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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


SQL Server Integration Services is a platform for building enterprise-level data integration and data 
transformations solutions. Use Integration Services to solve complex business problems by copying or 


downloading files, loading data warehouses, cleansing and mining data, and managing SQL Server objects and 
data. 


Integration Services can extract and transform data from a wide variety of sources such as XML data files, flat 
files, and relational data sources, and then load the data into one or more destinations. 


Integration Services includes a rich set of built-in tasks and transformations, graphical tools for building 
packages, and the Integration Services Catalog database, where you store, run, and manage packages. 


You can use the graphical Integration Services tools to create solutions without writing a single line of code. You 
can also program the extensive Integration Services object model to create packages programmatically and 
code custom tasks and other package objects. 


Get SQL Server Integration Services 


For info about installing SQL Server Integration Services with SQL Server, and about additional downloads you 
may want or need, see Install Integration Services. 


@® Resources 


© Get help in the SSIS forum 

@ Get help on Stack Overflow 

e Follow the SSIS team blog 

e Report issues & request features 


@ Get the docs on your PC 


What's New in Integration Services in SQL Server 


PAU IC 


11/23/2021 + 16 minutes to read « Edit Online 





Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


This topic describes the features that have been added or updated in SQL Server 2016 Integration Services. It 
also includes features added or updated in the Azure Feature Pack for Integration Services (SSIS) during the SQL 
Server 2016 time frame. 


New for SSIS in Azure Data Factory 


With the public preview of Azure Data Factory version 2 in September 2017, you can now do the following 
things: 


e Deploy packages to the SSIS Catalog database (SSISDB) on Azure SQL Database. 


e Run packages deployed to Azure on the Azure-SSIS Integration Runtime, a component of Azure Data Factory 
version 2. 


For more info, see Lift and shift SQL Server Integration Services workloads to the cloud. 


These new capabilities require SQL Server Data Tools (SSDT) version 17.2 or later, but do not require SQL Server 
2017 or SQL Server 2016. When you deploy packages to Azure, the Package Deployment Wizard always 
upgrades the packages to the latest package format. 


2016 improvements by category 
e Manageability 
o Better deployment 
o SSISDB Upgrade Wizard 
o Support for Always On in the SSIS Catalog 
o Incremental package deployment 
o Support for Always Encrypted in the SSIS Catalog 
o Better debugging 
© New ssis_logreader database-level role in the SSIS catalog 
o New RuntimeLineage logging level in the SSIS catalog 
o New custom logging level in the SSIS catalog 
o Column names for errors in the data flow 
o Expanded support for error column names 
o Support for server-wide default logging level 
o New IDTSComponentMetaData1 30 interface in the API 


o Better package management 


O° 


° 


° 


° 


Improved experience for project upgrade 
AutoAdjustBufferSize property automatically calculates buffer size for data flow 
Reusable control flow templates 


New templates renamed as parts 


e Connectivity 


o Expanded connectivity on premises 


O° 


ie) 


Support for OData v4 data sources 

Explicit support for Excel 2013 data sources 

Support for the Hadoop file system (HDFS) 
Expanded support for Hadoop and HDFS 

HDFS File Destination now supports ORC file format 
ODBC components updated for SQL Server 2016 
Explicit support for Excel 2016 data sources 
Connector for SAP BW for SQL Server 2016 released 
Connectors v4.0 for Oracle and Teradata released 


Connectors for Analytics Platform System (PDW) Appliance Update 5 released 


o Expanded connectivity to the cloud 


O° 


° 


° 


O° 


Azure Storage connectors and Hive and Pig tasks for HDInsight - Azure Feature Pack for 
SSIS released for SQL Server 2016 


Support for Microsoft Dynamics online resources released in Service Pack 1 
Support for Azure Data Lake Store released 


Support for Azure Synapse Analytics released 


e Usability and productivity 


° 


Better install experience 


° 


Upgrade blocked when SSISDB belongs to an Availability Group 


Better design experience 


° 


° 


SSIS Designer creates and maintains packages for SQL Server 2016, 2014, or 2012 


Multiple designer improvements and bug fixes. 


Better management experience in SQL Server Management Studio 


° 


Improved performance for SSIS Catalog views 


Other enhancements 


° 


° 


° 


Balanced Data Distributor transformation is now part of SSIS 
Data Feed Publishing Components are now part of SSIS 


Support for Azure Blob Storage in the SQL Server Import and Export Wizard 


o Change Data Capture Designer and Service for Oracle for Microsoft SQL Server 2016 
released 


o CDC components updated for SQL Server 2016 
o Analysis Services Execute DDL Task updated 

o Analysis Services tasks support tabular models 
© Support for Built-in R Services 


o Rich XML validation output in the XML Task 


Manageability 


Better deployment 
SSISDB Upgrade Wizard 


Run the SSISDB Upgrade Wizard to upgrade the SSIS Catalog database, SSISDB, when the database is older than 
the current version of the SQL Server instance. This occurs when one of the following conditions is true. 


e You restored the database from an older version of SQL Server. 


e You did not remove the database from an Always On Availability Group before upgrading the SQL Server 
instance. This prevents the automatic upgrade of the database. For more info, see Upgrading SSISDB in 
an availability group. 


For more info, see SSIS Catalog (SSISDB). 


Support for Always On in the SSIS Catalog 

The Always On Availability Groups feature is a high-availability and disaster-recovery solution that provides an 
enterprise-level alternative to database mirroring. An availability group supports a failover environment for a 
discrete set of user databases known as availability databases that fail over together. For more information, see 
Always On Availability Groups. 


In SQL Server 2016, SSIS introduces new capabilities that let you easily deploy to a centralized SSIS Catalog (i.e. 
SSISDB user database). In order to provide high availability for the SSISDB database and its contents - projects, 
packages, execution logs, and so on - you can add the SSISDB database to an Always On Availability Group, just 
like any other user database. When a failover occurs, one of the secondary nodes automatically becomes the 


new primary node. 


For a detailed overview and step-by-step instructions for enabling Always On for SSISDB, see SSIS Catalog. 


Incremental package deployment 

The Incremental Package Deployment feature lets you deploy one or more packages to an existing or new 
project without deploying the whole project. You can incrementally deploy packages by using the following 
tools. 


e Deployment Wizard 

e SQL Server Management Studio (which uses the Deployment Wizard) 

e@ SQL Server Data Tools (Visual Studio) (which also uses the Deployment Wizard) 
e Stored procedures 

e The Management Object Model (MOM) API 


For more info, see Deploy Integration Services (SSIS) Projects and Packages. 


Support for Always Encrypted in the SSIS Catalog 


SSIS already supports the Always Encrypted feature in SQL Server. For more info, see the following blog posts. 


e SSIS with Always Encrypted 
e Lookup transformation with Always Encrypted 


Better debugging 

New ssis_logreader database-level role in the SSIS catalog 

In previous versions of the SSIS catalog, only users in the ssis_admin role can access the views that contain 
logging output. There is now a new ssis_logreader database-level role that you can use to grant permissions 
to access the views that contain logging output to users who aren't administrators. 


There is also a new ssis_monitor role. This role supports Always On and is for internal use only by the SSIS 


catalog. 


New RuntimeLineage logging level in the SSIS catalog 

The new RuntimeLineage logging level in the SSIS catalog collects the data required to track lineage 
information in the data flow. You can parse this lineage information to map the lineage relationship between 
tasks. ISVs and developers can build custom lineage mapping tools with this information. 


New custom logging level in the SSIS catalog 

Previous versions of the SSIS catalog let you choose from four built-in logging levels when you run a package: 
None, Basic, Performance, or Verbose. SQL Server 2016 adds the RuntimeLineage logging level. In 
addition, you can now create and save multiple customized logging levels in the SSIS catalog, and pick the 
logging level to use every time you run a package. For each customized logging level, select only the statistics 
and events you want to capture. Optionally include the event context to see variable values, connection strings, 
and task properties. For more info, see Enable Logging for Package Execution on the SSIS Server. 


Column names for errors in the data flow 

When you redirect rows in the data flow that contain errors to an error output, the output contains a numeric 
identifier for the column in which the error occurred, but does not display the name of the column. There are 
now several ways to find or display the name of the column in which the error occurred. 


e When you configure logging, select the DiagnosticEx event for logging. This event writes a data flow 
column map to the log. You can then look up the column name in this column map by using the column 
identifier captured by an error output. For more info, see Error Handling in Data. 


e Inthe Advanced Editor, you can see the column name for the upstream column when you view the 


properties of an input or output column of a data flow component. 


@ To see the names of the columns in which the error occurred, attach a Data Viewer to an error output. The 
Data Viewer now displays both the description of the error and the name of the column in which the 


error occurred. 


e Inthe Script Component or a custom data flow component, call the new GetldentificationStringBy!ID 
method of the IDTSComponentMetadata1 00 interface. 


For more info about this improvement, see the following blog post by SSIS developer Bo Fan: Error Column 
Improvements for SSIS Data Flow. 


NOTE 


(This support has been expanded in subsequent releases. For more info, see Expanded support for error column names 
and New IDTSComponentMetaData130 interface in the API.) 





Expanded support for error column names 
The DiagnosticEx event now logs column information for all input and output columns, not just lineage 


columns. As a result we now call the output a pipeline column map instead of a pipeline lineage map. 


The method GetldentificationStringByLineagelD has been renamed to GetldentificationStringBy!D. For more info, 
see Column names for errors in the data flow. 


For more info about this change and about the error column improvement, see the following updated blog post. 
Error Column Improvements for SSIS Data Flow (Updated for CTP3.3) 





NOTE 


(In RCO, this method has been moved to the new IDTSComponentMetaData1 30 interface. For more info, see New 
IDTSComponentMetaData1 30 interface in the API.) 











Support for server-wide default logging level 

In SQL Server Server Properties, under the Server logging level property, you can now select a default 
server-wide logging level. You can pick from one of the built-in logging levels - basic, none, verbose, 
performance, or runtime lineage - or you can pick an existing customized logging level. The selected logging 
level applies to all packages deployed to the SSIS Catalog. It also applies by default to a SQL Agent job step that 
runs an SSIS package. 


New IDTSComponentMetaData130 interface in the API 

The new IDTSComponentMetaData130 interface adds new functionality in SQL Server 2016 to the existing 
IDTSComponentMetaData1 00 interface, especially the GetldentificationStringByID method. (The 
GetldentificationStringByID method is moved to the new interface from the IDTSComponentMetaData100 
interface.) There are also new IDTSInputColumn130 and IDTSOutputColumn130 interfaces, both of which 
provide the LineageldentificationString property. For more info, see Column names for errors in the data 
flow. 


Better package management 

Improved experience for project upgrade 

When you upgrade SSIS projects from previous versions to the current version, the project-level connection 
managers continue to work as expected and the package layout and annotations are retained. 


AutoAdjustBufferSize property automatically calculates buffer size for data flow 
When you set the value of the new AutoAdjustBufferSize property to true, the data flow engine automatically 
calculates the buffer size for the data flow. For more info, see Data Flow Performance Features. 


Reusable control flow templates 

Save a commonly used control flow task or container to a standalone template file and reuse it multiple times in 
one or more packages in a project by using control flow templates. This reusability makes SSIS packages easier 
to design and maintain. For more info, see Reuse Control Flow across Packages by Using Control Flow Package 
Parts. 


New templates renamed as parts 

The new reusable control flow templates released in CTP 3.0 have been renamed as control flow parts or 
package parts. For more info about this feature, see Reuse Control Flow across Packages by Using Control Flow 
Package Parts. 


Connectivity 


Expanded connectivity on premises 
Support for OData v4 data sources 


The OData Source and the OData Connection Manager now support the OData v3 and v4 protocols. 
e For OData V3 protocol, the component supports the ATOM and JSON data formats . 


e For OData V4 protocol, the component supports the JSON data format . 


For more info, see OData Source. 


Explicit support for Excel 2013 data sources 
The Excel Connection Manager, the Excel Source and the Excel Destination, and the SQL Server Import and 
Export Wizard now provide explicit support for Excel 2013 data sources. 


Support for the Hadoop file system (HDFS) 
Support for HDFS contains connection managers to connect to Hadoop clusters and tasks to do common HDFS 
operations. For more info, see Hadoop and HDFS Support in Integration Services (SSIS). 


Expanded support for Hadoop and HDFS 
@ The Hadoop Connection Manager now supports both Basic and Kerberos authentication. For more info, 
see Hadoop Connection Manager. 


e@ The HDFS File Source and the HDFS File Destination how support both Text and Avro format. For more 
info, see HDFS File Source and HDFS File Destination. 


e The Hadoop File System task now supports the CopyWithinHadoop option in addition to the 
CopyToHadoop and the CopyFromHadoop options. For more info, see Hadoop File System Task. 


HDFS File Destination now supports ORC file format 
The HDFS File Destination now supports the ORC file format in addition to Text and Avro. (The HDFS File Source 
supports only Text and Avro.) For more info about this component, see HDFS File Destination. 


ODBC components updated for SQL Server 2016 
The ODBC Source and Destination components have been updated to provide full compatibility with SQL Server 
2016. There is no new functionality and there are no changes in behavior. 


Explicit support for Excel 2016 data sources 
The Excel Connection Manager, the Excel Source, and the Excel Destination now provide explicit support for Excel 
2016 data sources. 


Connector for SAP BW for SQL Server 2016 released 

The MicrosoftA(®) Connector for SAP BW for Microsoft SQL ServerAQ®) 2016 has been released as part of the 
SQL Server 2016 Feature Pack. To download components of the Feature Pack, see MicrosoftA(®) SQL 
ServerA(®) 2016 Feature Pack. 


Connectors v4.0 for Oracle and Teradata released 
The Microsoft Connectors v4.0 for Oracle and Teradata have been released. To download the connectors, see 
Microsoft Connectors v4.0 for Oracle and Teradata. 


Connectors for Analytics Platform System (PDW) Appliance Update 5 released 


The destination adapters for loading data into PDW with AU5 have been released. To download the adapters, see 
Analytics Platform System Appliance Update 5 Documentation and Client Tools. 


Expanded connectivity to the cloud 

Azure Feature Pack for SSIS released for SQL Server 2016 

The Azure Feature Pack for Integration Services has been released for SQL Server 2016. The feature pack 
contains connection managers to connect to Azure data sources and tasks to do common Azure operations. For 


more info, see Azure Feature Pack for Integration Services (SSIS). 


Support for Microsoft Dynamics online resources released in Service Pack 1 
With SQL Server 2016 Service Pack 1 installed, the OData Source and OData Connection Manager now support 
connecting to the OData feeds of Microsoft Dynamics AX Online and Microsoft Dynamics CRM Online. 


Support for Azure Data Lake Store released 
The latest version of the Azure Feature Pack includes a connection manager, source, and destination to move 


data to and from Azure Data Lake Store. For more info, see Azure Feature Pack for Integration Services (SSIS) 


Support for Azure Synapse Analytics released 


The latest version of the Azure Feature Pack includes the Azure SQL DW Upload task for populating Azure 
Synapse Analytics with data. For more info, see Azure Feature Pack for Integration Services (SSIS) 


Usability and productivity 


Better install experience 

Upgrade blocked when SSISDB belongs to an Availability Group 

If the SSIS catalog database (SSISDB) belongs to an Always On Availability Group, you have to remove SSISDB 
from the availability group, upgrade SQL Server, then add SSISDB back to the availability group. For more info, 
see Upgrading SSISDB in an availability group. 


Better design experience 

Multi-targeting and multi-version support in SSIS Designer 

You can now use SSIS Designer in SQL Server Data Tools (SSDT) for Visual Studio 2015 to create, maintain, and 
run packages that target SQL Server 2016, SQL Server 2014, or SQL Server 2012. To get SSDT, see Download 
Latest SQL Server Data Tools. 


In Solution Explorer, right-click on an Integration Services project and select Properties to open the property 
pages for the project. On the General tab of Configuration Properties, select the TargetServerVersion 
property, and then choose SQL Server 2016, SQL Server 2014, or SQL Server 2012. 


Configuration: Active(Development) Platform: N/A v Configuration Manager... 


4 Common Properties ¥ Deployment Target Version 
Project EL S01 server 2017 io 


4 Configuration Properties SQL Server 2012 
General SQL Server 2014 
Build SQL Server 2016 
Deployment SQL Server 2017 
Debugging 


TargetServerVersion 
Specifies the version that is used to save, deploy, execute and debug packages in ... 


OK Cancel 


IMPORTANT 


If you develop custom extensions for SSIS, see Support multi-targeting in your custom components and Getting your 


SSIS custom extensions to be supported by the multi-version support of SSDT 2015 for SQL Server 2016. 





Better management experience in SQL Server Management Studio 
Improved performance for SSIS Catalog views 
Most SSIS catalog views now perform better when they're run by a user who is not a member of the ssis_admin 


role. 


Other enhancements 

Balanced Data Distributor transformation is now part of SSIS 

The Balanced Data Distributor transformation, which required a separate download in previous versions of SQL 
Server, is now installed when you install Integration Services. For more info, see Balanced Data Distributor 


Transformation. 


Data Feed Publishing Components are now part of SSIS 


The Data Feed Publishing Components, which required a separate download in previous versions of SQL Server, 


are now installed when you install Integration Services. For more info, see Data Streaming Destination. 


Support for Azure Blob Storage in the SQL Server Import and Export Wizard 

The SQL Server Import and Export Wizard can now import data from, and save data to, Azure Blob Storage. For 
more info, see Choose a Data Source (SQL Server Import and Export Wizard) and Choose a Destination (SQL 
Server Import and Export Wizard). 


Change Data Capture Designer and Service for Oracle for Microsoft SQL Server 2016 released 

The Microsoft(R) Change Data Capture Designer and Service for Oracle by Attunity for Microsoft SQL 
ServerAQ®) 2016 have been released as part of the SQL Server 2016 Feature Pack. These components now 
support Oracle 12c in classic installation. (Multitenant installation is not supported) To download components of 
the Feature Pack, see MicrosoftA®) SQL ServerAQ®) 2016 Feature Pack. 


CDC components updated for SQL Server 2016 

The CDC (Change Data Capture) Control Task, Source, and Splitter Transformation components have been 
updated to provide full compatibility with SQL Server 2016. There is no new functionality and there are no 
changes in behavior. 


Analysis Services Execute DDL Task updated 
The Analysis Services Execute DDL Task has been updated to accept Tabular Model Scripting Language 
commands. 


Analysis Services tasks support tabular models 

You can now use all the SSIS task and destinations that support SQL Server Analysis Services (SSAS) with SQL 
Server 2016 tabular models. The SSIS tasks have been updated to represent tabular objects instead of 
multidimensional objects. For example, when you select objects to process, the Analysis Services Processing 
Task automatically detects a Tabular model and displays a list of Tabular objects instead of showing measure 
groups and dimensions. The Partition Processing Destination now also shows tabular objects and supports 
pushing data into a partition. 


The Dimension Processing Destination does not work for Tabular models with the SQL 2016 compatibility level. 
The Analysis Services Processing Task and the Partition Processing Destination are all you need for tabular 
processing. 


Support for Built-in R Services 

SSIS already supports the built-in R services in SQL Server. You can use SSIS not only to extract data and load 
the output of analysis, but to build, run and periodically retrain R models. For more info, see the following log 
post. Operationalize your machine learning project using SQL Server 2016 SSIS and R Services. 


Rich XML validation output in the XML Task 

Validate XML documents and get rich error output by enabling the ValidationDetails property of the XML Task. 
Before the ValidationDetails property was available, XML validation by the XML Task returned only a true or 
false result, with no information about errors or their locations. Now, when you set ValidationDetails to true, 
the output file contains detailed information about every error including the line number and the position. You 
can use this information to understand, locate, and fix errors in XML documents. For more info, see Validate XML 
with the XML Task. 


SSIS introduced the ValidationDetails property in SQL Server 2012 (11.x) Service Pack 2. This new property 
was not announced or documented at that time. The ValidationDetails property is also available in SQL Server 
2014 (12.x) and in SQL Server 2016 (13.x). 


® Get help 


e UserVoice: Have suggestions for improving SQL Server? 
e Microsoft Q & A (SQL Server) 
e DBA Stack Exchange (tag sql-server): Ask SQL Server questions 


e Stack Overflow (tag sql-server): Answers to SQL development questions 


e Reddit: General discussion about SQL Server 

e Microsoft SQL Server License Terms and Information 
e Support options for business users 

© Contact Microsoft 

e Additional SQL Server help and feedback 


“ Contribute to SQL documentation 


Did you know that you can edit SQL content yourself? If you do so, not only do you help improve our 


documentation, but you also get credited as a contributor to the page. 


For more information, see How to contribute to SQL Server documentation 
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Applies to: Q sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


This topic describes the features that have been added or updated in SQL Server 2017 (14.x) Integration 
Services. 


NOTE 


SQL Server 2017 also includes the features of SQL Server 2016 and the features added in SQL Server 2016 updates. For 
info about the new SSIS features in SQL Server 2016, see What's New in Integration Services in SQL Server 2016. 











Highlights of this release 
Here are the most important new features of Integration Services in SQL Server 2017. 


e Scale Out. Distribute SSIS package execution more easily across multiple worker computers, and 
manage executions and workers from a single master computer. For more info, see Integration Services 
Scale Out. 


e Integration Services on Linux. Run SSIS packages on Linux computers. For more info, see Extract, 
transform, and load data on Linux with SSIS. 


e Connectivity improvements. Connect to the OData feeds of Microsoft Dynamics AX Online and 
Microsoft Dynamics CRM Online with the updated OData components. 


New in Azure Data Factory 


With the public preview of Azure Data Factory version 2 in September 2017, you can now do the following 
things: 


e Deploy packages to the SSIS Catalog database (SSISDB) on Azure SQL Database. 


e Run packages deployed to Azure on the Azure-SSIS Integration Runtime, a component of Azure Data Factory 
version 2. 


For more info, see Lift and shift SQL Server Integration Services workloads to the cloud. 


These new capabilities require SQL Server Data Tools (SSDT) version 17.2 or later, but do not require SQL Server 
2017 or SQL Server 2016. When you deploy packages to Azure, the Package Deployment Wizard always 
upgrades the packages to the latest package format. 


New in the Azure Feature Pack 


In addition to the connectivity improvements in SQL Server, the Integration Services Feature Pack for Azure has 
added support for Azure Data Lake Store. For more info, see the blog post New Azure Feature Pack Release 
Strengthening ADLS Connectivity. Also see Azure Feature Pack for Integration Services (SSIS). 


New in SQL Server Data Tools (SSDT) 


You can now develop SSIS projects and packages that target SQL Server versions 2012 through 2017 in Visual 
Studio 2017 or in Visual Studio 2015. For more info, see Download SQL Server Data Tools (SSDT). 


New in SSIS in SQL Server 2017 RC1 


New and changed features in Scale Out for SSIS 


e Scale Out Master now supports high availability. You can enable Always On for SSISDB and set up Windows 
Server failover clustering for the server that hosts the Scale Out Master service. By applying this change to 


Scale Out Master, you avoid a single point of failure and provide high availability for the entire Scale Out 
deployment. 


The failover handling of the execution logs from Scale Out Workers is improved. The execution logs are 
persisted to local disk in case the Scale Out Worker stops unexpectedly. Later, when the worker restarts, it 
reloads the persisted logs and continues saving them to SSISDB. 
e The parameter runincluster of the stored procedure [catalog].[create_execution] is renamed to 
runinscaleout for consistency and readability. This change of parameter name has the following impact: 
o If you have existing scripts to run packages in Scale Out, you have to change the parameter name 
from runincluster to runinscaleout to make the scripts work in RC1. 
© SQL Server Management Studio (SSMS) 17.1 and earlier versions can't trigger package execution in 
Scale Out in RC1. The error message is: "@runincluster is not a parameter for procedure 
create_execution." This issue is fixed in the next release of SSMS, version 17.2. Version 17.2 and later 
of SSMS support the new parameter name and package execution in Scale Out. Until SSMS version 
17.2 is available, as a workaround, you can use your existing version of SSMS to generate the package 
execution script, then change the name of the runincluster parameter to runinsca/eout in the script, 
and run the script. 
e The SSIS Catalog has a new global property to specify the default mode for executing SSIS packages. This 
new property applies when you call the [catalog].[create_execution] stored procedure with the 
runinscaleout parameter set to null. This mode also applies to SSIS SQL Agent jobs. You can set the new 
global property in the Properties dialog box for the SSISDB node in SSMS, or with the following command: 


EXEC [catalog].[configure_catalog] @property_name=N'DEFAULT_EXECUTION_MODE', @property_value=1 


New in SSIS in SQL Server 2017 CTP 2.1 


New and changed features in Scale Out for SSIS 

e You can now use the Use32BitRuntime parameter when you trigger execution in Scale Out. 

e The performance of logging to SSISDB for package executions in Scale Out has been improved. The Event 
Message and Message Context logs are now written to SSISDB in batch mode instead of one by one. Here 
are some additional notes about this improvement: 

o Some reports in the current version of SQL Server Management Studio (SSMS) don't currently display 
these logs for executions in Scale Out. We anticipate that they will be supported in the next release of 
SSMS. The affected reports include the A// Connections report, the Error Context report, and the 
Connection Information section in the Integration Service Dashboard. 

o Anew column event_message_guid has been added. Use this column to join the [catalog]. 
[event_message_context] view and the [catalog].[event_messages] view instead of using 
event_message_id when you query these logs of executions in Scale Out. 


@ To get the management application for SSIS Scale Out, download SQL Server Management Studio (SSMS) 
17.1 or later. 


New in SSIS in SQL Server 2017 CTP 2.0 


There are no new SSIS features in SQL Server 2017 CTP 2.0. 


New in SSIS in SQL Server 2017 CTP 1.4 


There are no new SSIS features in SQL Server 2017 CTP 1.4. 


New in SSIS in SQL Server 2017 CTP 1.3 


There are no new SSIS features in SQL Server 2017 CTP 1.3. 


New in SSIS in SQL Server 2017 CTP 1.2 


There are no new SSIS features in SQL Server 2017 CTP 1.2. 


New in SSIS in SQL Server 2017 CTP 1.1 


There are no new SSIS features in SQL Server 2017 CTP 1.1. 


New in SSIS in SQL Server 2017 CTP 1.0 


Scale Out for SSIS 
The Scale Out feature makes it much easier to run SSIS on multiple machines. 
After installing the Scale Out Master and Workers, the package can be distributed to execute on different 


Workers automatically. If the execution is terminated unexpectedly, the execution is retried automatically. Also, 
all the executions and Workers can be centrally managed using the Master. 


For more information, see Integration Services Scale Out. 


Support for Microsoft Dynamics Online Resources 


The OData Source and OData Connection Manager now support connecting to the OData feeds of Microsoft 
Dynamics AX Online and Microsoft Dynamics CRM Online. 


Integration Services features supported by the 


editions of SQL Server 
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Applies to: Q sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


This topic provides details about the features of SQL Server Integration Services (SSIS) supported by the 
different editions of SQL Server. 


For features supported by Evaluation and Developer editions, see features listed for Enterprise Edition in the 
following tables. 


For the latest release notes and what's new information, see the following articles: 


e SQL Server 2016 release notes 
e What's New in Integration Services in SQL Server 2016 


e What's New in Integration Services in SQL Server 2017 
Try SQL Server 2016! 


The SQL Server Evaluation edition is available for a 180-day trial period. 


Download SQL Server 2016 from the Evaluation Center 


New Integration Services features in SQL Server 2017 


EXPRESS WITH 
ADVANCED 
FEATURE ENTERPRISE STANDARD WEB SERVICES EXPRESS 


Scale Out Master Yes 


Scale Out Yes Yes | TBD TBD TBD 
Worker 


Support for Yes Yes 
Microsoft 

Dynamics AX 

and Microsoft 

Dynamics CRM 

in OData 

components 2 


Linux support Yes Yes Yes 


' If you run packages that require Enterprise-only features in Scale Out, the Scale Out Workers must also run on 
instances of SQL Server Enterprise. 


* This feature is also supported in SQL Server 2016 with Service Pack 1. 


SQL Server Import and Export Wizard 


EXPRESS WITH 


ADVANCED 
FEATURE ENTERPRISE STANDARD WEB SERVICES EXPRESS 
SQL Server Yes Yes Yes Yes! Yes! 
Import and 
Export Wizard 


' DTSWizard.exe is not provided with SQL on Linux. However, dtexec on Linux can be used to execute a package 
created by DTSWizard on Windows. 


Integration Services 


EXPRESS WITH 
ADVANCED 
FEATURE ENTERPRISE STANDARD WEB SERVICES EXPRESS 


Built-in data Yes Yes 
source 

connectors 

Built in tasks and Yes Yes 


transformations 


ODBC source Yes Yes 
and destination 


Azure data Yes Yes 
source 

connectors and 

tasks 


Hadoop/HDFS Yes Yes 
connectors and 
tasks 


Basic data Yes Yes 
profiling tools 


Integration Services - Advanced sources and destinations 


EXPRESS WITH 
ADVANCED 
FEATURE ENTERPRISE STANDARD WEB SERVICES EXPRESS 


High- Yes 
performance 

Oracle source 

and destination 

by Attunity 


High- Yes 
performance 

Teradata source 

and destination 

by Attunity 


EXPRESS WITH 
ADVANCED 
FEATURE ENTERPRISE STANDARD WEB SERVICES EXPRESS 


SAP BW source Yes 
and destination 


Data mining Yes 
model training 
destination 


Dimension Yes 
processing 
destination 


Partition Yes 
processing 
destination 


Integration Services - Advanced tasks and transformations 


EXPRESS WITH 
ADVANCED 
FEATURE ENTERPRISE STANDARD WEB SERVICES EXPRESS 


Change Data Yes 
Capture 

components by 

Attunity ' 


Data mining Yes 


query 
transformation 


Fuzzy grouping Yes 
and fuzzy lookup 
transformations 


Term extraction Yes 
and term lookup 
transformations 


1 The Change Data Capture components by Attunity require Enterprise edition. The Change Data Capture 
Service and the Change Data Capture Designer, however, do not require Enterprise edition. You can use the 
Designer and the Service on a computer where SSIS is not installed. 


Integration Services Developer Documentation 
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Integration Services includes a completely rewritten object model, which has been enhanced with many features 
that make extending and programming packages easier, more flexible, and more powerful. Developers can 
extend and program almost every aspect of Integration Services packages. 


As an Integration Services developer, there are two fundamental approaches that you can take to Integration 
Services programming: 


e You can extend packages by writing components that become available within SSIS Designer to provide 
custom functionality in a package. 


e You can create, configure, and run packages programmatically from your own applications. 


If you find that the built-in components in Integration Services do not meet your requirements, you can extend 
the power of Integration Services by coding your own extensions. In this approach, you have two discrete 
options: 


e For ad hoc use in a single package, you can create a custom task by writing code in the Script task, or a 
custom data flow component by writing code in the Script component, which you can configure as a 
source, transformation, or destination. These powerful wrappers write the infrastructure code for you and 
let you focus exclusively on developing your custom functionality; however, they are not easily reusable 
elsewhere. 


e For use in multiple packages, you can create custom Integration Services extensions such as connection 
managers, tasks, enumerators, log providers, and data flow components. The managed Integration 
Services object model contains base classes that provide a starting point and make developing custom 
extensions easier than ever. 


If you want to create packages dynamically, or to manage and run Integration Services packages outside the 
development environment, you can manipulate packages programmatically. You can load, modify, and run 
existing packages, or you can create and run entirely new packages programmatically. In this approach, you 
have a continuous range of options: 


e Load and run an existing package without modification. 
e Load an existing package, reconfigure it (for example, specify a different data source), and run it. 


e Create a new package, add and configure components, making changes object by object and property by 
property, save it, and then run it. 


These approaches to Integration Services programming are described in this section and demonstrated with 
examples. 


In This Section 


Integration Services Programming Overview 
Describes the roles of control flow and data flow in Integration Services development. 


Understanding Synchronous and Asynchronous Transformations 


Describes the important distinction between synchronous and asynchronous outputs and the components that 


use them in the data flow. 


Working with Connection Managers Programmatically 
Lists the connection managers that you can use from managed code, and the values that the connection 
managers return when the code calls the AcquireConnection method. 


Extending Packages with Scripting 
Describes how to extend the control flow by using the Script task, or the data flow by using the Script 


component. 


Extending Packages with Custom Objects 
Describes how to create and program custom tasks, data flow components, and other package objects for use in 
multiple packages. 


Building Packages Programmatically 
Describes how to create, configure, and save Integration Services packages programmatically. 


Running and Managing Packages Programmatically 
Describes how to enumerate, run, and manage Integration Services packages programmatically. 


Reference 


Integration Services Error and Message Reference 
Lists the predefined Integration Services error codes, together with their symbolic names and descriptions. 


Related Sections 


Troubleshooting Tools for Package Development 
Describes the features and tools that Integration Services provides for troubleshooting packages during 
development. 


See Also 


SQL Server Integration Services 


Integration Services Backward Compatibility 
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This topic describes changes between versions of SQL Server Integration Services. It covers features that are no 
longer available or are scheduled to be removed in a future release. It also describes changes to the product that 
are known to break, or to change the behavior of, an existing application that includes Integration Services 
functionality. 


Deprecated Integration Services Features 


This section describes deprecated Integration Services features that are still available in the current release of 
SQL Server Integration Services. These features are scheduled to be removed in a future release of SQL Server. 
Do not use deprecated features in new applications. 


There are no deprecated Integration Services features in SQL Server 2019 (15.x). 


Discontinued Integration Services Functionality 


This section describes Integration Services features that are no longer available in the current release of SQL 
Server Integration Services. 


There are no discontinued Integration Services features in SQL Server 2019 (15.x). 


Breaking Changes to Integration Services Features 


This section describes breaking changes in Integration Services. These changes may break applications, scripts, 
or other items that are based on earlier versions of SQL Server. You may encounter these issues after you 
upgrade. 


There are no breaking changes to Integration Services features in SQL Server 2019 (15.x). 


Behavior Changes to Integration Services Features 


This section describes behavior changes in Integration Services. Behavior changes affect how features work or 
interact in the current release of SQL Server Integration Services when compared to earlier versions of SQL 
Server. 


There are no behavior changes for Integration Services features in SQL Server 2019 (15.x). 


Deploy an SSIS project with SQL Server 
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This quickstart how to use SQL Server Management Studio (SSMS) to connect to the SSIS Catalog database, and 
then run the Integration Services Deployment Wizard to deploy an SSIS project to the SSIS Catalog. 


SQL Server Management Studio is an integrated environment for managing any SQL infrastructure, from SQL 
Server to SQL Database. For more info about SSMS, see SQL Server Management Studio (SSMS). 


Prerequisites 


Before you start, make sure you have the latest version of SQL Server Management Studio. To download SSMS, 
see Download SQL Server Management Studio (SSMS). 


The validation described in this article for deployment to Azure SQL Database requires SQL Server Data Tools 
(SSDT) version 17.4 or later. To get the latest version of SSDT, see Download SQL Server Data Tools (SSDT). 


An Azure SQL Database server listens on port 1433. If you're trying to connect to an Azure SQL Database server 
from within a corporate firewall, this port must be open in the corporate firewall for you to connect successfully. 


Supported platforms 
You can use the information in this quickstart to deploy an SSIS project to the following platforms: 
e@ SQL Server on Windows. 


e Azure SQL Database. For more info about deploying and running packages in Azure, see Lift and shift 
SQL Server Integration Services workloads to the cloud. 


You cannot use the information in this quickstart to deploy an SSIS package to SQL Server on Linux. For more 
info about running packages on Linux, see Extract, transform, and load data on Linux with SSIS. 


For Azure SQL Database, get the connection info 


To deploy the project to Azure SQL Database, get the connection information you need to connect to the SSIS 
Catalog database (SSISDB). You need the fully qualified server name and login information in the procedures 
that follow. 


1. Log in to the Azure portal. 


2. Select SQL Databases from the left-hand menu, and then select the SSISDB database on the SQL 
databases page. 


3. On the Overview page for your database, review the fully qualified server name. To see the Click to copy 
option, hover over the server name. 


4. If you forget your Azure SQL Database server login information, navigate to the SQL Database server page 
to view the server admin name. You can reset the password if necessary. 


Authentication methods for deployment 


If you're deploying to a SQL Server with the Deployment Wizard, you have to use Windows authentication; you 
can't use SQL Server authentication. 


If you're deploying to an Azure SQL Database server, you have to use SQL Server authentication or Azure Active 
Directory authentication; you can't use Windows authentication. 


Connect to the SSISDB database 
Use SQL Server Management Studio to establish a connection to the SSIS Catalog. 
1. Open SQL Server Management Studio. 


2. In the Connect to Server dialog box, enter the following information: 


SETTING SUGGESTED VALUE MORE INFO 

Server type Database engine This value is required. 

Server name The fully qualified server name If you're connecting to an Azure 
SQL Database server, the name is in 
this format: 


<server_name>.database.windows.net 


Authentication SQL Server Authentication With SQL Server authentication, you 
can connect to SQL Server or to 
Azure SQL Database. See 
authentication methods in the 
deployment in this article. 


Login The server admin account This account is the account that you 
specified when you created the 
server. 

Password The password for your server admin This password is the password that 

account you specified when you created the 
server. 


3. Click Connect. The Object Explorer window opens in SSMS. 


4. In Object Explorer, expand Integration Services Catalogs and then expand SSISDB to view the objects 
in the SSIS Catalog database. 


Start the Integration Services Deployment Wizard 


1. In Object Explorer, with the Integration Services Catalogs node and the SSISDB node expanded, 
expand a folder. 


2. Select the Projects node. 


3. Right-click on the Projects node and select Deploy project. The Integration Services Deployment 
Wizard opens. You can deploy a project from the current catalog or from the file system. 


Deploy a project with the wizard 


1. On the Introduction page of the wizard, review the introduction. Click Next to open the Select Source 
page. 


2. On the Select Source page, select the existing SSIS project to deploy. 


@ To deploy a project deployment file that you created by building a project in the development 
environment, select Project deployment file and enter the path to the .ispac file. 


e To deploy a project that is already deployed to an SSIS catalog database, select Integration Services 
catalog, and then enter the server name and the path to the project in the catalog. Click Next to see 
the Select Destination page. 


3. On the Select Destination page, select the destination for the project. 


e Enter the fully qualified server name. If the target server is an Azure SQL Database server, the name is 


in this format <server_name>.database.windows.net . 


e Provide authentication information, and then select Connect. See authentication methods in the 
deployment in this article. 


e Then select Browse to select the target folder in SSISDB. 


e Then select Next to open the Review page. (The Next button is enabled only after you select 
Connect.) 


4. On the Review page, review the settings you selected. 


e You can change your selections by clicking Previous, or by clicking any of the steps in the left pane. 
e Click Deploy to start the deployment process. 

5. If you're deploying to an Azure SQL Database server, the Validate page opens and checks the packages 
in the project for known issues that may prevent the packages from running as expected in the Azure- 
SSIS Integration Runtime. For more info, see Validate SSIS packages deployed to Azure. 


6. After the deployment process is complete, the Results page opens. This page displays the success or 
failure of each action. 


e If the action failed, click Failed in the Result column to display an explanation of the error. 
@ Optionally, click Save Report... to save the results to an XML file. 


e Click Close to exit the wizard. 


Next steps 


e Consider other ways to deploy a package. 
o Deploy an SSIS package with Transact-SQL (SSMS) 
o Deploy an SSIS package with Transact-SQL (VS Code) 
o Deploy an SSIS package from the command prompt 
o Deploy an SSIS package with PowerShell 
o Deploy an SSIS package with C# 


e Runa deployed package. To run a package, you can choose from several tools and languages. For more info, 
see the following articles: 


o Runan SSIS package with SSMS 

o Runan SSIS package with Transact-SQL (SSMS) 

o Runan SSIS package with Transact-SQL (VS Code) 
o Runan SSIS package from the command prompt 
o Runan SSIS package with PowerShell 

o Runan SSIS package with C# 


Deploy an SSIS project from SSMS with Transact- 


SQL 
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This quickstart demonstrates how to use SQL Server Management Studio (SSMS) to connect to the SSIS Catalog 
database, and then use Transact-SQL statements to deploy an SSIS project to the SSIS Catalog. 


SQL Server Management Studio is an integrated environment for managing any SQL infrastructure, from SQL 
Server to SQL Database. For more info about SSMS, see SQL Server Management Studio (SSMS). 


Prerequisites 


Before you start, make sure you have the latest version of SQL Server Management Studio. To download SSMS, 
see Download SQL Server Management Studio (SSMS). 


Supported platforms 
You can use the information in this quickstart to deploy an SSIS project to the following platforms: 


e SQL Server on Windows. 


You cannot use the information in this quickstart to deploy an SSIS package to Azure SQL Database. The 
catalog.deploy_project stored procedure expects path to the .ispac file in the local (on premises) file system. 
For more info about deploying and running packages in Azure, see Lift and shift SQL Server Integration Services 

workloads to the cloud. 


You cannot use the information in this quickstart to deploy an SSIS package to SQL Server on Linux. For more 
info about running packages on Linux, see Extract, transform, and load data on Linux with SSIS. 


Supported authentication method 


Refer to authentication methods for deployment. 


Connect to the SSIS Catalog database 


Use SQL Server Management Studio to establish a connection to the SSIS Catalog. 
1. Open SQL Server Management Studio. 


2. In the Connect to Server dialog box, enter the following information: 


SETTING SUGGESTED VALUE MORE INFO 
Server type Database engine This value is required. 
Server name The fully qualified server name 


Authentication SQL Server Authentication 


3: 


4. 


SETTING SUGGESTED VALUE MORE INFO 


Login The server admin account This account is the account that you 
specified when you created the 
server. 

Password The password for your server admin This password is the password that 

account you specified when you created the 
server. 


Click Connect. The Object Explorer window opens in SSMS. 


In Object Explorer, expand Integration Services Catalogs and then expand SSISDB to view the objects 
in the SSIS Catalog database. 


Run the T-SQL code 


Run the following Transact-SQL code to deploy an SSIS project. 


1. 


2. 


In SSMS, open a new query window and paste the following code. 


Update the parameter values in the catalog.deploy_project stored procedure for your system. 


. Make sure that SSISDB is the current database. 
. Run the script. 


. In Object Explorer, refresh the contents of SSISDB if necessary and check for the project that you 


deployed. 


DECLARE @ProjectBinary AS varbinary(max) 
DECLARE @operation_id AS bigint 
SET @ProjectBinary = 
(SELECT * FROM OPENROWSET(BULK '<project_file_path>.ispac', SINGLE_BLOB) AS BinaryData) 


EXEC catalog.deploy_project @folder_name = '<target_folder>', 
@project_name = '<project_name’, 
@Project_Stream = @ProjectBinary, 
@operation_id = @operation_id out 


Next steps 


Consider other ways to deploy a package. 

o Deploy an SSIS package with SSMS 

o Deploy an SSIS package with Transact-SQL (VS Code) 
o Deploy an SSIS package from the command prompt 
o Deploy an SSIS package with PowerShell 

© Deploy an SSIS package with C# 


Run a deployed package. To run a package, you can choose from several tools and languages. For more info, 
see the following articles: 


o Runan SSIS package with SSMS 

o Runan SSIS package with Transact-SQL (SSMS) 

o Runan SSIS package with Transact-SQL (VS Code) 
o Runan SSIS package from the command prompt 


o Runan SSIS package with PowerShell 


o RunanSSIS package with C# 


Deploy an SSIS project from Visual Studio Code 


with Transact-SQL 
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This quickstart demonstrates how to use Visual Studio Code to connect to the SSIS Catalog database, and then 
use Transact-SQL statements to deploy an SSIS project to the SSIS Catalog. 


Visual Studio Code is a code editor for Windows, macOS, and Linux that supports extensions, including the 
mssql extension for connecting to Microsoft SQL Server, Azure SQL Database, or Azure Synapse Analytics. For 
more info about VS Code, see Visual Studio Code. 


Prerequisites 


Before you start, make sure you have installed the latest version of Visual Studio Code and loaded the mssql 
extension. To download these tools, see the following pages: 


e Download Visual Studio Code 


® mssql extension 


Supported platforms 
You can use the information in this quickstart to deploy an SSIS project to the following platforms: 


e SQL Server on Windows. 


You cannot use the information in this quickstart to deploy an SSIS package to Azure SQL Database. The 
catalog.deploy_project stored procedure expects path to the .ispac file in the local (on premises) file system. 
For more info about deploying and running packages in Azure, see Lift and shift SQL Server Integration Services 

workloads to the cloud. 


You cannot use the information in this quickstart to deploy an SSIS package to SQL Server on Linux. For more 
info about running packages on Linux, see Extract, transform, and load data on Linux with SSIS. 


Set language mode to SQL in VS Code 


To enable mssql commands and T-SQL Intellisense, set the language mode to SQL in Visual Studio Code. 
1. Open Visual Studio Code and then open a new window. 
2. Click Plain Text in the lower right-hand corner of the status bar. 


3. In the Select language mode drop-down menu that opens, select or enter SQL, and then press ENTER 
to set the language mode to SQL. 


Supported authentication method 


Refer to authentication methods for deployment. 


Connect to the SSIS Catalog database 


Use Visual Studio Code to establish a connection to the SSIS Catalog. 


12 


In VS Code, press CTRL+SHIFT+P (or F1) to open the Command Palette. 


. Type sqicon and press ENTER. 


Server instance. 


each value, press ENTER to continue. 


SETTING 


Server name 


Database name 


Authentication 


User name 


Password (SQL Login) 


Save Password? 


Enter a name for this profile 


SUGGESTED VALUE 


The fully qualified server name 


SSISDB 


SQL Login 


The server admin account 


The password for your server admin 
account 


Yes or No 


A profile name, such as 
mySsSISServer 


. Press ENTER to select Create Connection Profile. This step creates a connection profile for your SQL 


. Follow the prompts to specify the connection properties for the new connection profile. After specifying 


MORE INFO 


The name of the database to which 
to connect. 


This account is the account that you 
specified when you created the 
server. 


This password is the password that 
you specified when you created the 
server. 


If you do not want to enter the 
password each time, select Yes. 


A saved profile name speeds your 
connection on subsequent logins. 


5. Press the ESC key to close the info message that informs you that the profile is created and connected. 


6. Verify your connection in the status bar. 


Run the T-SQL code 


Run the following Transact-SQL code to deploy an SSIS project. 
1. In the Editor window, enter the following query in the empty query window. 
2. Update the parameter values in the catalog.deploy_project stored procedure for your system. 


3. Press CTRL+SHIFT+E to run the code and deploy the project. 


DECLARE @ProjectBinary AS varbinary(max) 
DECLARE @operation_id AS bigint 
SET @ProjectBinary = (SELECT * FROM OPENROWSET(BULK ‘<project_file_path>.ispac', SINGLE_BLOB) AS BinaryData) 


EXEC catalog.deploy_project @folder_name = '<target_folder>', 
@project_name = '<project_name', 
@Project_Stream = @ProjectBinary, 
@operation_id = @operation_id out 


Next steps 


e Consider other ways to deploy a package. 
© Deploy an SSIS package with SSMS 
© Deploy an SSIS package with Transact-SQL (SSMS) 
o Deploy an SSIS package from the command prompt 
© Deploy an SSIS package with PowerShell 
© Deploy an SSIS package with C# 


e Runa deployed package. To run a package, you can choose from several tools and languages. For more info, 
see the following articles: 


o Runan SSIS package with SSMS 

o Runan SSIS package with Transact-SQL (SSMS) 

o RunanSSIS package with Transact-SQL (VS Code) 
o RunanSSIS package from the command prompt 
o Runan SSIS package with PowerShell 

o Runan SSIS package with C# 


Deploy an SSIS project from the command prompt 


with |SDeploymentWizard.exe 


SV ey ACPA: maalialvics\smcona-s-le Mmm sfelim@)al ial=) 





Applies to: Q sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


This quickstart demonstrates how to deploy an SSIS project from the command prompt by running the 
Integration Services Deployment Wizard, IsDeploymentWizard.exe . 


For more info about the Integration Services Deployment Wizard, see Integration Services Deployment Wizard. 


Prerequisites 


The validation described in this article for deployment to Azure SQL Database requires SQL Server Data Tools 
(SSDT) version 17.4 or later. To get the latest version of SSDT, see Download SQL Server Data Tools (SSDT). 


An Azure SQL Database server listens on port 1433. If you're trying to connect to an Azure SQL Database server 
from within a corporate firewall, this port must be open in the corporate firewall for you to connect successfully. 


Supported platforms 
You can use the information in this quickstart to deploy an SSIS project to the following platforms: 
e@ SQL Server on Windows. 


e Azure SQL Database. For more info about deploying and running packages in Azure, see Lift and shift 
SQL Server Integration Services workloads to the cloud. 


You cannot use the information in this quickstart to deploy an SSIS package to SQL Server on Linux. For more 
info about running packages on Linux, see Extract, transform, and load data on Linux with SSIS. 


For Azure SQL Database, get the connection info 


To deploy the project to Azure SQL Database, get the connection information you need to connect to the SSIS 
Catalog database (SSISDB). You need the fully qualified server name and login information in the procedures 
that follow. 


1. Log in to the Azure portal. 


2. Select SQL Databases from the left-hand menu, and then select the SSISDB database on the SQL 
databases page. 


3. On the Overview page for your database, review the fully qualified server name. To see the Click to copy 
option, hover over the server name. 


4. lf you forget your Azure SQL Database server login information, navigate to the SQL Database server page 
to view the server admin name. You can reset the password if necessary. 


Supported authentication method 


Refer to authentication methods for deployment. 


Start the Integration Services Deployment Wizard 


1. Open a Command Prompt window. 
2. Run ISDeploymentWizard.exe . The Integration Services Deployment Wizard opens. 


If the folder that contains IsDeploymentWizard.exe is notin your path environment variable, you may 
have to use the cd command to change to its directory. For SQL Server 2017, this folder is typically 


C:\Program Files (x86)\Microsoft SQL Server\140\DTS\Binn . 


Deploy a project with the wizard 


1. On the Introduction page of the wizard, review the introduction. Click Next to open the Select Source 
page. 


2. On the Select Source page, select the existing SSIS project to deploy. 


e To deploy a project deployment file that you created by building a project in the development 
environment, select Project deployment file and enter the path to the .ispac file. 


e To deploy a project that is already deployed to an SSIS catalog database, select Integration Services 
catalog, and then enter the server name and the path to the project in the catalog. Click Next to see 
the Select Destination page. 


3. On the Select Destination page, select the destination for the project. 


e Enter the fully qualified server name. If the target server is an Azure SQL Database server, the name is 


in this format <server_name>.database.windows.net . 


e Provide authentication information, and then select Connect. See authentication methods for 
deployment in this article. 


e Then select Browse to select the target folder in SSISDB. 


e Then select Next to open the Review page. (The Next button is enabled only after you select 
Connect.) 


4. On the Review page, review the settings you selected. 


e You can change your selections by clicking Previous, or by clicking any of the steps in the left pane. 
e Click Deploy to start the deployment process. 


5. If you're deploying to an Azure SQL Database server, the Validate page opens and checks the packages 
in the project for known issues that may prevent the packages from running as expected in the Azure- 
SSIS Integration Runtime. For more info, see Validate SSIS packages deployed to Azure. 


6. After the deployment process is complete, the Results page opens. This page displays the success or 
failure of each action. 


e If the action failed, click Failed in the Result column to display an explanation of the error. 
@ Optionally, click Save Report... to save the results to an XML file. 


e Click Close to exit the wizard. 


Next steps 


e@ Consider other ways to deploy a package. 
© Deploy an SSIS package with SSMS 
© Deploy an SSIS package with Transact-SQL (SSMS) 
© Deploy an SSIS package with Transact-SQL (VS Code) 
© Deploy an SSIS package with PowerShell 
© Deploy an SSIS package with C# 


e Runa deployed package. To run a package, you can choose from several tools and languages. For more info, 
see the following articles: 


Run an SSIS package with SSMS 

Run an SSIS package with Transact-SQL (SSMS) 
Run an SSIS package with Transact-SQL (VS Code) 
Run an SSIS package from the command prompt 
Run an SSIS package with PowerShell 

Run an SSIS package with C# 


Deploy an SSIS project with PowerShell 
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This quickstart demonstrates how to use a PowerShell script to connect to a database server and deploy an SSIS 
project to the SSIS Catalog. 


Prerequisites 


An Azure SQL Database server listens on port 1433. If you're trying to connect to an Azure SQL Database server 
from within a corporate firewall, this port must be open in the corporate firewall for you to connect successfully. 


Supported platforms 
You can use the information in this quickstart to deploy an SSIS project to the following platforms: 
e SQL Server on Windows. 


e Azure SQL Database. For more info about deploying and running packages in Azure, see Lift and shift 
SQL Server Integration Services workloads to the cloud. 


You cannot use the information in this quickstart to deploy an SSIS package to SQL Server on Linux. For more 
info about running packages on Linux, see Extract, transform, and load data on Linux with SSIS. 


For Azure SQL Database, get the connection info 


To deploy the project to Azure SQL Database, get the connection information you need to connect to the SSIS 
Catalog database (SSISDB). You need the fully qualified server name and login information in the procedures 
that follow. 


1. Sign in to the Azure portal. 


2. Select SQL Databases from the left-hand menu, and then select the SSISDB database on the SQL 
databases page. 


3. On the Overview page for your database, review the fully qualified server name. To see the Click to copy 
option, hover over the server name. 


4. If you forget your Azure SQL Database server login information, navigate to the SQL Database server page 
to view the server admin name. You can reset the password if necessary. 


5. Click Show database connection strings. 


6. Review the complete ADO.NET connection string. 


Supported authentication method 


Refer to authentication methods for deployment. 


SSIS PowerShell Provider 


Provide appropriate values for the variables at the top of the following script, and then run the script to deploy 
the SSIS project. 





NOTE 


The following example uses Windows Authentication to deploy to a SQL Server on premises. Use the New-PSDive cmdlet 
to establish a connection using SQL Server authentication. If you're connecting to an Azure SQL Database server, you 
can't use Windows authentication. 











# Variables 

$TargetInstanceName = “localhost\default" 

$TargetFolderName = "ProjectiFolder" 

$ProjectFilePath = "C:\Projects\Integration Services Project1\Integration Services 
Projecti\bin\Development\Integration Services Project1.ispac" 

$ProjectName = "Integration Services Project1" 


# Get the Integration Services catalog 
$catalog = Get-Item SQLSERVER: \SSIS\$TargetInstanceName\Catalogs\SSISDB\ 


# Create the target folder 

New-Object "Microsoft.SqlServer .Management.IntegrationServices.CatalogFolder" ($catalog, 
$TargetFolderName,"Folder description") -OutVariable folder 

$folder.Create() 


# Read the project file and deploy it 
[byte[]] $projectFile = [System.10.File]::ReadAllBytes($ProjectFilePath) 
$folder.DeployProject($ProjectName, $projectFile) 


# Verify packages were deployed. 
dir "$($catalog.PSPath) \Folders\$TargetFolderName\Projects\$ProjectName\Packages" | 
SELECT Name, DisplayName, PackageId 


PowerShell script 


Provide appropriate values for the variables at the top of the following script, and then run the script to deploy 
the SSIS project. 


NOTE 
The following example uses Windows Authentication to deploy to a SQL Server on premises. To use SQL Server 
authentication, replace the Integrated Security=SSPI; argument with User ID=<user name>;Password=<password>; 


. If you're connecting to an Azure SQL Database server, you can't use Windows authentication. 








# Variables 

$SSTSNamespace = “Microsoft.SqlServer.Management.IntegrationServices" 
$TargetServerName = "localhost" 

$TargetFolderName = "“ProjectiFolder" 

$ProjectFilePath = "C:\Projects\Integration Services Project1\Integration Services 
Project1\bin\Development\Integration Services Project1.ispac" 

$ProjectName = "Integration Services Project1" 


# Load the IntegrationServices assembly 
$loadStatus = [System.Reflection.Assembly]::Load("Microsoft.SQLServer.Management.IntegrationServices, "+ 
"Version=14.0.0.0, Culture=neutral, PublicKeyToken=89845dcd8080cc91, processorArchitecture=MSIL") 


# Create a connection to the server 
$sqlConnectionString = ~ 


"Data Source=" + $TargetServerName + ";Initial Catalog=master;Integrated Security=SSPI;" 


$sqlConnection = New-Object System.Data.SqlClient.SqlConnection $sqlConnectionString 


# Create the Integration Services object 
$integrationServices = New-Object $SSISNamespace".IntegrationServices" $sqlConnection 


# Get the Integration Services catalog 
$catalog = $integrationServices.Catalogs["SSISDB" ] 


# Create the target folder 

$folder = New-Object $SSISNamespace".CatalogFolder" (¢$catalog, $TargetFolderName, 
"Folder description") 

$folder.Create() 


Write-Host "Deploying " $ProjectName " project ... 


# Read the project file and deploy it 
[byte[]] $projectFile = [System.10.File]::ReadAllBytes($ProjectFilePath) 
$folder.DeployProject($ProjectName, $projectFile) 


Write-Host "Done." 


Next steps 


e Consider other ways to deploy a package. 
o Deploy an SSIS package with SSMS 
o Deploy an SSIS package with Transact-SQL (SSMS) 
o Deploy an SSIS package with Transact-SQL (VS Code) 
© Deploy an SSIS package from the command prompt 
o Deploy an SSIS package with C# 


e Runa deployed package. To run a package, you can choose from several tools and languages. For more info, 
see the following articles: 


o Runan SSIS package with SSMS 

o Runan SSIS package with Transact-SQL (SSMS) 

o Runan SSIS package with Transact-SQL (VS Code) 
o Runan SSIS package from the command prompt 
o Runan SSIS package with PowerShell 

o Runan SSIS package with C# 


Deploy an SSIS project with C# code in a .NET app 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 
This quickstart demonstrates how to write C# code to connect to a database server and deploy an SSIS project. 


To create a C# app, you can use Visual Studio, Visual Studio Code, or another tool of your choice. 


Prerequisites 


Before you start, make sure you have Visual Studio or Visual Studio Code installed. Download the free 
Community edition of Visual Studio, or the free Visual Studio Code, from Visual Studio Downloads. 


An Azure SQL Database server listens on port 1433. If you're trying to connect to an Azure SQL Database server 
from within a corporate firewall, this port must be open in the corporate firewall for you to connect successfully. 


Supported platforms 
You can use the information in this quickstart to deploy an SSIS project to the following platforms: 
e SQL Server on Windows. 


e Azure SQL Database. For more info about deploying and running packages in Azure, see Lift and shift 
SQL Server Integration Services workloads to the cloud. 


You cannot use the information in this quickstart to deploy an SSIS package to SQL Server on Linux. For more 
info about running packages on Linux, see Extract, transform, and load data on Linux with SSIS. 


For Azure SQL Database, get the connection info 


To deploy the project to Azure SQL Database, get the connection information you need to connect to the SSIS 
Catalog database (SSISDB). You need the fully qualified server name and login information in the procedures 
that follow. 


1. Log in to the Azure portal. 


2. Select SQL Databases from the left-hand menu, and then select the SSISDB database on the SQL 
databases page. 


3. On the Overview page for your database, review the fully qualified server name. To see the Click to copy 
option, hover over the server name. 


4. lf you forget your Azure SQL Database server login information, navigate to the SQL Database server page 
to view the server admin name. You can reset the password if necessary. 


5. Click Show database connection strings. 


6. Review the complete ADO.NET connection string. Optionally, your code can use a 
SqlConnectionStringBuilder to recreate this connection string with the individual parameter values that you 
provide. 


Supported authentication method 


Refer to authentication methods for deployment. 


Create a new Visual Studio project 


1. In Visual Studio, choose File, New, Project. 
. In the New Project dialog, and expand Visual C#. 


. Select Console App and enter dep/oy_ssis_project for the project name. 


KR WwW DY 


. Click OK to create and open the new project in Visual Studio. 


Add references 


1. In Solution Explorer, right-click the References folder and select Add Reference. The Reference Manager 
dialog box opens. 


2. In the Reference Manager dialog box, expand Assemblies and select Extensions. 
3. Select the following two references to add: 

e Microsoft.SqlServerManagement.Sdk.Sfc 

e Microsoft.SqlServerSmo 


4. Click the Browse button to add a reference to Microsoft.SqlServer.Management.IntegrationServices. 
(This assembly is installed only in the global assembly cache (GAC).) The Select the files to reference 
dialog box opens. 


5. In the Select the files to reference dialog box, navigate to the GAC folder that contains the assembly. 
Typically this folder is 
C:\Windows \assembly\GAC_MSIL\Microsoft.SqlServer.Management. IntegrationServices\14.0.0.0 89845dcd8080cc91 


6. Select the assembly (that is, the dll file) in the folder and click Add. 


7. Click OK to close the Reference Manager dialog box and add the three references. To make sure the 
references are there, check the References list in Solution Explorer. 


Add the C# code 


1. Open Program.cs. 


2. Replace the contents of Program.cs with the following code. Add the appropriate values for your server, 
database, user, and password. 





NOTE 
The following example uses Windows Authentication. To use SQL Server authentication, replace the 
Integrated Security=SSPI; argument with User ID=<user name>;Password=<password>; . If you're connecting to an 


Azure SQL Database server, you can't use Windows authentication. 











using Microsoft.SqlServer.Management.IntegrationServices; 
using System; 

using System.Data.SqlClient; 

using System.I0; 


namespace deploy_ssis_ project 


{ 


class Program 


{ 

static void Main(string[] args) 

{ 
// Variables 
string targetServerName = "localhost"; 
string targetFolderName = "ProjectiFolder"; 
string projectName = "Integration Services Project1"; 
string projectFilePath = @"C:\Projects\Integration Services Projecti\Integration Services 

Projecti\bin\Development\Integration Services Project1.ispac"; 


// Create a connection to the server 


string sqlConnectionString = "Data Source=" + targetServerName + 
";Initial Catalog=master;Integrated Security=SSPI;"; 
SqlConnection sqlConnection = new SqlConnection(sqlConnectionString) ; 


// Create the Integration Services object 
IntegrationServices integrationServices = new IntegrationServices(sqlConnection) ; 


// Get the Integration Services catalog 
Catalog catalog = integrationServices.Catalogs["SSISDB"]; 


// Create the target folder 

CatalogFolder folder = new CatalogFolder(catalog, 
targetFolderName, "Folder description") ; 

folder.Create(); 


Console.WriteLine("Deploying " + projectName + " project."); 


byte[] projectFile = File.ReadAllBytes(projectFilePath) ; 
folder .DeployProject(projectName, projectFile) ; 


Console.WriteLine("Done."); 


Run the code 


1. To run the application, press F5. 
2. In SSMS, verify that the project has been deployed. 


Next steps 


e Consider other ways to deploy a package. 
© Deploy an SSIS package with SSMS 
© Deploy an SSIS package with Transact-SQL (SSMS) 
© Deploy an SSIS package with Transact-SQL (VS Code) 


O° 


Deploy an SSIS package from the command prompt 
°o Deploy an SSIS package with PowerShell 

e Runa deployed package. To run a package, you can choose from several tools and languages. For more info, 
see the following articles: 
o Runan SSIS package with SSMS 


Run an SSIS package with Transact-SQL (SSMS) 
Run an SSIS package with Transact-SQL (VS Code) 
Run an SSIS package from the command prompt 
Run an SSIS package with PowerShell 

Run an SSIS package with C# 


Run an SSIS package with SQL Server Management 


SIU [COMES 
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Applies to: Q sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


This quickstart demonstrates how to use SQL Server Management Studio (SSMS) to connect to the SSIS Catalog 
database, and then run an SSIS package stored in the SSIS Catalog from Object Explorer in SSMS. 


SQL Server Management Studio is an integrated environment for managing any SQL infrastructure, from SQL 
Server to SQL Database. For more info about SSMS, see SQL Server Management Studio (SSMS). 


Prerequisites 


Before you start, make sure you have the latest version of SQL Server Management Studio (SSMS). To download 
SSMS, see Download SQL Server Management Studio (SSMS). 


An Azure SQL Database server listens on port 1433. If you're trying to connect to an Azure SQL Database server 
from within a corporate firewall, this port must be open in the corporate firewall for you to connect successfully. 


Supported platforms 
You can use the information in this quickstart to run an SSIS package on the following platforms: 
e@ SQL Server on Windows. 


e Azure SQL Database. For more info about deploying and running packages in Azure, see Lift and shift 
SQL Server Integration Services workloads to the cloud. 


You cannot use the information in this quickstart to run an SSIS package on Linux. For more info about running 
packages on Linux, see Extract, transform, and load data on Linux with SSIS. 


For Azure SQL Database, get the connection info 


To run the package on Azure SQL Database, get the connection information you need to connect to the SSIS 
Catalog database (SSISDB). You need the fully qualified server name and login information in the procedures 
that follow. 


1. Log in to the Azure portal. 


2. Select SQL Databases from the left-hand menu, and then select the SSISDB database on the SQL 
databases page. 


3. On the Overview page for your database, review the fully qualified server name. To see the Click to copy 
option, hover over the server name. 


4. If you forget your Azure SQL Database server login information, navigate to the SQL Database server page 
to view the server admin name. You can reset the password if necessary. 


Connect to the SSISDB database 
Use SQL Server Management Studio to establish a connection to the SSIS Catalog. 


1. Open SQL Server Management Studio. 


2. In the Connect to Server dialog box, enter the following information: 


SETTING SUGGESTED VALUE MORE INFO 

Server type Database engine This value is required. 

Server name The fully qualified server name If you're connecting to an Azure 
SQL Database server, the name is in 
this format: 


<server_name>.database.windows.net 


Authentication SQL Server Authentication With SQL Server authentication, you 
can connect to SQL Server or to 
Azure SQL Database. If you're 
connecting to an Azure SQL 
Database server, you can't use 
Windows authentication. 


Login The server admin account This account is the account that you 
specified when you created the 
server. 

Password The password for your server admin This password is the password that 

account you specified when you created the 
server. 


3. Click Connect. The Object Explorer window opens in SSMS. 


4. In Object Explorer, expand Integration Services Catalogs and then expand SSISDB to view the objects 
in the SSIS Catalog database. 


Run a package 
1. In Object Explorer, select the package that you want to run. 
2. Right-click and select Execute. The Execute Package dialog box opens. 


3. Configure the package execution by using the settings on the Parameters, Connection Managers, and 
Advanced tabs in the Execute Package dialog box. 


4. Click OK to run the package. 


Next steps 


e@ Consider other ways to run a package. 
o Runan SSIS package with Transact-SQL (SSMS) 
o Runan SSIS package with Transact-SQL (VS Code) 
o Runan SSIS package from the command prompt 
o Runan SSIS package with PowerShell 
o Runan SSIS package with C# 


Run an SSIS package from SSMS with Transact-SQL 
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Applies to: Q sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


This quickstart demonstrates how to use SQL Server Management Studio (SSMS) to connect to the SSIS Catalog 
database, and then use Transact-SQL statements to run an SSIS package stored in the SSIS Catalog. 


SQL Server Management Studio is an integrated environment for managing any SQL infrastructure, from SQL 
Server to SQL Database. For more info about SSMS, see SQL Server Management Studio (SSMS). 


Prerequisites 


Before you start, make sure you have the latest version of SQL Server Management Studio (SSMS). To download 
SSMS, see Download SQL Server Management Studio (SSMS). 


An Azure SQL Database server listens on port 1433. If you're trying to connect to an Azure SQL Database server 
from within a corporate firewall, this port must be open in the corporate firewall for you to connect successfully. 


Supported platforms 
You can use the information in this quickstart to run an SSIS package on the following platforms: 
e SQL Server on Windows. 


e Azure SQL Database. For more info about deploying and running packages in Azure, see Lift and shift 
SQL Server Integration Services workloads to the cloud. 


You cannot use the information in this quickstart to run an SSIS package on Linux. For more info about running 
packages on Linux, see Extract, transform, and load data on Linux with SSIS. 


For Azure SQL Database, get the connection info 


To run the package on Azure SQL Database, get the connection information you need to connect to the SSIS 
Catalog database (SSISDB). You need the fully qualified server name and login information in the procedures 
that follow. 


1. Log in to the Azure portal. 


2. Select SQL Databases from the left-hand menu, and then select the SSISDB database on the SQL 
databases page. 


3. On the Overview page for your database, review the fully qualified server name. To see the Click to copy 
option, hover over the server name. 


4. lf you forget your Azure SQL Database server login information, navigate to the SQL Database server page 


to view the server admin name. You can reset the password if necessary. 


Connect to the SSISDB database 


Use SQL Server Management Studio to establish a connection to the SSIS Catalog on your Azure SQL Database 
server. 


1. Open SQL Server Management Studio. 


2. In the Connect to Server dialog box, enter the following information: 


SETTING 


Server type 


Server name 


Authentication 


Login 


Password 


SUGGESTED VALUE 


Database engine 


The fully qualified server name 


SQL Server Authentication 


The server admin account 


The password for your server admin 
account 


3. Click Connect. The Object Explorer window opens in SSMS. 


MORE INFO 


This value is required. 


If you're connecting to an Azure 
SQL Database server, the name is in 
this format: 


<server_name>.database.windows.net 


With SQL Server authentication, you 
can connect to SQL Server or to 
Azure SQL Database. If you're 
connecting to an Azure SQL 
Database server, you can't use 
Windows authentication. 


This account is the account that you 
specified when you created the 
server. 


This password is the password that 
you specified when you created the 
server. 


4. In Object Explorer, expand Integration Services Catalogs and then expand SSISDB to view the objects 


in the SSIS Catalog database. 


Run a package 


Run the following Transact-SQL code to run an SSIS package. 


1. In SSMS, open a new query window and paste the following code. (This code is the code generated by the 


Script option in the Execute Package dialog box in SSMS.) 


2. Update the parameter values in the catalog.create_execution stored procedure for your system. 


3. Make sure that SSISDB is the current database. 


4. Run the script. 


5. In Object Explorer, refresh the contents of SSISDB if necessary and check for the project that you 


deployed. 


Declare @execution_id bigint 
EXEC [SSISDB].[catalog].[create_execution] @package_name=N'Package.dtsx', 
@execution_id=@execution_id OUTPUT, 
@folder_name=N'Deployed Projects’, 
@project_name=N'Integration Services Projecti', 
@use32bitruntime=False, 
@reference_id=Null 
Select @execution_id 
DECLARE @var@ smallint = 1 
EXEC [SSISDB].[catalog].[set_execution_parameter_value] @execution_id, 
@object_type=50, 
@parameter_name=N'LOGGING_LEVEL"', 
@parameter_value=@var@ 


EXEC [SSISDB].[catalog].[start_execution] @execution_id 
GO 


Next steps 


e Consider other ways to run a package. 
o Runan SSIS package with SSMS 
o Runan SSIS package with Transact-SQL (VS Code) 
o Runan SSIS package from the command prompt 
o Runan SSIS package with PowerShell 
o Runan SSIS package with C# 


Run an SSIS package from Visual Studio Code with 
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Applies to: Q sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


This quickstart demonstrates how to use Visual Studio Code to connect to the SSIS Catalog database, and then 
use Transact-SQL statements to run an SSIS package stored in the SSIS Catalog. 


Visual Studio Code is a code editor for Windows, macOS, and Linux that supports extensions, including the 
mssql extension for connecting to Microsoft SQL Server, Azure SQL Database, or Azure Synapse Analytics. For 
more info about VS Code, see Visual Studio Code. 


Prerequisites 


Before you start, make sure you have installed the latest version of Visual Studio Code and loaded the mssql 
extension. To download these tools, see the following pages: 


e Download Visual Studio Code 


® mssql extension 


Supported platforms 
You can use the information in this quickstart to run an SSIS package on the following platforms: 
e SQL Server on Windows. 


e Azure SQL Database. For more info about deploying and running packages in Azure, see Lift and shift 
SQL Server Integration Services workloads to the cloud. 


You cannot use the information in this quickstart to run an SSIS package on Linux. For more info about running 
packages on Linux, see Extract, transform, and load data on Linux with SSIS. 


Set language mode to SQL in VS Code 

To enable mssql commands and T-SQL IntelliSense, set the language mode is set to SQL in Visual Studio Code. 
1. Open Visual Studio Code and then open a new window. 

2. Click Plain Text in the lower right-hand corner of the status bar. 


3. In the Select language mode drop-down menu that opens, select or enter SQL, and then press ENTER 
to set the language mode to SQL. 


For Azure SQL Database, get the connection info 


To run the package on Azure SQL Database, get the connection information you need to connect to the SSIS 
Catalog database (SSISDB). You need the fully qualified server name and login information in the procedures 
that follow. 


1. Log in to the Azure portal. 
2. Select SQL Databases from the left-hand menu, and then select the SSISDB database on the SQL 


databases page. 


. On the Overview page for your database, review the fully qualified server name. To see the Click to copy 


option, hover over the server name. 


If you forget your Azure SQL Database server login information, navigate to the SQL Database server page 


to view the server admin name. You can reset the password if necessary. 


Connect to the SSIS Catalog database 


Use Visual Studio Code to establish a connection to the SSIS Catalog. 








IMPORTANT 


Before continuing, make sure that you have your server, database, and login information ready. If you change your focus 
from Visual Studio Code after you begin entering the connection profile information, you have to restart creating the 


connection profile. 





1; 


2. 


In VS Code, press CTRL+SHIFT+P (or F1) to open the Command Palette. 


Type sqicon and press ENTER. 


. Press ENTER to select Create Connection Profile. This step creates a connection profile for your SQL 


Server instance. 


Follow the prompts to specify the connection properties for the new connection profile. After specifying 
each value, press ENTER to continue. 


SETTING SUGGESTED VALUE MORE INFO 

Server name The fully qualified server name If you're connecting to an Azure 
SQL Database server, the name is in 
this format: 


<server_name>.database.windows.net 


Database name SSISDB The name of the database to which 
to connect. 
Authentication SQL Login With SQL Server authentication, you 


can connect to SQL Server or to 
Azure SQL Database. If you're 
connecting to an Azure SQL 
Database server, you can't use 
Windows authentication. 


User name The server admin account This account is the account that you 
specified when you created the 
server. 

Password (SQL Login) The password for your server admin This password is the password that 

account you specified when you created the 
server. 

Save Password? Yes or No If you do not want to enter the 


password each time, select Yes. 





SETTING SUGGESTED VALUE MORE INFO 


Enter a name for this profile A profile name, such as A saved profile name speeds your 
mySsSISServer connection on subsequent logins. 


5. Press the ESC key to close the info message that informs you that the profile is created and connected. 


6. Verify your connection in the status bar. 


Run the T-SQL code 


Run the following Transact-SQL code to run an SSIS package. 


1. In the Editor window, enter the following query in the empty query window. (This code is the code 
generated by the Script option in the Execute Package dialog box in SSMS.) 


2. Update the parameter values in the catalog.create_execution stored procedure for your system. 


3. Press CTRL+SHIFT+E to run the code and run the package. 


Declare @execution_id bigint 
EXEC [SSISDB].[catalog].[create_execution] @package_name=N'Package.dtsx', 
@execution_id=@execution_id OUTPUT, 
@folder_name=N'Deployed Projects’, 
@project_name=N'Integration Services Projecti', 
@use32bitruntime=False, 
@reference_id=Null 
Select @execution_id 
DECLARE @var@ smallint = 1 
EXEC [SSISDB].[catalog].[set_execution_parameter_value] @execution_id, 
@object_type=50, 
@parameter_name=N'LOGGING_LEVEL"', 
@parameter_value=@var@ 
EXEC [SSISDB].[catalog].[start_execution] @execution_id 
GO 


Next steps 


e@ Consider other ways to run a package. 
o Runan SSIS package with SSMS 
o Runan SSIS package with Transact-SQL (SSMS) 
o Runan SSIS package from the command prompt 
o Runan SSIS package with PowerShell 
o Runan SSIS package with C# 


Run an SSIS package from the command prompt 


with DTExec.exe 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


This quickstart demonstrates how to run an SSIS package from the command prompt by running DTExec.exe 
with the appropriate parameters. 





NOTE 


The method described in this article has not been tested with packages deployed to an Azure SQL Database server. 











For more info about DTExec.exe , see dtexec Utility. 


Supported platforms 
You can use the information in this quickstart to run an SSIS package on the following platforms: 


e SQL Server on Windows. 


The method described in this article has not been tested with packages deployed to an Azure SQL Database 
server. For more info about deploying and running packages in Azure, see Lift and shift SQL Server Integration 
Services workloads to the cloud. 


You cannot use the information in this quickstart to run an SSIS package on Linux. For more info about running 
packages on Linux, see Extract, transform, and load data on Linux with SSIS. 


Run a package with dtexec 


If the folder that contains DTExec.exe is notin your path environment variable, you may have to use the cd 
command to change to its directory. For SQL Server 2017, this folder is typically 
C:\Program Files (x86)\Microsoft SQL Server\140\DTS\Binn 


With the parameter values used in the following example, the program runs the package in the specified folder 
path on the SSIS server - that is, the server that hosts the SSIS Catalog database (SSISDB). The /Server 
parameter provides the server name. The program connects as the current user with Windows Integrated 
Authentication. To use SQL Authentication, specify the /User and Password parameters with appropriate 


values. 
1. Open a Command Prompt window. 
2. Run DTExec.exe and provide values at least for the Isserver andthe Server parameters, as shown in 


the following example: 


dtexec /ISServer "\SSISDB\Project1iFolder\Integration Services Project1\Package.dtsx" /Server 
"localhost" 


Next steps 


e Consider other ways to run a package. 
o Runan SSIS package with SSMS 
o Runan SSIS package with Transact-SQL (SSMS) 
o RunanSSIS package with Transact-SQL (VS Code) 
o Runan SSIS package with PowerShell 
o Runan SSIS package with C# 


Run an SSIS package with PowerShell 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


This quickstart demonstrates how to use a PowerShell script to connect to a database server and run an SSIS 
package. 


Prerequisites 


An Azure SQL Database server listens on port 1433. If you're trying to connect to an Azure SQL Database server 
from within a corporate firewall, this port must be open in the corporate firewall for you to connect successfully. 


Supported platforms 
You can use the information in this quickstart to run an SSIS package on the following platforms: 
e SQL Server on Windows. 


e SSIS integration runtime (IR) in Azure Data Factory (ADF), where SSIS catalog (SSISDB) is hosted by Azure 
SQL Managed Instance (MI). For more info about deploying and running packages in Azure, see Lift and 
shift SQL Server Integration Services workloads to the cloud. 


You cannot use the information in this quickstart to run an SSIS package on Linux. For more info about running 
packages on Linux, see Extract, transform, and load data on Linux with SSIS. 


For Azure SQL Database, get the connection info 


To run the package on Azure SQL Database, get the connection information you need to connect to the SSIS 
Catalog database (SSISDB). You need the fully qualified server name and login information in the procedures 
that follow. 


1. Sign in to the Azure portal. 


2. Select SQL Databases from the left-hand menu, and then select the SSISDB database on the SQL 
databases page. 


3. On the Overview page for your database, review the fully qualified server name. To see the Click to copy 
option, hover over the server name. 


4. If you forget your Azure SQL Database server login information, navigate to the SQL Database server page 
to view the server admin name. You can reset the password if necessary. 


5. Click Show database connection strings. 


6. Review the complete ADO.NET connection string. 


SSIS PowerShell Provider 


You can use the SSIS PowerShell Provider to connect to an SSIS catalog and execute packages within it. 


Below is a basic example of how to execute an SSIS package in a package catalog with the SSIS PowerShell 
Provider. 


(Get-ChildItem 

SQLSERVER: \SSIS\localhost\Default\Catalogs\SSISDB\Folders\ProjectiFolder\Projects\'Integration Services 
Project1'\Packages\ 

WHERE { $_.Name -eq 'Package.dtsx' }).Execute("false", $null) 


PowerShell script 


Provide appropriate values for the variables at the top of the following script, and then run the script to run the 
SSIS package. 





NOTE 


The following example uses Windows Authentication. To use SQL Server authentication, replace the 


Integrated Security=SSPI; argument with User ID=<user name>;Password=<password>; . If you're connecting to an 


Azure SQL Database server, you can't use Windows authentication. 





# Variables 

$SSISNamespace = "Microsoft.SqlServer.Management.IntegrationServices" 
$TargetServerName = "localhost" 

$TargetFolderName = "ProjectiFolder" 

$ProjectName = "Integration Services Project1" 

$PackageName = "Package.dtsx" 


# Load the IntegrationServices assembly 


$loadStatus = [System.Reflection.Assembly]::Load("Microsoft.SQLServer.Management.IntegrationServices, "+ 
"Version=14.0.0.0, Culture=neutral, PublicKeyToken=89845dcd8080cc91, processorArchitecture=MSIL") 


# Create a connection to the server 
$sqlConnectionString = ~ 


"Data Source=" + $TargetServerName + ";Initial Catalog=master;Integrated Security=SSPI;" 


$sqlConnection = New-Object System.Data.SqlClient.SqlConnection $sqlConnectionString 


# Create the Integration Services object 
$integrationServices = New-Object $SSISNamespace".IntegrationServices" $sqlConnection 


# Get the Integration Services catalog 
$catalog = $integrationServices.Catalogs["SSISDB" ] 


# Get the folder 
$folder = $catalog.Folders[$TargetFolderName ] 


# Get the project 
$project = $folder.Projects[$ProjectName ] 


# Get the package 
$package = $project.Packages[$PackageName ] 


Write-Host "Running " $PackageName " s 


$result = $package.Execute("false", $null) 


Write-Host "Done." 


Next steps 


e@ Consider other ways to run a package. 
o Runan SSIS package with SSMS 
o Runan SSIS package with Transact-SQL (SSMS) 





o RunanSSIS package with Transact-SQL (VS Code) 
o Runan SSIS package from the command prompt 


o RunanSSIS package with C# 


Run an SSIS package with C# code in a .NET app 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 
This quickstart demonstrates how to write C# code to connect to a database server and run an SSIS package. 


You can use Visual Studio, Visual Studio Code, or another tool of your choice to create a C# app. 


Prerequisites 


Before you start, make sure you have Visual Studio or Visual Studio Code installed. Download the free 
Community edition of Visual Studio, or the free Visual Studio Code, from Visual Studio Downloads. 


An Azure SQL Database server listens on port 1433. If you're trying to connect to an Azure SQL Database server 
from within a corporate firewall, this port must be open in the corporate firewall for you to connect successfully. 


For Azure SQL Database, get the connection info 


To run the package on Azure SQL Database, get the connection information you need to connect to the SSIS 
Catalog database (SSISDB). You need the fully qualified server name and login information in the procedures 
that follow. 


1. Log in to the Azure portal. 


2. Select SQL Databases from the left-hand menu, and then select the SSISDB database on the SQL 
databases page. 


3. On the Overview page for your database, review the fully qualified server name. To see the Click to copy 
option, hover over the server name. 


4. If you forget your Azure SQL Database server login information, navigate to the SQL Database server page 
to view the server admin name. You can reset the password if necessary. 


5. Click Show database connection strings. 


6. Review the complete ADO.NET connection string. Optionally, your code can use a 
SqlConnectionStringBuilder to recreate this connection string with the individual parameter values that you 
provide. 


Create a new Visual Studio project 


1. In Visual Studio, choose File, New, Project. 

2. Inthe New Project dialog, and expand Visual C#. 

3. Select Console App and enter run_ssis_project for the project name. 
4 


. Click OK to create and open the new project in Visual Studio. 


Add references 


1. In Solution Explorer, right-click the References folder and select Add Reference. The Reference Manager 
dialog box opens. 


2. In the Reference Manager dialog box, expand Assemblies and select Extensions. 
3. Select the following two references to add: 


e Microsoft.SqlServerManagement.Sdk.Sfc 


e Microsoft.SqlServerSmo 
4. Click the Browse button to add a reference to Microsoft.SqlServer.Management.IntegrationServices. 
(This assembly is installed only in the global assembly cache (GAC).) The Select the files to reference 
dialog box opens. 
5. In the Select the files to reference dialog box, navigate to the GAC folder that contains the assembly. 
Typically this folder is 
C:\Windows \assembly\GAC_MSIL\Microsoft.SqlServer.Management.IntegrationServices\14.0.0.0 89845dcd8080cc91 


6. Select the assembly (that is, the .dll file) in the folder and click Add. 


7. Click OK to close the Reference Manager dialog box and add the three references. To make sure the 
references are there, check the References list in Solution Explorer. 


Add the C# code 


1. Open Program.cs. 


2. Replace the contents of Program.cs with the following code. Add the appropriate values for your server, 
database, user, and password. 





NOTE 
The following example uses Windows Authentication. To use SQL Server authentication, replace the 
Integrated Security=SSPI; argument with User ID=<user name>;Password=<password>; . If you're connecting to an 


Azure SQL Database server, you can't use Windows authentication. 











using Microsoft.SqlServer.Management.IntegrationServices; 
using System.Data.SqliClient; 


namespace run_ssis_package 
{ 
class Program 
if 
static void Main(string[] args) 
{ 
// Nariables 
string targetServerName = "localhost"; 
string folderName = "ProjectiFolder"; 
string projectName = "Integration Services Projecti"; 
string packageName = "Package.dtsx"; 


// Create a connection to the server 


string sqlConnectionString = "Data Source=" + targetServerName + 
";Initial Catalog=master;Integrated Security=SSPI;"; 


SqlConnection sqlConnection = new SqlConnection(sqlConnectionString) ; 


// Create the Integration Services object 


IntegrationServices integrationServices = new IntegrationServices(sqlConnection) ; 


// Get the Integration Services catalog 
Catalog catalog = integrationServices.Catalogs["SSISDB"]; 


// Get the folder 
CatalogFolder folder = catalog.Folders[folderName] ; 


// Get the project 
ProjectInfo project = folder.Projects[projectName ] ; 


// Get the package 
PackageInfo package = project.Packages[packageName] ; 


// Run the package 
package.Execute(false, null); 


Run the code 


1. To run the application, press F5. 


2. Verify that the package ran as expected and then close the application window. 


Next steps 


e Consider other ways to run a package. 
o Runan SSIS package with SSMS 
o Runan SSIS package with Transact-SQL (SSMS) 
o Runan SSIS package with Transact-SQL (VS Code) 
o Runan SSIS package from the command prompt 


o Runan SSIS package with PowerShell 


Lift and shift SQL Server Integration Services 


workloads to the cloud 
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You can now move your SQL Server Integration Services (SSIS) projects, packages, and workloads to the Azure 
cloud. Deploy, run, and manage SSIS projects and packages in the SSIS Catalog (SSISDB) on Azure SQL 
Database or SQL Managed Instance with familiar tools such as SQL Server Management Studio (SSMS). 


Benefits 
Moving your on-premises SSIS workloads to Azure has the following potential benefits: 


e Reduce operational costs and reduce the burden of managing infrastructure that you have when you run 
SSIS on-premises or on Azure virtual machines. 


e Increase high availability with the ability to specify multiple nodes per cluster, as well as the high 
availability features of Azure and of Azure SQL Database. 


e Increase scalability with the ability to specify multiple cores per node (scale up) and multiple nodes per 
cluster (scale out). 


Architecture of SSIS on Azure 
The following table highlights the differences between SSIS on premises and SSIS on Azure. 


The most significant difference is the separation of storage from runtime. Azure Data Factory hosts the runtime 
engine for SSIS packages on Azure. The runtime engine is called the Azure-SSIS Integration Runtime (Azure- 
SSIS IR). For more info, see Azure-SSIS Integration Runtime. 


LOCATION STORAGE RUNTIME SCALABILITY 
On premises SQL Server SSIS runtime hosted by SQL SSIS Scale Out (in SQL 
Server Server 2017 and later) 


Custom solutions (in prior 
versions of SQL Server) 


On Azure SQL Database or SQL Azure-SSIS Integration Scaling options for the 
Managed Instance Runtime, a component of Azure-SSIS Integration 
Azure Data Factory Runtime 


Provision SSIS on Azure 


Provision. Before you can deploy and run SSIS packages in Azure, you have to provision the SSIS Catalog 
(SSISDB) and the Azure-SSIS Integration Runtime. 


® To provision SSIS on Azure in the Azure portal, follow the provisioning steps in this article: Provision the 
Azure-SSIS Integration Runtime in Azure Data Factory. 


© To provision SSIS on Azure with PowerShell, follow the provisioning steps in this article: Provision the 


Azure-SSIS Integration Runtime in Azure Data Factory with PowerShell. 


You only have to provision the Azure-SSIS IR one time. After that, you can use familiar tools such as SQL Server 
Data Tools (SSDT) and SQL Server Management Studio (SSMS) to deploy, configure, run, monitor, schedule, and 
manage packages. 


NOTE 


The Azure-SSIS Integration Runtime is not yet available in all Azure regions. For info about the supported regions, see 


Products available by region - Microsoft Azure. 





Scale up and out. When you provision the Azure-SSIS IR, you can scale up and scale out by specifying values 
for the following options: 


@ The node size (including the number of cores) and the number of nodes in the cluster. 


e The existing instance of Azure SQL Database to host the SSIS Catalog Database (SSISDB), and the service tier 
for the database. 


e The maximum parallel executions per node. 


Improve performance. For more info, see Configure the Azure-SSIS Integration Runtime for high 


performance. 


Reduce costs. To reduce costs, run the Azure-SSIS IR only when you need it. For more info, see How to 
schedule starting and stopping of an Azure SSIS integration runtime. 


Design packages 
You continue to design and build packages on-premises in SSDT, or in Visual Studio with SSDT installed. 


Connect to data sources 


To connect to on-premises data sources from the cloud with Windows authentication, see Connect to data 
sources and file shares with Windows Authentication from SSIS packages in Azure. 


To connect to files and file shares, see Open and save files on premises and in Azure with SSIS packages 
deployed in Azure. 


Available SSIS components 


When you provision an instance of SQL Database to host SSISDB, the Azure Feature Pack for SSIS and the 
Access Redistributable are also installed. These components provide connectivity to various Azure data sources 
and to Excel and Access files, in addition to the data sources supported by the built-in components. 


You can also install additional components - for example, you can install a driver that's not installed by default. 
For more info, see Customize setup for the Azure-SSIS integration runtime. 


If you have an Enterprise Edition license, additional components are available. For more info, see Provision 
Enterprise Edition for the Azure-SSIS Integration Runtime. 


If you're an ISV, you can update the installation of your licensed components to make them available on Azure. 
For more info, see Install paid or licensed custom components for the Azure-SSIS integration runtime. 


Transaction support 


With SQL Server on premises and on Azure virtual machines, you can use Microsoft Distributed Transaction 
Coordinator (MSDTC) transactions. To configure MSDTC on each node of the Azure-SSIS IR, use the custom 
setup capability. For more info, see Custom setup for the Azure-SSIS integration runtime. 


With Azure SQL Database, you can only use elastic transactions. For more info, see Distributed transactions 


across cloud databases. 


Deploy and run packages 
To get started, see Tutorial: Deploy and run a SQL Server Integration Services (SSIS) package in Azure. 


Prerequisites 


To deploy SSIS packages to Azure, you have to have one of the following versions of SQL Server Data Tools 
(SSDT): 


e For Visual Studio 2017, version 15.3 or later. 


e For Visual Studio 2015, version 17.2 or later. 


Connect to SSISDB 


The name of the SQL Database that hosts SSISDB becomes the first part of the four-part name to use when 
you deploy and run packages from SSDT and SSMS, in the following format - 

<sql_database_name>.database.windows.net . For more info about how to connect to the SSIS Catalog database in 
Azure, see Connect to the SSIS Catalog (SSISDB) in Azure. 


Deploy projects and packages 


You have to use the project deployment model, not the package deployment model, when you deploy 
projects to SSISDB on Azure. 


To deploy projects on Azure, you can use one of several familiar tools and scripting options: 


e SQL Server Management Studio (SSMS) 
e Transact-SQL (from SSMS, Visual Studio Code, or another tool) 
e Acommand-line tool 


e PowerShell or C# and the SSIS management object model 


The deployment process validates packages to ensure that they can run on the Azure-SSIS Integration Runtime. 
For more info, see Validate SQL Server Integration Services (SSIS) packages deployed to Azure. 


For a deployment example that uses SSMS and the Integration Services Deployment Wizard, see Tutorial: 
Deploy and run a SQL Server Integration Services (SSIS) package in Azure. 


Version support 


You can deploy a package created with any version of SSIS to Azure. When you deploy a package to Azure, if 
there are no validation errors, the package is automatically upgraded to the latest package format. In other 
words, it is always upgraded to the latest version of SSIS. 


Run packages 


To run SSIS packages deployed in Azure, you can use a variety of methods. For more info, see Run SQL Server 
Integration Services (SSIS) packages deployed in Azure. 


Run packages in an Azure Data Factory pipeline 


To run an SSIS package in an Azure Data Factory pipeline, use the Execute SSIS Package Activity. For more info, 
see Run an SSIS package using the Execute SSIS Package Activity in Azure Data Factory. 


When you run a package in a Data Factory pipeline with the Execute SSIS Package Activity, you can pass values 
to the package at runtime. To pass one or more runtime values, create SSIS execution environments in SSISDB 
with SQL Server Management Studio (SSMS). In each environment, create variables and assign values that 
correspond to the parameters for your projects or packages. Configure your SSIS packages in SSMS to associate 
those environment variables with your project or package parameters. When you run the packages in the 
pipeline, switch between environments by specifying different environment paths on the Settings tab of the 
Execute SSIS Package activity Ul. For more info about SSIS environments, see Create and Map a Server 


Environment. 


Monitor packages 
To monitor running packages, use the following reporting options in SSMS. 


e Right-click SSISDB, and then select Active Operations to open the Active Operations dialog box. 


e Select a package in Object Explorer, right-click and select Reports, then Standard Reports, then All 
Executions. 


To monitor the Azure-SSIS Integration Runtime, see Monitor the Azure-SSIS integration runtime. 


Schedule packages 


To schedule the execution of packages deployed in Azure, you can use a variety of tools. For more info, see 
Schedule the execution of SQL Server Integration Services (SSIS) packages deployed in Azure. 


Next steps 


To get started with SSIS workloads on Azure, see the following articles: 


e Tutorial: Deploy and run a SQL Server Integration Services (SSIS) package in Azure 


e@ Provision the Azure-SSIS Integration Runtime in Azure Data Factory 


Tutorial: Deploy and run a SQL Server Integration 


Services (SSIS) package in Azure 
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This tutorial shows you how to deploy a SQL Server Integration Services (SSIS) project to the SSIS Catalog in 
Azure SQL Database, run a package in the Azure-SSIS Integration Runtime, and monitor the running package. 


Prerequisites 


Before you start, make sure you have version 17.2 or later of SQL Server Management Studio. To download the 
latest version of SSMS, see Download SQL Server Management Studio (SSMS). 


Also make sure that you have set up the SSISDB database in Azure and provisioned the Azure-SSIS Integration 
Runtime. For info about how to provision SSIS on Azure, see Deploy SQL Server Integration Services packages 
to Azure. 


For Azure SQL Database, get the connection info 


To run the package on Azure SQL Database, get the connection information you need to connect to the SSIS 
Catalog database (SSISDB). You need the fully qualified server name and login information in the procedures 
that follow. 


1. Log in to the Azure portal. 


2. Select SQL Databases from the left-hand menu, and then select the SSISDB database on the SQL 
databases page. 


3. On the Overview page for your database, review the fully qualified server name. To see the Click to copy 
option, hover over the server name. 


4. If you forget your Azure SQL Database server login information, navigate to the SQL Database server page 
to view the server admin name. You can reset the password if necessary. 


Connect to the SSISDB database 


Use SQL Server Management Studio to connect to the SSIS Catalog on your Azure SQL Database server. For 
more info and screenshots, see Connect to the SSISDB Catalog database on Azure. 


Here are the two most important things to remember. These steps are described in the following procedure. 


e Enter the fully qualified name of the Azure SQL Database server in the format 
mysqldbserver.database.windows.net. 


e Select ssispB as the database for the connection. 


IMPORTANT 


An Azure SQL Database server listens on port 1433. If you are attempting to connect to an Azure SQL Database server 


from within a corporate firewall, this port must be open in the corporate firewall for you to connect successfully. 





1. Open SQL Server Management Studio. 


2. Connect to the server. In the Connect to Server dialog box, enter the following information: 


SETTING SUGGESTED VALUE DESCRIPTION 
Server type Database Engine This value is required. 
Server name The fully qualified server name The name should be in this format: 


mysqldbserver.database.windo 
ws.net. If you need the server 
name, see Connect to the SSISDB 
Catalog database on Azure. 


Authentication SQL Server Authentication You can't connect to Azure SQL 
Database with Windows 
authentication. 


Login The server admin account The account that you specified when 
you created the server. 


Password The password for your server admin The password that you specified 
account when you created the server. 


. Connect to the SSISDB database. Select Options to expand the Connect to Server dialog box. In 


the expanded Connect to Server dialog box, select the Connection Properties tab. In the Connect to 
database field, select or enter ssispB . 


Then select Connect. The Object Explorer window opens in SSMS. 


. In Object Explorer, expand Integration Services Catalogs and then expand SSISDB to view the objects 


in the SSIS Catalog database. 


Deploy a project with the Deployment Wizard 


To learn more about deploying packages and about the Deployment Wizard, see Deploy Integration Services 


(SSIS) Projects and Packages and Integration Services Deployment Wizard. 





NOTE 
Deployment to Azure only supports the project deployment model. 





Start the Integration Services Deployment Wizard 


1. 


In Object Explorer in SSMS, with the Integration Services Catalogs node and the SSISDB node 
expanded, expand a project folder. 


. Select the Projects node. 


. Right-click on the Projects node and select Deploy project. The Integration Services Deployment 


Wizard opens. You can deploy a project from an SSIS Catalog database or from the file system. 
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Deploy a project with the Deployment Wizard 


1. On the Introduction page of the Deployment Wizard, review the introduction. Select Next to open the 
Select Source page. 


2. On the Select Source page, select the existing SSIS project to deploy. 


© To deploy a project deployment file that you created, select Project deployment file and enter the 
path to the .ispac file. 


© To deploy a project that resides in an SSIS catalog, select Integration Services catalog, and then 
enter the server name and the path to the project in the catalog. Only projects that reside in SSISDB 
hosted by SQL Server can be redeployed in this step. 


e Select Next to see the Select Destination page. 


3. On the Select Destination page, select the destination for the project. 


Enter the fully qualified server name in the format <server_name>.database.windows.net . 


Provide authentication information, and then select Connect. 


Then select Browse to select the target folder in SSISDB. 


Then select Next to open the Review page. (The Next button is enabled only after you select 
Connect.) 


4. On the Review page, review the settings you selected. 


e You can change your selections by selecting Previous, or by selecting any of the steps in the left pane. 


e Select Deploy to start the deployment process. 


NOTE 

If you get the error message There is no active worker agent. (.Net SqlClient Data Provider), make sure 
the Azure-SSIS Integration Runtime is running. This error occurs if you try to deploy while the Azure-SSIS IR is in a 
stopped state. 





5. After the deployment process is complete, the Results page opens. This page displays the success or 
failure of each action. 


e If the action failed, select Failed in the Result column to display an explanation of the error. 
@ Optionally, select Save Report... to save the results to an XML file. 


e Select Close to exit the wizard. 


Deploy a project with PowerShell 


To deploy a project with PowerShell to SSISDB on Azure SQL Database, adapt the following script to your 
requirements. The script enumerates the child folders under $ProjectFilePath and the projects in each child 
folder, then creates the same folders in SSISDB and deploys the projects to those folders. 


This script requires SQL Server Data Tools version 17.x or SQL Server Management Studio installed on the 
computer where you run the script. 





# Variables 
$ProjectFilePath = "C:\<folder>" 


$SSISDBServerEndpoint = "<servername>.database.windows.net" 
$SSISDBServerAdminUserName = "<username>" 
$SSISDBServerAdminPassword = "<password>" 


# Load the IntegrationServices Assembly 
[System.Reflection.Assembly]::LoadWithPartialName("Microsoft.SqlServer.Management.IntegrationServices") | 
Out-Null; 


# Store the IntegrationServices Assembly namespace to avoid typing it every time 
$ISNamespace = "Microsoft.SqlServer.Management.IntegrationServices" 


Write-Host "Connecting to server ..." 
# Create a connection to the server 
$sqlConnectionString = "Data Source=" + $SSISDBServerEndpoint + ";User ID="+ $SSISDBServerAdminUserName 


+";Password="+ $SSISDBServerAdminPassword + ";Initial Catalog=SSISDB" 
$sqlConnection = New-Object System.Data.SqlClient.SqlConnection $sqlConnectionString 


# Create the Integration Services object 
$integrationServices = New-Object $ISNamespace".IntegrationServices"” $sqlConnection 


# Get the catalog 
$catalog = $integrationServices.Catalogs[ 'SSISDB' ] 


write-host "Enumerating all folders..." 
$folders = 1s -Path $ProjectFilePath -Directory 


if ($folders.Count -gt @) 


{ 
foreach ($filefolder in $folders) 
{ 
Write-Host "Creating Folder " + $filefolder.Name + " iD 
# Create a new folder 
$folder = New-Object $ISNamespace".CatalogFolder" ($catalog, $filefolder.Name, "Folder description") 
$folder.Create() 
$projects = 1s -Path $filefolder.FullName -File -Filter *.ispac 
if ($projects.Count -gt @) 
{ 
foreach($projectfile in $projects) 
{ 
$projectfilename = $projectfile.Name.Replace(".ispac", "") 
Write-Host “Deploying " + $projectfilename + " project ..." 
# Read the project file, and deploy it to the folder 
[byte[]] $projectFileContent = [System.10.File]::ReadAllBytes($projectfile.FullName) 
$folder.DeployProject($projectfilename, $projectFileContent) 
t 
t 
t 
t 


Write-Host "All done.” 


Run a package 


1. In Object Explorer in SSMS, select the package that you want to run. 
2. Right-click and select Execute to open the Execute Package dialog box. 


3. In the Execute Package dialog box, configure the package execution by using the settings on the 


Parameters, Connection Managers, and Advanced tabs. 


4. Select OK to run the package. 


Monitor the running package in SSMS 


To view the status of currently running Integration Services operations on the Integration Services server, such 
as deployment, validation, and package execution, use the Active Operations dialog box in SSMS. To open the 
Active Operations dialog box, right-click SSISDB, and then select Active Operations. 


You can also select a package in Object Explorer, right-click and select Reports, then Standard Reports, then 
All Executions. 


For more info about how to monitor running packages in SSMS, see Monitor Running Packages and Other 
Operations. 


Monitor the Execute SSIS Package activity 


If you're running a package as part of an Azure Data Factory pipeline with the Execute SSIS Package activity, you 
can monitor the pipeline runs in the Data Factory UI. Then you can get the SSISDB execution ID from the output 
of the activity run, and use the ID to check more comprehensive execution logs and error messages in SSMS. 
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Monitor the Azure-SSIS Integration Runtime 


To get status info about the Azure-SSIS Integration Runtime in which packages are running, use the following 
PowerShell commands. For each of the commands, provide the names of the Data Factory, the Azure-SSIS IR, 
and the resource group. 


For more info, see Monitor Azure-SSIS integration runtime. 


Get metadata about the Azure-SSIS Integration Runtime 


Get-AzDataFactoryV2IntegrationRuntime -DataFactoryName $DataFactoryName -Name $AzureSsisIRName - 
ResourceGroupName $ResourceGroupName 


Get the status of the Azure-SSIS Integration Runtime 


Get-AzDataFactoryV2IntegrationRuntime -Status -DataFactoryName $DataFactoryName -Name $AzureSsisIRName - 
ResourceGroupName $ResourceGroupName 


Next steps 


e Learn how to schedule package execution. For more info, see Schedule SSIS package execution on Azure 


Connect to the SSIS Catalog (SSISDB) in Azure 
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Find the connection information you need to connect to the SSIS Catalog (SSISDB) hosted on an Azure SQL 
Database server. You need the following items to connect: 


e fully qualified server name 
e database name 


e login information 





IMPORTANT 


You can't create the SSISDB Catalog database on Azure SQL Database at this time independently of creating the Azure- 
SSIS Integration Runtime in Azure Data Factory. The Azure-SSIS IR is the runtime environment that runs SSIS packages on 
Azure. For a walkthrough of the process, see Deploy and run an SSIS package in Azure. 








Prerequisites 


Before you start, make sure you have version 17.2 or later of SQL Server Management Studio (SSMS). If the 
SSISDB Catalog database is hosted on SQL Managed Instance, make sure you have version 17.6 or later of 
SSMS. To download the latest version of SSMS, see Download SQL Server Management Studio (SSMS). 


Get the connection info from the Azure portal 


1. Log in to the Azure portal. 


2. In the Azure portal, select SQL Databases from the left-hand menu, and then select the sstspB 
database on the SQL databases page. 


3. On the Overview page for the ss1spB database, review the fully qualified server name as shown in the 


following image. Hover over the server name to bring up the Click to copy option. 
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SETTINGS ¥ 


4. If you have forgotten the login information for the SQL Database server, navigate to the SQL Database 
server page. There you can view the server admin name and, if necessary, reset the password. 


Connect with SSMS 


1. Open SQL Server Management Studio. 


2. Connect to the server. In the Connect to Server dialog box, enter the following information: 


SETTING SUGGESTED VALUE 


Server type 


Database Engine 


Server name The fully qualified server name 


Authentication SQL Server Authentication 

















Login The server admin account 
Password The password for your server admin 
account 
cae Connect to Server x 
SQL Server 
Server type: 
Server name: 
Authentication: SQL Server Authentication v 
Login: v 
Password: 














Cancel Help 


Options >> 








DESCRIPTION 


This value is required. 


The name should be in this format: 
mysqldbserver.database.windo 
ws.net. 


This is the account that you 
specified when you created the 
server. 


This is the password that you 
specified when you created the 
server. 


3. Connect to the SSISDB database. Select Options to expand the Connect to Server dialog box. In 


the expanded Connect to Server dialog box, select the Connection Properties tab. In the Connect to 


database field, select or enter ssrspB . 


IMPORTANT 


If you don't select ssispB_ when you connect, you may not see the SSIS Catalog in Object Explorer. 
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4. Then select Connect. 


5. In Object Explorer, expand Integration Services Catalogs and then expand SSISDB to view the objects 
in the SSIS Catalog database. 








Connecty ¥ *F & YT a ah 





© Databases 

© Security 

©) Server Objects 

© Replication 

© PolyBase 

© Always On High Availability 
©) Management 


Integration Services Catalogs 
| & SSISDB 


o XEvent Profiler 








0 
AR HHA RAA # 














o 








Next steps 


e Deploy a package. For more info, see Deploy an SSIS project with SQL Server Management Studio (SSMS). 
e Runa package. For more info, see Run an SSIS package with SQL Server Management Studio (SSMS). 


e Schedule a package. For more info, see Schedule SSIS packages in Azure 


Validate SQL Server Integration Services (SSIS) 


packages deployed to Azure 
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When you deploy a SQL Server Integration Services (SSIS) project to the SSIS Catalog (SSISDB) on an Azure 
server, the Package Deployment Wizard adds an additional validation step after the Review page. This validation 
step checks the packages in the project for known issues that may prevent the packages from running as 
expected in the Azure SSIS Integration Runtime. Then the wizard displays any applicable warnings on the 
Validate page. 


IMPORTANT 


The validation described in this article occurs when you deploy a project with SQL Server Data Tools (SSDT) version 17.4 or 
later. To get the latest version of SSDT, see Download SQL Server Data Tools (SSDT). 





For more info about the Package Deployment Wizard, see Deploy Integration Services (SSIS) Projects and 
Packages. 


Validate connection managers 
The wizard checks certain connection managers for the following issues, which may cause the connection to fail: 


e Windows authentication. If a connection string uses Windows authentication, validation raises a warning. 
Windows authentication requires additional configuration steps. For more info, see Connect to data and file 
shares with Windows Authentication. 

e File path. If a connection string contains a hard-coded local file path like c:\\... , validation raises a 
warning. Packages that contain an absolute path may fail. 

e UNC path. If a connection string contains a UNC path, validation raises a warning. Packages that contain a 
UNC path may fail, typically because a UNC path requires Windows authentication to access. 

e Host name. If a server property contains host name instead of IP address, validation raises a warning. 
Packages that contain host name may fail, typically because the Azure virtual network requires the correct 
DNS configuration to support DNS name resolution. 

e Provider or driver. If a provider or driver is not supported, validation raises a warning. Only a small 
number of built-in providers and drivers are supported at this time. 


The wizard does the following validation checks for the connection managers in the list. 


WINDOWS 
CONNECTION AUTHENTICATIO PROVIDER OR 
MANAGER N FILE PATH UNC PATH HOST NAME DRIVER 
Ado ace" ace" ace" 
AdoNet ace" ace" ace" 


Cache ace" ace" 


WINDOWS 


CONNECTION AUTHENTICATIO PROVIDER OR 
MANAGER N FILE PATH UNC PATH HOST NAME DRIVER 
Excel ace" ace" 

File ace" ace" 

FlatFile ace" ace" 

Ftp ace” 

MsOLAP100 ace” ace” 
MultiFile ace" dace" 

MultiFlatFile ace" dace" 

OData dace" doe" 

Odbc ace" doe" dace" 
OleDb ace" doe" dace" 
SmoServer ace" doe" 

Smtp ace” ace" 

SqlMobile aoe” ace” 

Wmi ace" 


Validate sources and destinations 


The following third-party sources and destinations are not supported: 


e Oracle Source and Destination by Attunity 
e Teradata Source and Destination by Attunity 


e SAP BW Source and Destination 


Validate tasks and components 


Execute Process Task 


Validation raises a warning if a command points to a local file with an absolute path, or to a file with a UNC path. 


These paths may cause execution on Azure to fail. 


Script Task and Script Component 

Validation raises a warning if a package contains a script task or a script component, which may reference or call 
unsupported assemblies. These references or calls may cause execution to fail. 

Other components 


The Orc format is not supported in the HDFS Destination and the Azure Data Lake Store Destination. 


Next steps 


To learn how to schedule package execution on Azure, see Schedule SSIS packages in Azure. 


Run SQL Server Integration Services (SSIS) 


packages deployed in Azure 
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Applies to: Q sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


You can run SSIS packages deployed to the SSISDB Catalog on an Azure SQL Database server by choosing one 
of the methods described in this article. You can run a package directly, or run a package as part of an Azure 
Data Factory pipeline. For an overview about SSIS on Azure, see Deploy and run SSIS packages in Azure. 


e Runa package directly 
© Run with SSMS 
o Run with stored procedures 
© Run with script or code 
e Runa package as part of an Azure Data Factory pipeline 
o Run with the Execute SSIS Package activity 


o Run with the Stored Procedure activity 





NOTE 


Running a package with dtexec.exe has not been tested with packages deployed to Azure. 











Run a package with SSMS 


In SQL Server Management Studio (SSMS), you can right-click on a package deployed to the SSIS Catalog 
database, SSISDB, and select Execute to open the Execute Package dialog box. For more info, see Run an SSIS 
package with SQL Server Management Studio (SSMS). 


Run a package with stored procedures 


In any environment from which you can connect to Azure SQL Database and run Transact-SQL code, you can run 
a package by calling the following stored procedures: 


1. [catalog].[create_execution]. For more info, see catalog.create_execution. 


2. [catalog].[set_execution_parameter_value]. For more info, see 
catalog.set_execution_parameter_value. 


3. [catalog].[start_execution]. For more info, see catalog.start_execution. 
For more info, see the following examples: 
e Runan SSIS package from SSMS with Transact-SQL 


e Runan SSIS package from Visual Studio Code with Transact-SQL 


Run a package with script or code 


In any development environment from which you can call a managed API, you can run a package by calling the 
Execute method of the Package object in the Microsoft.SQLServer.Management.IntegrationServices namespace. 


For more info, see the following examples: 
e Runan SSIS package with PowerShell 


e Runan SSIS package with C# code in a NET app 


Run a package with the Execute SSIS Package activity 


For more info, see Run an SSIS package using the Execute SSIS Package Activity in Azure Data Factory. 


Run a package with the Stored Procedure activity 


For more info, see Run an SSIS package using stored procedure activity in Azure Data Factory. 


Next steps 


Learn about options for scheduling SSIS packages deployed to Azure. For more info, see Schedule SSIS 
packages in Azure. 


Schedule the execution of SQL Server Integration 


Services (SSIS) packages deployed in Azure 
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Applies to: Q sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


You can schedule the execution of SSIS packages deployed to the SSISDB Catalog on an Azure SQL Database 
server by choosing one of the methods described in this article. You can schedule a package directly, or schedule 
a package indirectly as part of an Azure Data Factory pipeline. For an overview about SSIS on Azure, see Lift and 
shift SQL Server Integration Services workloads to the cloud. 


e Schedule a package directly 
o Schedule with the Schedule option in SQL Server Management Studio (SSMS) 
o SQL Database elastic jobs 
o SQL Server Agent 


e Schedule a package indirectly as part of an Azure Data Factory pipeline 


Schedule a package with SSMS 


In SQL Server Management Studio (SSMS), you can right-click on a package deployed to the SSIS Catalog 
database, SSISDB, and select Schedule to open the New schedule dialog box. For more info, see Schedule 
SSIS packages in Azure with SSMS. 


This feature requires SQL Server Management Studio version 17.7 or higher. To get the latest version of SSMS, 
see Download SQL Server Management Studio (SSMS). 


Schedule a package with SQL Database Elastic Jobs 
For more info about elastic jobs on SQL Database, see Managing scaled-out cloud databases. 


Prerequisites 
Before you can use elastic jobs to schedule SSIS packages stored in the SSISDB Catalog database on an Azure 


SQL Database server, you have to do the following things: 


1. Install and configure the Elastic Database jobs components. For more info, see Installing Elastic Database 
jobs overview. 


2. Create database-scoped credentials that jobs can use to send commands to the SSIS Catalog database. 
For more info, see CREATE DATABASE SCOPED CREDENTIAL (Transact-SQL). 


Create an elastic job 


Create the job by using a Transact-SQL script similar to the script shown in the following example: 


-- Create Elastic Jobs target group 
EXEC jobs.sp_add_target_group 'TargetGroup' 


-- Add Elastic Jobs target group member 
EXEC jobs.sp_add_target_group_member @target_group_name='TargetGroup' , 





@target_type='SqlDatabase', @server_name='YourSQLDBServer.database.windows.net', 
@database_name='SSISDB" 


-- Add a job to schedule SSIS package execution 
EXEC jobs.sp_add_job @job_name='ExecutePackageJob', @description='Description' , 
@schedule_interval_type='Minutes', @schedule_interval_count=60 


-- Add a job step to create/start SSIS package execution using SSISDB catalog stored procedures 
EXEC jobs.sp_add_jobstep @job_name='ExecutePackageJob', 
@command=N'DECLARE @exe_id bigint 
EXEC [SSISDB]. [catalog]. [create_execution] 
@folder_name=N''folderName'', @project_name=N' 'projectName'', 
@package_name=N' 'packageName'', @use32bitruntime=@, 
@runinscaleout=1, @useanyworker=1, 
@execution_id=@exe_id OUTPUT 
EXEC [SSISDB].[catalog].[start_execution] @exe_id, @retry_count=0', 
@credential_name='YourDBScopedCredentials', 
@target_group_name='TargetGroup' 


-- Enable the job schedule 


EXEC jobs.sp_update_job @job_name='ExecutePackageJob', @enabled=1, 
@schedule_interval_type='"Minutes', @schedule_interval_count=60 


Schedule a package with SQL Server Agent on premises 


For more info about SQL Server Agent, see SQL Server Agent Jobs for Packages. 


Prerequisite - Create a linked server 


Before you can use SQL Server Agent on premises to schedule execution of packages stored on an Azure SQL 
Database server, you have to add the SQL Database server to your on-premises SQL Server as a linked server. 


1. Set up the linked server 


-- Add the SSISDB database on your Azure SQL Database as a linked server to your SQL Server on 


premises 
EXEC sp_addlinkedserver 
@server='myLinkedServer', -- Name your linked server 
@srvproduct="", 
@provider='sqincli', -- Use SQL Server native client 
@datasrc='<server_name>.database.windows.net', -- Add your Azure SQL Database server endpoint 


@location="", 
@provstr="', 
@catalog='SSISDB' -- Add SSISDB as the initial catalog 


2. Set up linked server credentials 


-- Add your Azure SQL Database server admin credentials 
EXEC sp_addlinkedsrvlogin 


@rmtsrvname = 'myLinkedServer', 

@useself = ‘false’, 

@rmtuser = 'myUsername', -- Add your server admin username 
@rmtpassword = 'myPassword' -- Add your server admin password 


3. Set up linked server options 


EXEC sp_serveroption 'myLinkedServer', ‘rpc out’, true; 


For more info, see Create Linked Servers and Linked Servers. 


Create a SQL Server Agent job 


To schedule a package with SQL Server Agent on premises, create a job with a job step that calls the SSIS 
Catalog stored procedures [catalog].[create_execution] and then [catalog].[start_execution] . For more info, 


see SQL Server Agent Jobs for Packages. 


1. In SQL Server Management Studio, connect to the on-premises SQL Server database on which you want 
to create the job. 


2. Right-click on the SQL Server Agent node, select New, and then select Job to open the New Job 
dialog box. 


3. In the New Job dialog box, select the Steps page, and then select New to open the New Job Step 
dialog box. 


4. In the New Job Step dialog box, select ssispB as the Database. 


5. Inthe Command field, enter a Transact-SQL script similar to the script shown in the following example: 


-- T-SQL script to create and start SSIS package execution using SSISDB stored procedures 
DECLARE @return_value int, @exe_id bigint 


EXEC @return_value = [YourLinkedServer].[SSISDB].[catalog].[create_execution] 
@folder_name=N'folderName', @project_name=N'projectName’ , 
@package_name=N'packageName', @use32bitruntime=0, @runincluster=1, @useanyworker=1, 


@execution_id=@exe_id OUTPUT 


EXEC [YourLinkedServer].[SSISDB].[catalog].[set_execution_parameter_value] @exe_id, 
@object_type=50, @parameter_name=N'SYNCHRONIZED', @parameter_value=1 


EXEC [YourLinkedServer].[SSISDB].[catalog].[start_execution] @execution_id=@exe_id 


6. Finish configuring and scheduling the job. 


Schedule a package as part of an Azure Data Factory pipeline 


You can schedule a package indirectly by using a trigger to run an Azure Data Factory pipeline that runs an SSIS 
package. 


To schedule a Data Factory pipeline, use one of the following triggers: 

e Schedule trigger 

e Tumbling window trigger 

e Event-based trigger 

To run an SSIS package as part of a Data Factory pipeline, use one of the following activities: 
e Execute SSIS Package activity. 


e Stored Procedure activity. 


Next steps 


Review the options for running SSIS packages deployed to Azure. For more info, see Run SSIS packages in 


Azure. 


Schedule the execution of SSIS packages deployed 
in Azure with SQL Server Management Studio 


(SSIS 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


You can use SQL Server Management Studio (SSMS) to schedule SSIS packages deployed to Azure SQL 
Database. SQL Server on premises and SQL Managed Instance have SQL Server Agent and Managed Instance 
Agent respectively as a first-class SSIS job scheduler. SQL Database, on the other hand, does not have a built-in 
first-class SSIS job scheduler. The SSMS feature described in this article provides a familiar user interface that's 
similar to SQL Server Agent for scheduling packages deployed to SQL Database. 


If you're using SQL Database to host the SSIS catalog, ssispB , you can use this SSMS feature to generate the 
Data Factory pipelines, activities, and triggers required to schedule SSIS packages. Later you can optionally edit 
and extend these objects in Data Factory. 


When you use SSMS to schedule a package, SSIS automatically creates three new Data Factory objects, with 
names based on the name of the selected package and the timestamp. For example, if the name of the SSIS 
package is MyPackage, SSMS creates new Data Factory objects similar to the following: 


OBJECT NAME 

Pipeline Pipeline_MyPackage_2018-05-08T09_00_00Z 

Execute SSIS Package activity Activity_MyPackage_2018-05-08T09_00_00Z 

Trigger Trigger_MyPackage_2018-05-08T09_00_00Z 
Prerequisites 


The feature described in this article requires SQL Server Management Studio version 17.7 or higher. To get the 
latest version of SSMS, see Download SQL Server Management Studio (SSMS). 


Schedule a package in SSMS 


1. In SSMS, in Object Explorer, select the SSISDB database, select a folder, select a project, and then select a 
package. Right-click on the package and select Schedule. 
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2. The New Schedule dialog box opens. On the General page of the New Schedule dialog box, provide a 
name and description for the new scheduled job. 





BZ Microsoft SQL Server Management Studio i New Schedule - ag xX 
File Edit View Debug Tools Window Help Select a page 


-O/8- O-S P| Bnway BR 21% om 


# Schedule 





Connect> ¥ *¥ Oo 
Gg <server name> database.windows.net (SQL Server 12.0.2000.4) Created via SSMS scheduing feature 
® WE Databases 
3 W Integration Services Catalogs 
= © ssisos 
@ demo 
@ Projects 
4 Gl PowerSheliProject 
SI ScaleOutProject 
@ Packages 
23 inaSQUDBTables.dtsx 
23 SQLDBTable1toSQLOB2Table1.dtsx 
3, SQLDBTable2toSQLOB2ZT able2.dtsx 
23, SQLDBTableXtoSQLOB2TableY.dtsx 
£3 SQLDBroSQLDB2.dtsx 
@ Environments 
© Environmenttt 
© Environmenti2 
© Environment21 
© Environment22 


This feature will automatically create a data integration pipeline. activity and trigger under your 
Azure Dats Factory (ADF) to schedule SSIS package execution as They will be 
named “Pipeline’Actvity/Tngger_YourPackageName_YourCreation Time by I but you 
can rename them. Once created. they can be monitorediedited on ADF app 


[or | ces 


3. On the Package page of the New Schedule dialog box, select optional run-time settings and a run-time 
environment. 
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4. On the Schedule page of the New Schedule dialog box, provide the schedule settings such as 
frequency, time of day, and duration. 
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5. After you finish creating the job in the New Schedule dialog box, a confirmation appears to remind you 
about the new Data Factory objects that SSMS is going to create. If you select Yes in confirmation dialog 
box, the new Data Factory pipeline opens in the Azure portal for you to review and customize. 
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6. To customize the scheduling trigger, select New/Edit from the Trigger menu. 
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Next steps 


To learn about other methods for scheduling an SSIS package, see Schedule the execution of an SSIS package on 
Azure. 


To learn more about Azure Data Factory pipelines, activities, and triggers, see the following articles: 


e Pipelines and activities in Azure Data Factory 


e Pipeline execution and triggers in Azure Data Factory 


Migrate on-premises SSIS workloads to SSIS in ADF 
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This article lists process and tools that can help migrate SQL Server Integration Services (SSIS) workloads to 
SSIS in ADF. 


Migration overview highlights overall migration process of your ETL workloads from on-premises SSIS to SSIS 
in ADF. 


The migration process consists of two phases: Assessment and Migration. 


Assessment 


Data Migration Assistant (DMA) is a freely downloadable tool for this purpose that can be installed and executed 


locally. DMA assessment project of type Integration Services can be created to assess SSIS packages in batches 
and identify compatibility issues. 


Get Database Migration Assistant, and perform package assessment. 


Migration 


Depending on the storage types of source SSIS packages and the migration destination of database workloads, 
the steps to migrate SSIS packages and SQL Server Agent jobs that schedule SSIS package executions may vary. 


For more information, see this page. 


Next steps 


e Migrate SSIS packages to Azure SQL Managed Instance. 
e Migrate SSIS jobs to Azure Data Factory (ADF) with SQL Server Management Studio (SSMS). 


Install Integration Services (SSIS) 
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Applies to: @sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


SQL Server provides a single setup program to install any or all of its components, including Integration 
Services. Use Setup to install Integration Services with or without other SQL Server components on a single 
computer. 


This article highlights important considerations that you should know before you install Integration Services. 
Information in this article helps you evaluate your installation options so that your selection results in a 
successful installation. 


G SQL Server 


Select the Enterprise Edition: Core-based Licensing features to install. 


Global Rules 
Product Updates 
Install Setup Files Features: Feature description: 
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Sonam Client Tools Connectivity Includes the designer, runtime, and utilities 
Installation Type Integration Services that enable Integration Services to move, 
Product Key Scale Out Master integrate, and transform data between data 





Scale Out Worker Prerequisites for selected features: 
Client Tools Backwards Compatibility 
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Select All Unselect All 


Instance root directory: C:\Program Files\Microsoft SQL Server\ 
Shared feature directory: d:\Program Files\Microsoft SQL Server\ 


Shared feature directory (x86): d:\Program Files (x86)\Microsoft SQL Server\ 





Get ready to install Integration Services 


Before you install Microsoft SQL Server Integration Services, review the following information: 
© Hardware and Software Requirements for Installing SQL Server 


e Security Considerations for a SQL Server Installation 


Install standalone or side by side 


You can install SQL Server Integration Services in the following configurations: 


e You can install SQL Server Integration Services on a computer that has no previous instances of SQL 
Server. 


e You can install SQL Server side by side with an existing instance of Integration Services. 


When you upgrade to the latest version of Integration Services on a computer that has an earlier version of 


Integration Services already installed, the current version is installed side by side with the earlier version. 


For more information about upgrading Integration Services, see Upgrade Integration Services. 


Get SQL Server with Integration Services 


If you don't already have Microsoft SQL Server, download a free Evaluation Edition, or the free Developer 
Edition, from SQL Server downloads. SSIS isn't included with the Express edition of SQL Server. 


Install Integration Services 


After you review the installation requirements for SQL Server and ensure that your computer meets those 


requirements, you're ready to install Integration Services. 


If you're using the Setup Wizard to install Integration Services, you use a series of pages to specify components 
and options. 


e On the Feature Selection page, under Shared Features, select Integration Services. 


e Under Instance Features, optionally select Database Engine Services to host the SSIS Catalog 
database, ssispB , to store, manage, run, and monitor SSIS packages. 


e To install managed assemblies for Integration Services programming, also under Shared Features, 
select Client Tools SDK. 


NOTE 

Some SQL Server components that you can select for installation on the Feature Selection page of the Setup Wizard 
install a partial subset of Integration Services components. These components are useful for specific tasks, but the 
functionality of Integration Services is limited. For example, the Database Engine Services option installs the 
Integration Services components required for the SQL Server Import and Export Wizard. To ensure a complete installation 


of Integration Services, you must select Integration Services on the Feature Selection page. 











Installing a dedicated server for ETL processes 


To use a dedicated server for extraction, transformation, and loading (ETL) processes, install a local instance of 
the SQL Server Database Engine when you install Integration Services. Integration Services typically stores 
packages in an instance of the Database Engine and relies on SQL Server Agent for scheduling those packages. 
If the ETL server doesn't have an instance of the Database Engine, you have to schedule or run packages from a 
server that does have an instance of the Database Engine. As a result, the packages aren't running on the ETL 
server, but instead on the server from which they're started. As a result, the resources of the dedicated ETL 
server aren't being used as intended. Furthermore, the resources of other servers may be strained by the 
running ETL processes 


Configuring SSIS event logging 


By default, in a new installation, Integration Services is configured not to log events that are related to the 
running of packages to the Application event log. This setting prevents too many event log entries when you use 
the Data Collector feature of SQL Server. The events that aren't logged are EventID 12288, "Package started,” 
and EventID 12289, "Package finished successfully." To log these events to the Application event log, open the 
registry for editing. Then, in the registry, locate the HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Microsoft 
SQL Server\130\SSIS node, and change the DWORD value of the LogPackageExecutionToEventLog setting from 
0 to 1. 


Install additional components for Integration Services 


For a complete installation of Integration Services, select the components that you need from the following list: 


e Integration Services (SSIS). Install SSIS with the SQL Server Setup wizard. Selecting SSIS installs the 
following things: 


© Support for the SSIS Catalog on the SQL Server Database Engine. 

© Optionally, the Scale Out feature, which consists of a Master and Workers. 

0 32-bit and 64-bit SSIS components. 

9° Installing SSIS does NOT install the tools required to design and develop SSIS packages. 


e SQL Server Database Engine. Install the Database Engine with the SQL Server Setup wizard. Selecting 
the Database Engine lets you create and host the SSIS Catalog database, ssispB , to store, manage, run, 
and monitor SSIS packages. 


e SQL Server Data Tools (SSDT). To download and install SSDT, see Download SQL Server Data Tools 
(SSDT). Installing SSDT lets you design and deploy SSIS packages. SSDT installs the following things: 


°o The SSIS package design and development tools, including SSIS Designer. 
o 32-bit SSIS components only. 
o A limited version of Visual Studio (if a Visual Studio edition isn't already installed). 


o Visual Studio Tools for Applications (VSTA), the script editor used by the SSIS Script Task and Script 
Component. 


o SSIS wizards including the Deployment Wizard and the Package Upgrade Wizard. 
o SQL Server Import and Export Wizard. 


e SQL Server Data Tools (SSDT). We've discontinued the SSDT standalone installer for Visual Studio 
2019. For Visual Studio 2019, you now can get the SSIS designer extension from the VS market place. 


e Integration Services Feature Pack for Azure. To download and install the Feature Pack, see Microsoft 
SQL Server Integration Services Feature Pack for Azure. Installing the Feature Pack lets your packages 
connect to storage and analytics services in the Azure cloud, including the following services: 


o Azure Blob Storage. 

o Azure HDinsight. 

o Azure Data Lake Store. 

o Azure Synapse Analytics. 

o Azure Data Lake Storage (Gen2). 


e Optional additional components. You can optionally download additional third-party components 
from the SQL Server Feature Package. 


© Microsoft®) Connector for SAP BW for Microsoft SQL Server(). To get these components, see 
Microsoft®) SQL Server(R) 2017 Feature Pack. 


o Microsoft Connectors for Oracle and Teradata by Attunity. To get these components, see Attunity 
connectors. 


Next steps 


e Installing Integration Services Versions Side by Side 
e What's New in Integration Services in SQL Server 2016 


e@ What's New in Integration Services in SQL Server 2017 


Installing Integration Services Versions Side by Side 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


You can install SQL Server 2019 (15.x) Integration Services (SSIS) side-by-side with earlier versions of SSIS. This 
topic describes some limitations of side-by-side installations. 


Designing and maintaining packages 


To design and maintain packages that target SQL Server 2016, SQL Server 2014, or SQL Server 2012, use SQL 
Server Data Tools (SSDT) for Visual Studio 2015. To get SSDT, see Download Latest SQL Server Data Tools. 


In the property pages for an Integration Services project, on the General tab of Configuration Properties, 
select the TargetServerVersion property and choose SQL Server 2016, SQL Server 2014, or SQL Server 2012. 


TARGET VERSION OF SQL SERVER DEVELOPMENT ENVIRONMENT FOR SSIS PACKAGES 
2016 SQL Server Data Tools for Visual Studio 2015 
2014 SQL Server Data Tools for Visual Studio 2015 

or 


SQL Server Data Tools - Business Intelligence for Visual 
Studio 2013 


2012 SQL Server Data Tools for Visual Studio 2015 
or 


SQL Server Data Tools - Business Intelligence for Visual 
Studio 2012 


2008 Business Intelligence Development Studio from SQL Server 
2008 


When you add an existing package to an existing project, the package is converted to the format targeted by the 
project . 


Running packages 


You can use the SQL Server 2019 (15.x) version of the dtexec utility or of SQL Server Agent to run Integration 
Services packages created by earlier versions of the development tools. When these SQL Server 2019 (15.x) 
tools load a package that was developed in an earlier version of the development tools, the tool temporarily 
converts the package in memory to the package format that SQL Server 2019 Integration Services (SSIS) uses. 
If the package has issues that prevent a successful conversion, the SQL Server 2019 (15.x) tool can't run the 
package until those issues are resolved. For more info, see Upgrade Integration Services Packages. 
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If SQL Server 2008 Integration Services (SSIS) or later is currently installed on your computer, you can upgrade 
to SQL Server 2019 Integration Services (SSIS). 


When you upgrade to SQL Server 2019 Integration Services (SSIS) on a machine that has one of these earlier 
versions of Integration Services installed, SQL Server 2019 Integration Services (SSIS) is installed side-by-side 
with the earlier version. 


With this side-by-side install, multiple versions of dtexec utility are installed. To ensure that you run the correct 
version of the utility, at the command prompt run the utility by entering the full path (<drive>:\Program 
Files\Microsoft SQL Server\<version>\DTS\Binn). For more information about dtexec, see dtexec Utility. 


NOTE 


In previous versions of SQL Server, by default when you installed SQL Server all users in the Users group had access to 
the Integration Services service. When you install SQL Server 2016 (13.x) and later, users do not have access to the 
Integration Services service. The service is secure by default. After SQL Server is installed, the SQL Server administrator 
must run the DCOM Configuration tool (Dcomcnfg.exe) to grant specific users access to the Integration Services service. 
For more information, see Integration Services Service (SSIS Service). 











Before Upgrading Integration Services 


We recommended that you run Upgrade Advisor before you upgrade to SQL Server 2019 (15.x). Upgrade 
Advisor reports issues that you might encounter if you migrate existing Integration Services packages to the 
new package format that SQL Server 2019 (15.x) uses. 





NOTE 


Support for migrating or running Data Transformation Services (DTS) packages has been discontinued in SQL Server 
2012. The following DTS functionality has been discontinued. 


e DTS runtime 

e DTS API 

e Package Migration Wizard for migrating DTS packages to the next version of Integration Services 
e Support for DTS package maintenance in SQL Server Management Studio 

e Execute DTS 2000 Package task 

e Upgrade Advisor scan of DTS packages. 


For information about other discontinued features, see Discontinued Integration Services Functionality in SQL Server 
2016. 





Upgrading Integration Services 


You can upgrade by using one of the following methods: 


e Run SQL Server 2019 (15.x) Setup and select the option to Upgrade from SQL Server 2008, SQL 
Server 2008 R2, SQL Server 2012 (11.x), or SQL Server 2014 (12.x). 





e Run setup.exe at the command prompt and specify the /ACTION =upgrade option. For more 
information, see the section, "Installation Scripts for Integration Services," in Install SQL Server 2016 
from the Command Prompt. 


You cannot use upgrade to perform the following actions: 
e Reconfigure an existing installation of Integration Services. 
e Move from a 32-bit to a 64-bit version of SQL Server or from a 64-bit version to a 32-bit version. 


e Move from one localized version of SQL Server to another localized version. 


When you upgrade, you can upgrade both Integration Services and the Database Engine, or just upgrade the 
Database Engine, or just upgrade Integration Services. If you upgrade only the Database Engine, SQL Server 
2008 Integration Services (SSIS) or later remains functional, but you do not have the functionality of SQL Server 
2019 Integration Services (SSIS). If you upgrade only Integration Services, SQL Server 2019 Integration Services 
(SSIS) is fully functional, but can only store packages in the file system, unless an instance of the SQL Server 
2019 Database Engine is available on another computer. 


Upgrading Both Integration Services and the Database Engine to SQL 
Server 2019 (15.x) 


This section describes the effects of performing an upgrade that has the following criteria: 
e You upgrade both Integration Services and an instance of the Database Engine to SQL Server 2019 (15.x). 
e Both Integration Services and the instance of the Database Engine are on the same computer. 


What the Upgrade Process Does 


The upgrade process does the following tasks: 


e Installs the SQL Server 2019 Integration Services (SSIS) files, service, and tools (Management Studio and 
SQL Server Data Tools). When there are multiple instances of SQL Server 2008, SQL Server 2008 R2, SQL 
Server 2012 (11.x), or SQL Server 2014 (12.x) on the same computer, the first time you upgrade any of 
the instances to SQL Server 2019 (15.x), the SQL Server 2019 Integration Services (SSIS) files, service, 
and tools are installed. 


e Upgrades the instance of the SQL Server 2008, SQL Server 2008 R2, SQL Server 2012 (11.x), or SQL 
Server 2014 (12.x)Database Engine to the SQL Server 2019 (15.x) version. 


e Moves data from the SQL Server 2008 Integration Services (SSIS) or later system tables to the SQL 
Server 2019 Integration Services (SSIS) system tables, as follows: 


o Moves packages without change from the msdb.dbo.sysdtspackages90 system table to the 
msdb.dbo.sysssispackages system table. 


NOTE 


Although the data moves to a different system table, the upgrade process does not migrate packages to 


the new format. 











o Moves folder metadata from the msdb.sysdtsfolders90 system table to the msdb.sysssisfolders 
system table. 


o Moves log data from the msdb.sysdtslog90 system table to the msdb.sysssislog system table. 


e Removes the msdb.sysdts*90 system tables and the stored procedures that are used to access them after 
moving the data to the new msdb:sysssis* tables. However, upgrade replaces the sysdtslog90 table with a 


view that is also named sysdtslog90. This new sysdtslog90 view exposes the new msdb.sysssislog system 
table. This ensures that reports based on the log table continue to run without interruption. 


To control access to packages, creates three new fixed database-level roles: db_ssisadmin, db_ssisltduser, 
and db_ssisoperator. The SQL Server 2005 (9.x)Integration Services roles of db_dtsadmin, db_dtsltduser, 
and db_dtsoperator are not removed, but are made members of the corresponding new roles. 


If the SSIS package store (that is, the file system location managed by the Integration Services service) is 
the default location under \SQL Server\90,\SQL Server\100,\SQL Server\110, or \SQL 
Server\120 moves those packages to the new default location under \SQL Server\130. 


Updates the Integration Services service configuration file to point to the upgraded instance of the 
Database Engine. 


What the Upgrade Process Does Not Do 


The upgrade process does not do the following tasks: 


Does not remove the SQL Server 2008 Integration Services (SSIS) or later service. 


Does not migrate existing Integration Services packages to the new package format that SQL Server 
2019 (15.x) uses. For information about how to migrate packages, see Upgrade Integration Services 
Packages. 


Does not move packages from file system locations, other than the default location, that have been added 
to the service configuration file. If you have previously edited the service configuration file to add more 
file system folders, packages that are stored in those folders will not be moved to a new location. 


In SQL Server Agent job steps that call the dtexec utility (dtexec.exe) directly, does not update the file 
system path for the dtexec utility. You have to edit these job steps manually to update the file system 
path to specify the SQL Server 2019 (15.x) location for the dtexec utility. 


What You Can Do After Upgrading 


After the upgrade process finishes, you can do the following tasks: 


Run SQL Server Agent jobs that run packages. 


Use Management Studio to manage Integration Services packages that are stored in an instance of SQL 
Server 2008, SQL Server 2008 R2, SQL Server 2012 (11.x), or SQL Server 2014 (12.x). You need to 
modify the service configuration file to add the instance of SQL Server 2008, SQL Server 2008 R2, SQL 
Server 2012 (11.x), or SQL Server 2014 (12.x) to the list of locations managed by the service. 





NOTE 


Early versions of Management Studio cannot connect to SQL Server 2019 Integration Services (SSIS) Service. 





Identify the version of packages in the msdb.dbo.sysssispackages system table by checking the value in 
the packageformat column. The table has a packageformat column that identifies the version of each 
package. A value of 3 indicates a SQL Server 2008 Integration Services (SSIS) package. Until you migrate 
packages to the new package format, the value in the packageformat column does not change. 


You cannot use the SQL Server 2008, SQL Server 2008 R2, SQL Server 2012 (11.x), or SQL Server 2014 
(12.x) tools to design, run, or manage Integration Services packages. The SQL Server 2008, SQL Server 
2008 R2, SQL Server 2012 (11.x), or SQL Server 2014 (12.x) tools include the respective versions of SQL 
Server Data Tools (SSDT), the SQL Server Import and Export Wizard, and the Package Execution Utility 
(dtexecui.exe). The upgrade process does not remove the SQL Server 2008, SQL Server 2008 R2, SQL 
Server 2012 (11.x), or SQL Server 2014 (12.x)tools. However, you will not able to use these tools to 
continue to work with SQL Server 2008 Integration Services (SSIS) or later packages on a server that has 


been upgraded. 


e By default, in an upgrade installation, Integration Services is configured to log events that are related to 
the running of packages to the Application event log. This setting might generate too many event log 
entries when you use the Data Collector feature of SQL Server 2019 (15.x). The events that are logged 
include EventID 12288, "Package started," and EventID 12289, "Package finished successfully." To stop 
logging these two events to the Application event log, open the registry for editing. Then in the registry, 
locate the HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Microsoft SQL Server\130\SSIS node, and 
change the DWORD value of the LogPackageExecutionToEventLog setting from 1 to 0. 


Upgrading only the Database Engine to SQL Server 2019 (15.x) 
This section describes the effects of performing an upgrade that has the following criteria: 


e You upgrade only an instance of the Database Engine. That is, the instance of the Database Engine is now 
an instance of SQL Server 2019 (15.x), but the instance of Integration Services and the client tools are 
from SQL Server 2008, SQL Server 2008 R2, SQL Server 2012 (11.x), or SQL Server 2014 (12.x). 


e The instance of the Database Engine is on one computer, and Integration Services and the client tools are 
on another computer. 


What You Can Do After Upgrading 


The system tables that store packages in the upgraded instance of the Database Engine are not the same as 
those used in SQL Server 2008. Therefore, the SQL Server 2008 versions of Management Studio and SQL 
Server Data Tools cannot discover the packages in the system tables on the upgraded instance of the Database 
Engine. Because these packages cannot be discovered, there are limitations on what you can do with those 
packages: 


e You cannot use the SQL Server 2008 tools, Management Studio and SQL Server Data Tools, on other 
computers to load or manage packages from the upgraded instance of the Database Engine. 





NOTE 


Although the packages in the upgraded instance of the Database Engine have not yet been migrated to the new 


package format, they are not discoverable by the SQL Server 2008 tools. Therefore, the packages cannot be used 
by the SQL Server 2008 tools. 








e You cannot use SQL Server 2008 Integration Services (SSIS) on other computers to run packages that are 
stored in msdb on the upgraded instance of the Database Engine. 


e You cannot use SQL Server Agent jobs on SQL Server 2008 computers to run SQL Server 2008 


Integration Services (SSIS) packages that are stored in the upgraded instance of the Database Engine. 


External Resources 


Blog entry, Making your Existing Custom SSIS Extensions and Applications Work in Denali, on blogs.msdn.com. 
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When you upgrade an instance of SQL Server 2008 to the current release of SQL Server, your existing SQL 


Server 2008 Integration Services (SSIS) packages are not automatically upgraded to the package format that the 


current release SQL Serverlntegration Services uses. You will have to select an upgrade method and manually 


upgrade your packages. 


For information on upgrading packages when you convert a project to the project deployment model, see 


Deploy Integration Services (SSIS) Projects and Packages 


Selecting an Upgrade Method 


You can use various methods to upgrade SQL Server 2008, SQL Server 2008 R2, SQL Server 2012 (11.x), or 
SQL Server 2014 (12.x) packages. For some of these methods, the upgrade is only temporary. For others, the 


upgrade is permanent. The following table describes each of these methods and whether the upgrade is 


temporary or permanent. 


NOTE 


NOTE 





UPGRADE METHOD 


Use the dtexec utility (dtexec.exe) that is installed with the 
current release of SQL Server to run a SQL Server 2008, SQL 
Server 2008 R2, SQL Server 2012 (11.x), or SQL Server 2014 
(12.x) package. 


For more information, see dtexec Utility. 


Open a SQL Server 2008, SQL Server 2008 R2, SQL Server 
2012 (11.x), or SQL Server 2014 (12.x) package file in SQL 
Server Data Tools (SSDT). 


Add a SQL Server 2008, SQL Server 2008 R2, SQL Server 
2012 (11.x), or SQL Server 2014 (12.x) package to an 
existing project in SQL Server Data Tools (SSDT). 


When you run a SQL Server 2008, SQL Server 2008 R2, SQL Server 2012 (11.x), or SQL Server 2014 (12.x) package using 
the dtexec utility (dtexec.exe) that is installed with the current release of SQL Server, the temporary package upgrade 
increases the execution time. The rate of increase in package execution time varies depending on the size of the package. 
To avoid an increase in the execution time, it is recommended that you upgrade the package before running it. 


For Script components referencing SSIS related assemblies which bind with version, upgrade process will not take care of 
but keep them unchanged. Manual update reference to the new version is needed. 


TYPE OF UPGRADE 


The package upgrade is temporary. 


The changes cannot be saved. 


The package upgrade is permanent if you save the package; 
otherwise, it is temporary if you do not save the package. 


The package upgrade is permanent. 





UPGRADE METHOD TYPE OF UPGRADE 


Open a SQL Server 2008 Integration Services (SSIS) or later The package upgrade is permanent. 
project file in Visual Studio, and then use the SSIS Package 
Upgrade Wizard to upgrade multiple packages in the project. 


For more information, see Upgrade Integration Services 
Packages Using the SSIS Package Upgrade Wizard and SSIS 
Package Upgrade Wizard F1 Help. 


Use the Upgrade method to upgrade one or more The package upgrade is permanent. 
Integration Services packages. 


Custom Applications and Custom Components 


SQL Server 2005 Integration Services (SSIS) custom components will not work with the current release of SQL 


ServerIntegration Services. 


You can use the current release of SQL Serverlntegration Services tools to run and manage packages that 
include SQL Server 2008, SQL Server 2008 R2, SQL Server 2012 (11.x), or SQL Server 2014 (12.x)SSIS custom 
components. We added four binding redirection rules to the following files to help redirect the runtime 
assemblies from version 10.0.0.0 (SQL Server 2008 R2), version 11.0.0.0 (SQL Server 2012 (11.x)), or version 
12.0.0.0 (SQL Server 2014 (12.x)) to version 15.0.0.0 (SQL Server 2019 (15.x)). 


e DTExec.exe.config 

e dtshost.exe.config 

e DTSWizard.exe.config 
e DTUtil.exe.config 

e DTExecUl.exe.config 


To use SQL Server Data Tools to design packages that include SQL Server 2008, SQL Server 2008 R2, SQL 
Server 2012 (11.x), or SQL Server 2014 (12.x) custom components, you need to modify the devenv.exe.config 
file that is located at <drive>:\Program Files\Microsoft Visual Studio 10.0\Common/\IDE. 


To use these packages with customer applications that are built with the runtime for SQL Server 2019 (15.x), 
include redirection rules in the configuration section of the *.exe.config file for the executable. The rules redirect 
the runtime assemblies to version 15.0.0.0 (SQL Server 2019 (15.x)). For more information about assembly 
version redirection, see <assemblyBinding> Element for <runtime>. 


Locating the Assemblies 


In SQL Server 2019 (15.x), the Integration Services assemblies were upgraded to .NET 4.0. There is a separate 
global assembly cache for .NET 4, located in <drive>\Windows\Microsoft.NET\assembly. You can find all of the 
Integration Services assemblies under this path, usually in the GAC_MSIL folder. 


As in previous versions of SQL Server, the core Integration Services extensibility .dll files are also located at 
<drive>:\Program Files\Microsoft SQL Server\130\SDK\Assemblies. 


Understanding SQL Server Package Upgrade Results 


During the package upgrade process, most components and features in SQL Server 2008, SQL Server 2008 R2, 
SQL Server 2012 (11.x), or SQL Server 2014 (12.x) packages convert seamlessly to their counterparts in the 
current release of SQL Server. However, there are several components and features that either will not be 
upgraded or have upgrade results of which you should be aware. The following table identifies these 


components and features. 





NOTE 
To identify which packages have the issues listed in this table, run Upgrade Advisor. 





COMPONENT OR FEATURE UPGRADE RESULTS 


Connection strings For SQL Server 2008, SQL Server 2008 R2, SQL Server 2012 
(11.), or SQL Server 2014 (12.x) packages, the names of 
certain providers have changed and require different values 
in the connection strings. To update the connection strings, 
use one of the following procedures: 


Use the SSIS Package Upgrade Wizard to upgrade the 
package, and select the Update connection strings to 
use new provider names option. 


In SQL Server Data Tools (SSDT), on the General page of the 
Options dialog box, select the Update connection strings 
to use new provider names option. For more 
information about this option, see General Page. 


In SQL Server Data Tools (SSDT), open the package and 
manually change the text of the ConnectionString property. 


Note: You cannot use the previous procedures to update a 
connection string when the connection string is stored in 
either a configuration file or a data source file, or when an 
expression sets the ConnectionString property. To update 
the connection string in these cases, you must manually 
update the file or the expression. 


For more information about data sources, see Data Sources. 


Scripts that Depend on ADODB.dll 


Script Task and Script Component scripts that explicitly reference ADODB.dIl may not upgrade or run on 
machines without SQL Server Management Studio or SQL Server Data Tools (SSDT) installed. In order to 
upgrade these Script Task or Script Component scripts, it is recommended that you remove the dependency on 
ADODB.adIl. Ado.Net is the recommended alternative for managed code such as VB and C# scripts. 


Upgrade Integration Services Packages Using the 
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You can upgrade packages that were created in earlier versions of Integration Services to the Integration 
Services format that SQL Server 2019 (15.x) uses. SQL Server provides the SSIS Package Upgrade Wizard to 
help in this process. Because you can configure the wizard to backup up your original packages, you can 
continue to use the original packages if you experience upgrade difficulties. 


The SSIS Package Upgrade Wizard is installed when Integration Services is installed. 





NOTE 


The SSIS Package Upgrade Wizard is available in the Standard, Enterprise, and Developer Editions of SQL Server. 





For more information about how to upgrade Integration Services packages, see Upgrade Integration Services 
Packages. 


The remainder of this topic describes how to run the wizard and back up the original packages. 


Running the SSIS Package Upgrade Wizard 


You can run the SSIS Package Upgrade Wizard from SQL Server Data Tools (SSDT), from SQL Server 
Management Studio, or at the command prompt. 


To run the wizard from SQL Server Data Tools 


1. In SQL Server Data Tools (SSDT), create or open an Integration Services project. 


2. In Solution Explorer, right-click the SSIS Packages node, and then click Upgrade All Packages to 
upgrade all the packages under this node. 





NOTE 


When you open an Integration Services project that contains SQL Server 2008 Integration Services (SSIS) or later 
packages, Integration Services automatically opens the SSIS Package Upgrade Wizard. 








To run the wizard from SQL Server Management Studio 


e In SQL Server Management Studio, connect to Integration Services, expand the Stored Packages node, and 
right-click the File System or MSDB node, and then click Upgrade Packages. 


To run the wizard at the command prompt 
e At the command prompt, run the SSISUpgrade.exe file from the C:\Program Files\Microsoft SQL 
Server\130\DTS\Binn folder. 


Backing Up the Original Packages 


To back up the original packages, both the original packages and the upgraded packages must be stored in the 
same folder in the file system. Depending on how you run the wizard, this storage location might be 
automatically selected. 


e When you run the SSIS Package Upgrade Wizard from SQL Server Data Tools (SSDT), the wizard 
automatically stores both the original packages and upgraded packages in the same folder in the file 
system. 


e When you run the SSIS Package Upgrade Wizard from SQL Server Management Studio or at the 
command prompt, you can specify different storage locations for the original and upgraded packages. To 
back up the original packages, make sure to specify that both the original and upgraded packages are 
stored in the same folder in the file system. If you specify any other storage options, the wizard will not 
be able to back up the original packages. 


When the wizard backs up the original packages, the wizard stores a copy of the original packages in an 
SSISBackupFolder folder. The wizard creates this SSISBackupFolder folder as a subfolder to the folder that 
contains the original packages and the upgraded packages. 


To back up the original packages in SQL Server Management Studio or at the command prompt 


1. Save the original packages to a location on the file system. 





NOTE 


The backup option in the wizard only works with packages that have been stored to the file system. 





2. In SQL Server Management Studio or at the command prompt, run the SSIS Package Upgrade Wizard. 
3. On the Select Source Location page of the wizard, set the Package source property to File System. 


4. On the Select Destination Location page of the wizard, select Save to source location tosave the 
upgraded packages to the same location as the original packages. 





NOTE 


The backup option in the wizard is available only when the upgraded packages are stored in the same folder as 


the original packages. 








5. On the Select Package Management Options page of the wizard, select the Backup original 
packages option. 


To back up the original packages in SQL Server Data Tools 


1. Save the original packages to a location on the file system. 


2. On the Select Package Management Options page of the wizard, select the Backup original 


packages option. 





WARNING 


The Backup original packages option is not displayed when you open a SQL Server 2008 Integration Services 
(SSIS) or later project in SQL Server Data Tools (SSDT), which automatically launches the wizard. 








3. In SQL Server Data Tools (SSDT), run the SSIS Package Upgrade Wizard. 
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Integration Services includes two studios for working with packages: 


e SQL Server Data Tools (SSDT) for developing the Integration Services packages that a business solution 
requires. SQL Server Data Tools (SSDT) provides the Integration Services project in which you create 
packages. 


e SQL Server Management Studio for managing packages in a production environment. 


SQL Server Data Tools 
Working in SQL Server Data Tools (SSDT), you can perform the following tasks: 


e Run the SQL Server Import and Export Wizard to create basic packages that copy data from a source toa 
destination. 


e Create packages that include complex control flow, data flow, event-driven logic, and logging. 


e Test and debug packages by using the troubleshooting and monitoring features in SSIS Designer, and the 
debugging features in SQL Server Data Tools (SSDT). 


e Create configurations that update the properties of packages and package objects at run time. 
e Create a deployment utility that can install packages and their dependencies on other computers. 
e Save copies of packages to the SQL Server msdb database, the SSIS Package Store, and the file system. 


For more information about SQL Server Data Tools (SSDT), see SQL Server Data Tools. 


SQL Server Management Studio 


SQL Server Management Studio provides the Integration Services service that you use to manage packages, 
monitor running packages, and determine impact and data lineage for Integration Services and SQL Server 
objects. 


Working in SQL Server Management Studio, you can perform the following tasks: 
e Create folders to organize packages in a way that is meaningful to your organization. 
e Run packages that are stored on the local computer by using the Execute Package utility. 


e Run the Execute Package utility to generate a command line to use when you run the dtexec command 
prompt utility (dtexec.exe). 


e Import and export packages to and from the SQL Server msdb database, the SSIS Package Store, and the 
file system. 


Integration Services (SSIS) Projects and Solutions 
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SQL Server provides SQL Server Data Tools (SSDT) for the development of Integration Services packages. 


Integration Services packages reside in projects. To create and work with Integration Services projects, you must 
install SQL Server Data Tools. For more information, see Install Integration Services. 


When you create a new Integration Services project in SQL Server Data Tools (SSDT), the New Project dialog 
box includes an Integration Services Project template. This project template creates a new project that 
contains a single package. 


Projects and solutions 


Projects are stored in solutions. You can create a solution first and then add an Integration Services project to 
the solution. If no solution exists, SQL Server Data Tools (SSDT) automatically creates one for you when you first 
create the project. A solution can contain multiple projects of different types. 





TIP 

By default, when you create a new project in SQL Server Data Tools, the solution is not shown in Solution Explorer 
pane. To change this default behavior, on the Tools menus, click Options. In the Options dialog box, expand Projects 
and Solutions, and then click General. On the General page, select Always show solution. 





Solutions contain projects 


A solution is a container that groups and manages the projects that you use when you develop end-to-end 
business solutions. A solution lets you handle multiple projects as one unit and to bring together one or more 
related projects that contribute to a business solution. 


Solutions can include different types of projects. If you want to use SSIS Designer to create an Integration 
Services package, you work in an Integration Services project in a solution provided by SQL Server Data Tools 
(SSDT). 


When you create a new solution, SQL Server Data Tools (SSDT) adds a Solution folder to Solution Explorer, and 
creates files that have the extensions, .sIn and .suo: 


e The *.sin file contains information about the solution configuration and lists the projects in the solution. 
@ The *.suo file contains information about your preferences for working with the solution. 


While SQL Server Data Tools (SSDT) automatically creates a solution when you create a new project, you can 
also create a blank solution, and then add projects later. 


Integration Services projects contain packages 


A project is a container in which you develop Integration Services packages. 


In SQL Server Data Tools (SSDT), an Integration Services project stores and groups the files that are related to 
the package. For example, a project includes the files that are required to create a specific extract, transfer, and 
load (ETL) solution. 





Before you create an Integration Services project, you should become familiar with the basic contents of this 
kind of project. After you understand what a project contains, you can begin creating and working with an 
Integration Services project. 


Folders in Integration Services projects 
The following diagram shows the folders in an Integration Services project in SQL Server Data Tools (SSDT). 
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The following table describes the folders that appear in an Integration Services project. 
FOLDER DESCRIPTION 


Connection Managers Contains Project Connection Managers. For more 
information, see Integration Services (SSIS) Connections. 


SSIS Packages Contains packages. For more information, see Integration 
Services (SSIS) Packages. 


Package Parts Contains Package Parts that can be reused or imported. For 
more information, see Reuse Control Flow across Packages 
by Using Control Flow Package Parts 


Miscellaneous Contains files other than package files. 


Files in Integration Services projects 


When you add a new or an existing Integration Services project to a solution, SQL Server Data Tools (SSDT) 
creates project files that have the extensions .dtproj, .dtproj.user, database, Project.params. 


e The *.dtproj file contains information about project configurations and items such as packages. 
e The *.dtproj.user file contains information about your preferences for working with the project. 


e The *.database file contains information that SQL Server Data Tools (SSDT) requires to open the 
Integration Services project. 


e The Project.params file contains information about the Project parameters. 


Version targeting in Integration Services projects 


In SQL Server Data Tools (SSDT), you can create, maintain, and run packages that target SQL Server 2017, SQL 
Server 2016, SQL Server 2014, or SQL Server 2012. 


In Solution Explorer, right-click on an Integration Services project and select Properties to open the property 


pages for the project. On the General tab of Configuration Properties, select the TargetServerVersion 
property, and then choose SQL Server 2017, SQL Server 2016, SQL Server 2014, or SQL Server 2012. 
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Create a new Integration Services project 


1. Open SQL Server Data Tools (SSDT). 
2. On the File menu, point to New, and then click Project. 


3. In the New Project dialog box, select Business Intelligence, and then select the Integration Services 
Project template. 


The Integration Services Project template creates an Integration Services project that contains a 
single, empty package. 
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4. (Optional) Edit the project name and the location. 


The solution name is automatically updated to match the project name. 


5. To create a separate folder for the solution file, select Create directory for solution. This is the default 
option. 


6. If source control software is installed on the computer, select Add to source control to associate the 


project with source control. 


7. If the source control software is Microsoft Visual SourceSafe, the Visual SourceSafe Login dialog box 
opens. In Visual SourceSafe Login, provide a user name, a password, and the name of the Microsoft 
Visual SourceSafe database. Click Browse to locate the database. 


NOTE: To view and change the selected source control plug-in and to configure the source control 
environment, click Options on the Tools menu, and then expand the Source Control node. 


8. Click OK to add the solution to Solution Explorer and add the project to the solution. 


Import an existing project with the Import Project Wizard 


1. In Visual Studio, click New > Project on the File menu. 


2. Inthe Installed Templates area of the New Project window, expand Business Intelligence, and click 
Integration Services. 


3. Select Integration Services Import Project Wizard from the project types list. 

4. Type a name for the new project to be created in the Name text box. 

5. Type the path or location for the project in the Location text box, or click Browse to select one. 
6. Type a name for the solution in the Solution name text box. 

7. Click OK to launch the Integration Services Import Project Wizard dialog box. 

8. Click Next to switch to the Select Source page. 


9. If you're importing from an .ispac file, type the path including file name in the Path text box. Click 
Browse to navigate to the folder where you want the solution to be stored and type file name in the File 


name text box, and click Open. 


If you're importing from an Integration Services Catalog, type the database instance name in the 


Server name text box or click Browse and select the database instance that contains the catalog. 


Click Browse next to Path text box, expand folder in the catalog, select the project you want to import, 
and click OK. 


Click Next to switch to the Review page. 
10. Review the information and click Import to create a project based on the existing project you selected. 
11. Optional: click Save Report to save the results to a file 


12. Click Close to close the Integration Services Import Project Wizard dialog box. 


Add a project to a solution 


When you add a project, you can have Integration Services create a new, blank project, or you can add a project 
that you have already created for a different solution. You can only add a project to an existing solution when the 
solution is visible in SQL Server Data Tools (SSDT). 


Add a new project to a solution 


1. In SQL Server Data Tools (SSDT), open the solution to which you want to add a new Integration Services 


project, and do one of the following: 

e Right-click the solution, click Add, and then click New Project. 

e On the File menu, point to Add, and then click New Project. 
2. Inthe Add New Project dialog box, click Integration Services Project in the Templates pane. 
3. Optionally, edit the project name and location. 
4. Click OK. 


Add an existing project to a solution 


1. In SQL Server Data Tools (SSDT), open the solution to which you want to add an existing Integration 


Services project, and do one of the following: 
e Right-click the solution, point to Add, and then click Existing Project. 
e@ On the File menu, click Add, and then click Existing Project. 


2. Inthe Add Existing Project dialog box, browse to locate the project you want to add, and then click 
Open. 


3. The project is added to the solution folder in Solution Explorer. 


Remove a project from a solution 


You can only remove a project from a solution when the solution is visible in SQL Server Data Tools (SSDT). After 
the solution is visible, you can remove all except one project. As soon as only one project remains, SQL Server 
Data Tools (SSDT) no longer displays the solution folder and you cannot remove the last project. 


1. In SQL Server Data Tools (SSDT), open the solution from which you want to remove an Integration 


Services project. 
2. In Solution Explorer, right-click the project, and then click Unload Project. 


3. Click OK to confirm the removal. 


Add an item to a project 


1. In SQL Server Data Tools (SSDT), open the solution that contains the Integration Services project to which 


you want to add an item. 
2. In Solution Explorer, right-click the project, point to Add, and do one of the following: 


e Click New Item, and then select a template from the Templates pane in the Add New Item 


dialog box. 


e Click Existing Item, browse in the Add Existing Item dialog box to locate the item you want to 
add to the project, and then click Add. 


3. The new item appears in the appropriate folder in Solution Explorer. 


Copy project items 


You can copy objects within an Integration Services project or between Integration Services projects. You can 
also copy objects between the other types of SQL Server Data Tools (SSDT) projects, Reporting Services and 
Analysis Services. To copy between projects, the project must be part of the same SQL Server Data Tools (SSDT) 


solution. 


1. In SQL Server Data Tools (SSDT), open the Integration Services project or solution that you want to work 
with. 


2. Expand the project and item folder to copy from. 
3. Right-click the item and click Copy. 
4. Right-click the Integration Services project to copy to and click Paste. 


The items are automatically copied to the correct folder. If you copy items to the Integration Services 
project that aren't packages, the items are copied to the Miscellaneous folder. 


Next steps 


e@ Download and install SQL Server Data Tools. 


e SSIS How to Create an ETL Package 


SQL Server Integration Services (SSIS) DevOps 


Tools Azure DevOps extension 
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SSIS DevOps Tools extension is available in AZure DevOps Marketplace. 


If you do not have an Azure DevOps organization, firstly sign up for Azure Pipelines, then add SSIS DevOps 
Tools extension following the steps. 


SSIS DevOps Tools includes SSIS Build task, SSIS Deploy release task, and SSIS Catalog Configuration 
task. 


e SSIS Build task supports building dtproj files in project deployment model or package deployment 
model. 


e SSIS Deploy task supports deploying single or multiple ispac files to on-premises SSIS catalog and 
Azure-SSIS IR, or SSISDeploymentManifest files and their associated files to on-premises or Azure file 
share. 


e SSIS Catalog Configuration task supports configuring folder/project/environment of SSIS Catalog 
with a configuration file in JSON format. This task supports following scenarios: 
o Folder 
o Create folder. 
o Update folder description. 
°o Project 
o Configure value of parameters, both literal value and referenced value are supported. 
o Add environment references. 
o Environment 
o Create environment. 
o Update environment description. 


o Create or update environment variable. 


SSIS Build task 


@Tasks Variables Triggers Options Retention History 














Pipeline een , 
i bahar nero SSIS Build © @ Link settings [Ff View YAML [ii] Remove 
== Get sources Task version 0,* Vv 
SSiSRepo ss _$/SSISRepe 
Agent job 1 ae Display name * 
alatabicas Build SSIS 
sq Build SSIS oO: ': 
ssis SSIS Build t Project path ® 
‘ . $/SSISRepo/Main/ClCDTest 
t Publish Artifact: drop did 
eames = Publish build artifacts 





Project configuration @ 





Development | 





Output path @ 





$(Build.ArtifactStagingDirectory) 





Control Options v 


Output Variables v 


Properties 

Project path 

Path of the project folder or file to be built. If a folder path is specified, SSIS Build task will search all dtproj files 
recursively under this folder and build them all. 


Project path cannot be empty, set as . to build from the root folder of the repository. 


Project configuration 
Name of the project configuration to be used for build. If not supplied, it defaults to the first defined project 
configuration in each dtproj file. 


Output path 
Path of a separate folder to save build results, which can be published as build artifact via publish build artifacts 
task. 


Limitations and known issues 

e SSIS Build task relies on Visual Studio and SSIS designer, which is mandatory on build agents. Thus, to 
run SSIS Build task in the pipeline, you must choose vs2017-win2016 for Microsoft-hosted agents, or 
install Visual Studio and SSIS designer (either VS2017 + SSDT2017, or VS2019 + SSIS Projects extension) 
on self-hosted agents. 


e To build SSIS projects using any out-of-box components (including SSIS Azure feature pack, and other 
third-party components), those out-of-box components must be installed on the machine where the 
pipeline agent is running. For Microsoft-hosted agent, user can add a PowerShell Script task or Command 
Line Script task to download and install the components before SSIS Build task is executed. Below is the 
sample PowerShell script to install Azure Feature Pack: 


wget -Uri https://download.microsoft.com/download/E/E/0/EE@CB6A0-4105 -466D-A7CA- 
5E39FA9AB128/SsisAzureFeaturePack_2017_x86.msi -OutFile AFP.msi 
start -Wait -FilePath msiexec -Args "/i AFP.msi /quiet /1* log.txt" 


cat log.txt 


e Protection level EncryptSensitiveWithPassword and EncryptAllWithPassword are not supported in 
SSIS Build task. Make sure all SSIS projects in codebase are not using these two protection levels, or SSIS 
Build task will stop responding and time out during execution. 


SSIS Build task version 1.* 


Enhancements in version 1.*: 


e Remove the dependency on Visual Studio and SSIS designer. Build task can run on Microsoft-hosted 
agent or self-hosted agent with Windows OS and .NET framework 4.6.2 or higher. 


e No need of installing out-of-box components. 
e Support protection level EncryptionWithPassword and EncryptionAllWithPassword. 


Version 1.* only properties 

Project Password 

Password of the SSIS project and its packages. This argument is only valid when the protection level of the SSIS 
project and packages is EncryptSensitiveWithPassword or EncryptAllWithPassword. For package deployment 
model, all packages must share the same password specified by this argument. 


Strip Sensitive Data 


Convert the protection level of the SSIS project to DontSaveSensitve if this value is true. When protection level is 


EncryptSensitiveWithPassword or EncryptAllWithPassword, the argument Project Password must be correctly 
set. This option is only valid for project deployment model. 


SSIS Deploy task 





Pipeline Tasks Variables Retention Options _ History 
Stage 1 a Display name * 
Deployment process Deploy ispac 
F Source path * iG 
Agent job + Pp D 
aiaee $(System.DefaultWorkingDirectory)/CICD/drop 
sss Depiey, Spee iv) # Destination type* @ 


<< SSISDB Vv 


sis Deploy SSISDeploymentManifest 
wrk Destination server* @ 
$(ServerName) 


Destination path * @ 


G 
/SSISDB/$(FolderName) 
Authentication type*  @ 


Active Directory - Password v 


Username @ 
$(AADUsername) 
Password () 
$(Password) 
Overwrite existing projects or SSISDeploymentManifest files of same names * @ 


Yes ee 


Continue deployment when error occurs * @ 


No Vv 


Properties 


Source path 

Path of source ISPAC or SSISDeploymentManifest files you want to deploy. This path could be a folder path or a 

file path. 

Destination type 

Type of the destination. Currently SSIS Deploy task supports two types: 

e File System: Deploy SSISDeploymentManifest files and their associated files to a specified file system. Both 
on-premises and Azure file share are supported. 

e SS/SDB: Deploy ISPAC files to a specified SSIS catalog, which can be hosted on on-premises SQL Server or 
Azure-SSIS Integration Runtime. 

Destination server 


Name of destination SQL server. It can be the name of an on-premises SQL Server, Azure SQL Database, or 
Azure SQL Managed Instance. This property is only visible when destination type is SSISDB. 


Destination path 


Path of the destination folder where the source file will be deployed to. For example: 


e /SSISDB/<folderName> 
e@ \\<machineName>\<shareFolderName>\<optionalSubfolderName> 
SSIS Deploy task will create the folder and subfolder if they don't exist. 


Authentication type 


Authentication type to access the specified destination server. This property is only visible when Destination type 
is SSISDB. In general below authentication types are supported: 


e Windows Authentication 


e SQL Server Authentication 
e Active Directory - Password 


e Active Directory - Integrated 


But whether a specific authentication type is supported depends on destination server type and agent type. 
Detail support matrix is listed in below table. 


DESTINATION SERVER TYPE MICROSOFT-HOSTED AGENT SELF-HOSTED AGENT 

SQL server on-premises or VM N/A Windows Authentication 

Azure SQL SQL Server Authentication SQL Server Authentication 
Active Directory - Password Active Directory - Password 


Active Directory - Integrated 


Domain name 
Domain name to access the specified file system. This property is only visible when Destination type is File 
System. You can leave it empty when the user account to run the self-hosted agent has been granted read/write 


access to the specified destination path. 


Username 

Username to access the specified file system or SSISDB. This property is visible when Destination type is File 
System or Authentication type is SQL Server Authentication or Active Directory - Password. You can leave it 
empty when the destination type is file system, and the user account to run the self-hosted agent has been 
granted read/write access to the specified destination path. 


Password 

Password to access the specified file system or SSISDB. This property is visible when destination type is file 
system or authentication type is SQL Server authentication or Active Directory - password. You can leave it 
empty when destination type is file system, and the user account to run the self-hosted agent has been granted 
read/write access to the specified destination path. 


Overwrite existing projects or SSISDeploymentManifest files of the same names 


Specify whether overwrite the existing projects or SSISDeploymentManifest files of the same names. If ‘No’, 
SSIS Deploy task will skip deploying those projects or files. 


Continue deployment when error occurs 


Specify whether to continue deployment for remaining projects or files when an error occurs. If 'No', SSIS 
Deploy task will stop immediately when error occurs. 


Limitations and known issues 


SSIS Deploy task currently doesn't support the following scenarios: 


e Configuring the environment in the SSIS catalog. 

e Deploying ISPAC to Azure SQL Server or Azure SQL Managed Instance, which allow only multifactor 
authentication. 

e Deploying packages to MSDB or SSIS Package Store. 

e Uploading to an on-premises DevOps server might result in the error "The extension package size exceeds 
the maximum package size". To resolve the error, first complete the following steps. If the error persists, 
please contact Azure DevOps support. 

1. Get the publisher name of the extension you want to increase the size limit for. The publisher name 
typically is on the left side of the . character in the URL of the extension’s item details page in Azure 
Marketplace. For example, if the extension’s item details page is 

https: //marketplace.visualstudio.com/items?itemName=tylermurry.pr-auto-comment , the pu blisher name 


is tylermurry . 


2. Connect to the on-premises SQL Server instance and select the database Galler y_Configuration. 


3. Run this query by replacing <publisherName> with the publisher name from step 1: 


INSERT INTO dbo.tbl_RegistryItems VALUES (1, '#\Configuration\Service\Gallery\LargeExtensionUpload\ 
<publisherName>\', 'MaxPackageSizeMB\' ,50) 


Change 5e toa higher number if the extension is larger than 50 MBs. 


4. After you run the query, restart Internet Information Services. Try again to upload the extension. 


SSIS Deploy task version 1.* 


Enhancements in version 1.*: 
e Support protection level EncryptionWithPassword and EncryptionAllWithPassword. 


Version 1.* only properties 

Project Password 

Password to decrypt the ISPAC or DTSX files. This argument is only valid when the protection level is 
EncryptSensitiveWithPassword or EncryptAllWithPassword. 


SSIS Catalog Configuration task 


All pipelines > * Project deployment JSON File 
Pipeline Tasks ~ Variables Retention Options —_History 


development 
ie a aes 1 (SSISLab) © [A View YAML [il] Remove 





Task version 0.* v 


Agent job + 
Run on agent 
Deploy SSIS Display name * 
Be gree Configure SSIS Catalog 
[c3) Bie Hareform: Configuration file source @ 
ss Configure SSIS Catalog oi @ Fite Path 
SSIS Catalog Configuration (SSISLab) ~ 
Configuration JSON file path* @ 
$(System.DefaultWorkingDirectory)/_catalog build/projectbuildoutput 
@ Roll back configuration when error occurs © 
Target server* @ 
rver.database.windows.net 
Authentication type* @ 
SQL Server Authentication v 
Username @ 
Password @ 
$(SSISDBServerAdminPassword) 
Control Options v 
Output Variables v 
Properties 


Configuration file source 


Source of the SSIS catalog configuration JSON file. It can be "File path" or "Inline". 
Refer to details on how to define configuration JSON: 


e Refer to a sample inline configuration JSON. 
e Check JSON schema. 


Configuration JSON file path 


Path of the SSIS catalog configuration JSON file. This property is only visible when selecting "File path" as 
configuration file source. 


To use pipeline variables in configuration JSON file, you need to add a File Transform task before this task to 
substitute configuration values with pipeline variables. For more information, see JSON variable substitution. 


Inline configuration JSON 


Inline JSON of the SSIS catalog configuration. This property is only visible when selecting "Inline" as 
configuration file source. Pipeline variables can be directly used. 
Roll back configuration when error occurs 


Whether to roll back the configuration made by this task when error occurs. 


Target server 

Name of target SQL server. It can be the name of an on-premises SQL Server, Azure SQL Database, or Azure 
SQL Managed Instance. 

Authentication type 


Authentication type to access the specified target server. In general below authentication types are supported: 


e Windows Authentication 
e SQL Server Authentication 
e Active Directory - Password 


e Active Directory - Integrated 


But whether a specific authentication type is supported depends on destination server type and agent type. 
Detail support matrix is listed in below table. 


DESTINATION SERVER TYPE MICROSOFT-HOSTED AGENT SELF-HOSTED AGENT 

SQL server on-premises or VM N/A Windows Authentication 

Azure SQL SQL Server Authentication SQL Server Authentication 
Active Directory - Password Active Directory - Password 


Active Directory - Integrated 


Username 

Username to access the target SQL Server. This property is only visible when Authentication type is SQL Server 
Authentication or Active Directory - Password. 

Password 


Password to access the target SQL Server. This property is only visible when Authentication type is SQL Server 
Authentication or Active Directory - Password. 


Define configuration JSON 


The configuration JSON schema has three layers: 


e catalog 
e folder 


@ project and environment 


folder1 


—— 


A sample inline configuration JSON 


"folders": [ 
{ 
"name": "devopsdemo", 
"description": "devops demo folder", 
"projects": [ 
{ 
"name": "catalog devops", 
"parameters": [ 
{ 
"name": "password", 
"container": "Package.dtsx", 
"value": "passwd", 
"valueType": "referenced" 
ts 
{ 
"name": "serverName", 
"container": "catalog devops", 
"value": "localhost", 
"valueType": "literal" 
} 
], 
"references": [ 
{ 
"environmentName": "test", 
"environmentFolder": "“devopsdemo" 
ts 
{ 
"environmentName": "test", 
"environmentFolder": "." 
} 
] 
t 
], 
"environments": [ 
{ 
"name": "test", 
"description": "test", 
"variables": [ 
{ 
"name": "passwd", 
Ztypeuy Strings, 
"description": "" 
"value": "$(SSISDBServerAdminPassword)", 
"sensitive": true 
ts 
{ 
"name": "serverName", 
"type": "string", 
"description": "" 
"value": "$(TargetServerName)", 
"sensitive": false 
} 
] 
i; 
] 


JSON schema 


Catalog Attributes 


PROPERTY 


folders 


Folder Attributes 


PROPERTY 


name 


description 


projects 


environments 


Project Attributes 


PROPERTY 


name 


parameters 


references 


Parameter Attributes 


PROPERTY 


name 


container 


DESCRIPTION 


An array of folder objects. Each object 
contains configuration information for 
a catalog folder. 


DESCRIPTION 


Name of the catalog folder. 


Description of the catalog folder. 


An array of project objects. Each object 
contains configuration information for 
a project. 


An array of environment objects. Each 
object contains configuration 
information for an environment. 


DESCRIPTION 


Name of the project. 


An array of parameter objects. Each 
object contains configuration 
information for a parameter. 


An array of reference objects. Each 
object represents an environment 
reference to the target project. 


DESCRIPTION 


Name of the parameter. 


Container of the parameter. 


NOTES 


See Folder Attributes for the schema of 
a folder object. 


NOTES 


Folder will be created if not exists. 


The value of nu//will be skipped. 


See Project Attributes for the schema 
of a project object. 


See Environment Attributes for the 
schema of an environment object. 


NOTES 


Project object will be skipped if project 
does not exist in the parent folder. 


See Parameter Attributes the schema 
of a parameter object. 


See Reference Attributes for the 
schema of a reference object. 


NOTES 


e@ The parameter can be a project 
parameter or a package parameter. 

e The parameter is skipped if it doesn't 
exist. 

e Ifthe parameter is a connection 
manager property, the name should 
be in the format CM.<Connection 
Manager Name>.<Property 
Name>. 


© Ifthe parameter is a project 
parameter, the container should be the 
project name. 

© If it's a package parameter, the 
container should be the package name 
with .dtsx extension. 


PROPERTY 


value 


valueType 


Reference Attributes 


PROPERTY 


environmentFolder 


environmentName 


Environment Attributes 


PROPERTY 


name 


description 


variables 


Variable Attributes 


PROPERTY 


name 


DESCRIPTION 


Value of the parameter. 


Type of the parameter value. 


DESCRIPTION 


Folder name of the environment. 


Name of the referenced environment. 


DESCRIPTION 


Name of the environment. 


Description of the environment. 


An array of variable objects. 


DESCRIPTION 


Name of the environment variable. 


NOTES 


@ When valueType is referenced The 
value is a reference to an environment 
variable in string type. 

e@ When valueType is literal This 
attribute supports any valid boolean, 
number, and string JSON values. 

© The value will be converted to the 
target parameter type. Error will occur 
if it cannot be converted. 

@ The value of nu//is invalid. The task 
will skip this parameter object, and 
give a warning. 


Valid types are: 

literat The value attribute represents a 
literal value. 

referenced. The value attribute 
represents a reference to an 
environment variable. 


NOTES 


Folder will be created if not exists. 
Value can be ".", which represents 
parent folder of the project, which 


references the environment. 


The specified environment will be 
created if not exists. 


NOTES 


Environment will be created if not 
exists. 


The value of nu//will be skipped. 


Each object contains configuration 
information for an environment 
variable.see Variable Attributes for the 
schema of a variable object. 


NOTES 


Environment variable will be created if 
not exists. 


PROPERTY 


type 


description 


value 


sensitive 


Release notes 


Version 1.0.6 
Release Date: September 1, 2021 


e@ General Availability(GA) release. 


Version 1.0.5 
Release Date: June 2, 2021 


DESCRIPTION 


Data type of the environment variable. 


Description of the environment 
variable. 


Value of the environment variable. 


Whether the value of the environment 
variable is sensitive. 


NOTES 


Valid types are: 
boolean 
byte 
datetime 
decimal 
double 
int16 
int32 
int64 
sbyte 
single 
string 
uint32 
uint64 


The value of nu//will be skipped. 


This attribute supports any valid 
boolean, number, and string JSON 
values. 

The value will be converted to the type 
specified by type attribute. Error will 
occur if conversion fails. 

The value of nu//is invalid. The task will 
skip this environment variable object, 
and give a warning. 


Valid inputs are: 
true 
false 


e Fixed an issue that sometimes SSIS Build Task of version 1.* failed to build projects/packages with protection 


level EncryptSensitiveWithPassword or EncryptAllWithPassword with the error "Specified initialization vector 


(IV) does not match the block size for this algorithm." 


e Removed the JSON content in the log of the SSIS Catalog Configuration task when "Configuration file 


source’ is "File Path". 


Version 1.0.4 
Release Date: April 21, 2021 


e SSIS Build task version 1.* (Preview) 


o Remove the dependency on Visual Studio and SSIS designer. Build task can run on Microsoft-hosted 


agent or self-hosted agent with Windows OS and .NET framework 4.6.2 or higher. 


o No need of installing out-of-box components. 


© Support protection level EncryptionWithPassword and EncryptionAllWithPassword. 
e SSIS Deploy task version 1.* (Preview) 


© Support protection level EncryptionWithPassword and EncryptionAllWithPassword. 
Version 1.0.3 
Release Date: October 21, 2020 
e Allow specifying connection string suffix for SSIS Deploy task and SSIS Catalog Configuration task. 
Version 1.0.2 
Release Date: May 26, 2020 
e Fixed an issue that SSIS Catalog Configuration task may fail in some case after configuration work is done. 
Version 1.0.1 


Release Date: May 9, 2020 


e Fixed an issue that SSIS Build task always build the whole solution even if only single dtproj file is specified 
as project path. 

Version 1.0.0 

Release Date: May 8, 2020 


@ General Availability (GA) release. 


e Added a restriction of minimum .NET framework version on agent. Currently the minimum .NET framework 
version is 4.6.2. 


e Refined description of SSIS Build task and SSIS Deploy task. 


Version 0.2.0 Preview 


Release Date: March 31, 2020 
e Add SSIS Catalog Configuration task. 


Version 0.1.3 Preview 


Release Date: January 19, 2020 
e Fixed an issue that prevented ispac from being deployed if its original file name was changed. 


Version 0.1.2 Preview 


Release Date: January 13, 2020 


e Added more detailed exception information in the SSIS Deploy task log when the destination type is SSISDB. 
e Fixed the example destination path in the help text of the property Destination path of SSIS Deploy task. 


Version 0.1.1 Preview 


Release Date: January 6, 2020 


e Added a restriction of minimal agent version requirement. Currently the minimal agent version of this 
product is 2.144.0. 


e Fixed some incorrect display text for SSIS Deploy task. 


e Refined some error messages. 


Version 0.1.0 Preview 


Release Date: December 5, 2019 


Initial release of SSIS DevOps Tools. This is a preview release. 


Next steps 


e Get SSIS DevOps extension 


Standalone SQL Server Integration Service (SSIS) 
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Standalone SSIS DevOps Tools provide a set of executables to do SSIS CICD tasks. Without the dependency on 
the installation of Visual Studio or SSIS runtime, these executables can be easily integrated with any CICD 
platform. The executables provided are: 


e SSISBuild.exe: build SSIS projects in project deployment model or package deployment model. 
e SSISDeploy.exe: deploy ISPAC files to SSIS catalog, or DTSX files and their dependencies to file system. 


Installation 


.NET framework 4.6.2 or higher is required. 

Download the latest installer from download center. Also, direct download link is available for automation script. 
Then install via wizard or command line: 

e Install via wizard 


Double-click the .exe file to install, then specify a folder to extract the executables and dependency files. 





SSIS DevOps Tools - 0.1.0 (Preview) = x 


Please type the location where you want to place the extracted files. 





[ok] | Cancel 





e Install via command line 


SSISDevOpsTools.exe /Q /C /T:<full path> 


SSIS DevOps Tools - 0.1.0 (Preview) x 


a) Command line options: 


/Q -- Quiet modes for package, 
/T:<full path> -- Specifies temporary working folder, 
/C -- Extract files only to the folder when used also with /T. 


/G<Cmd> -- Override Install Command defined by author. 





SSISBuild.exe 


Syntax 


SSISBuild.exe -project|-p:<dtproj file path> [-configuration|-c:<configuration name>] [-projectPassword|-pp: 


<project password>] [-stripSensitive|-ss] [-output|-o:<output path>] [-log|-1:<log level>[;<log path>]] [- 


quiet|-q] [-help|-h|-?] 


Parameters 


PARAMETER 


-project |-p:<dtproj file path> 


-configuration|-c:< configuration name> 


-projectPassword|-pp:< project password> 


-stripSensitive|-ss 


-output|-o0:< output path> 


-log|-I:<log level>[;<log path>] 


-quiet|-q 


-help|-h|-? 


Examples 


DESCRIPTION 


File path of the dtproj file to be built. 


Name of the project configuration to be used for build. If not 
supplied, it defaults to the first defined project configuration 
in the dtproj file. 


Password of the SSIS project and its packages. This argument 
is only valid when the protection level of the SSIS project and 
packages is EncryptSensitiveWithPassword or 
EncryptAllWithPassword. For package deployment model, all 
packages must share the same password specified by this 
argument. 


Convert the protection level of the SSIS project to 
DontSaveSensitve. When protection level is 
EncryptSensitiveWithPassword or EncryptAllWithPassword, 
the argument -projectPassword must be correctly set. This 
option is only valid for project deployment model. 


Output path of the build artifact. The value of this argument 
will overwrite the default output path in the project 
configuration. 


Log related settings. 

@ log level: Only logs with equal or higher logging level will 
be written to the log file. There are four logging levels (from 
low to high): DIAG, INFO, WRN, ERR. The default logging 
level is INFO if it's not specified. 

@ log path: Path of the file to persist logs. Log file will not be 
generated if the path is not specified. 


Do not display any logs to the standard output. 


Show detailed usage information of this command-line 
utility. 


e Build a dtproj with the first defined project configuration, not encrypted with password: 


SSISBuild.exe -p:"C:\projects\demo\demo.dtproj” 


e Build a dtproj with configuration "DevConfiguration", encrypted with password, and output the build 


artifacts to a specific folder: 


SSISBuild.exe -p:C:\projects\demo\demo.dtproj -c:DevConfiguration -pp:encryptionpassword -o:D:\folder 


e Build a dtproj with configuration "DevConfiguration", encrypted with password, striping its sensitive data, 


and log level DIAG: 


SSISBuild.exe -p:C:\projects\demo\demo.dtproj -c:DevConfiguration -pp:encryptionpassword -ss -l:diag 


SSISDeploy.exe 


Syntax 


SSISDeploy.exe -source|-s:<source path> -destination|-d:<type>;<path>[;server] [-authType|-at:<auth type 


name>] [-connectionStringSuffix|-css:<connection string suffix>] [-projectPassword|-pp:<project password>] 


[-username|-u:<username>] [-password|-p:<password>] [-log|-1:<log level>[;<log path>]] [-quiet|-q] [-help|- 


h|-?] 


Parameters 


PARAMETER 


-source|-s:<source path> 


-destination|-d:<type>;<path> [server] 


-authType|-at:<auth type name> 


-connectionStringSuffix|-css:< connection string suffix> 


-projectPassword|-pp:< project password> 


-username|-u: <username> 


-password|-p:< password> 


DESCRIPTION 


Local file path of artifacts to be deployed. ISPAC, DTSX, path 
of folder for DTSX, SSISDeploymentManfiest are allowed. 


Destination type, path of the destination folder, and server 
name of the SSIS catalog where the source file will be 
deployed to. Currently we support following two destination 
types: 

@ CATALOG: deploy single or multiple ISPAC files to the 
specified SSIS catalog. The path of CATALOG destination 
should be in such format: 

/SSISDB/< folder name> [/< project name>] 

The optional <project name> is only valid when the source 
specifies a single ISPAC file path. Server name must be 
specified for CATALOG destination. 

e FILE deploy SSIS packages or files specified in a single or 
multiple SSISDeploymentManifest files to the specified path 
of the file system. The path of FILE destination can be a local 
folder path or a network folder path in such format: 

\\< machine name>\<folder name> [\<sub folder name>...] 


Authentication type to access SQL Server. Mandatory for 
CATALOG destination. Following types are supported: 

e WIN: Windows Authentication 

@ SQL: SQL Server Authentication 

e ADPWD: Active Directory - Password 

@ ADINT: Active Directory - Integrated 


Suffix of the connection string, which is used to connect to 
the SSIS catalog. 


Password to decrypt the ISPAC or DTSxX files. 


Username to access the specified SSIS catalog or file system. 
Prefix with domain name is allowed for file system access. 


Password to access the specified SSIS catalog or file system. 


PARAMETER DESCRIPTION 


-log|-l:<log level>[;<log path>] Log related settings for running this utility. 
@ log level: Only logs with equal or higher logging level will 
be written to the log file. There are four logging levels (from 
low to high): DIAG, INFO, WRN, ERR. The default logging 
level is INFO if it's not specified. 
@ log path: Path of the file to persist logs. Log file will not be 
generated if the path is not specified. 


-quiet|-q Do not display logs to the standard output. 
-help|-h|-? Show detailed usage information of this command-line 
utility. 
Examples 


e Deploy a single ISPAC not encrypted with password to SSIS catalog with Windows authentication. 


SSISDeploy.exe -s:D:\myfolder\demo.ispac -d:catalog;/SSISDB/destfolder;myssisserver -at:win 


e@ Deploy a single ISPAC encrypted with password to SSIS catalog with SQL authentication, and rename the 


project name. 


SSISDeploy.exe -s:D:\myfolder\test.ispac -d:catalog;/SSISDB/folder/testproj;myssisserver -at:sql - 
u:sqlusername -p:sqlpassword -pp:encryptionpassword 


e Deploy a single SSISDeploymentManifest and its associated files to Azure file share. 


SSISDeploy.exe -s:D:\myfolder\mypackage.SSISDeploymentManifest - 
d:file;\\myssisshare.file.core.windows.net\destfolder -u:Azure\myssisshare -p:storagekey 


e Deploy a folder of DTSX files to on-premises file system. 


SSISDeploy.exe -s:D:\myfolder -d:file;\\myssisshare\destfolder 


Release notes 


Version 1.0.0.0 
Release Date: September 1, 2021 


e@ General Availability(GA) release. 


Version 0.1.3.1 Preview 


Release Date: June 10, 2021 


e Fixed an issue that SSISDeploy.exe failed to deploy SSIS projects with error "Unhandled Exception: 
System.1O.FileLoadException: Could not load file or assembly 
‘Microsoft.SqlServer.IntegrationServices.ProjectDeployment, Version=1.0.0.0, Culture=neutral, 
PublicKkeyToken=31bf3856ad364e35' or one of its dependencies. Strong name validation failed. (Exception 
from HRESULT: 0x8013141A) ---> System.Security.SecurityException: Strong name validation failed. 
(Exception from HRESULT: 0x8013141A)". 


Version 0.1.3 Preview 


Release Date: June 2, 2021 


Fixed an issue that SSISBuild.exe failed to build projects with error "Project consistency check failed. The 
following inconsistencies were detected" when the package name in the project contains special characters. 
Fixed an issue that SSISBUild.exe failed to build projects when there's mismatch between the name in dtproj 
and the filename. 

Fixed an issue that SS|ISBuild.exe failed to build projects with protection level 
encryptSenstiveWithPassword/EncryptAllWithPassword when the project targets SQL Server 2016. 


Version 0.1.2 Preview 


Release Date: January 14, 2021 


Fixed an issue that SS|SBuild.exe fails to build project with NullReference exception when package parameter 
metadata in SSIS project file and SSIS package mismatches. 

Fixed an issue that package fails to be executed with error starting with “Failed to decrypt protected XML 
node” though the package is deployed to SSISDB successfully with SSISDeploy.exe, when the SSIS project 
containing the package is encrypted with EncryptSensitiveWithUserKey and the package contains CM with 
sensitive data. 


Version 0.1.1 Preview 


Release Date: November 11, 2020 


Fixed an issue that SSISDeploy.exe fails to load an assembly when deploying ispac to SSIS catalog. 


Version 0.1.0 Preview 


Release Date: October 16, 2020 


Initial preview release of standalone SSIS DevOps Tools. 


Next steps 


e@ Get standalone SSIS DevOps Tools 


e If you have questions, visit QUA 


Integration Services User Interface 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


In addition to the design surfaces on the SSIS Designer tabs, the user interface provides access to the following 


windows and dialog boxes for adding features to packages and configuring the properties of package objects: 


e The dialog boxes and windows that you use to add functionality such as logging and configurations to 


packages. 


e The custom editors for configuring the properties of package objects. Almost every type of container, 


task, and data flow component has its own custom editor. 


e The Advanced Editor dialog box, a generic editor that provides more detailed configuration options for 


many data flow components. 


SQL Server Data Tools (SSDT) also provides windows and dialog boxes for configuring the environment and 


working with packages. 


Dialog Boxes and Windows 


After you open a package or create a new package in SSIS Designer, the following dialog boxes and windows are 


available. 


This table lists the dialog boxes that are available from the SSIS menu and the design surfaces of SSIS Designer. 


DIALOG BOX 


Getting Started 


Configure SSIS Logs 


Package Configuration Organizer 


PURPOSE 


Access samples, tutorials, and videos. 


Configure logging for a package and 
its tasks by adding logs and setting 
logging details. 


Add and edit package configurations. 


You run the Package Configuration 
Wizard from this dialog box. 


ACCESS 


On the design surface of the Control 
Flow tab or the Data Flow tab, right- 
click and then click Getting Started. 


To automatically display the Getting 
Started window when you create a 
new Integration Services project, select 
Always show in new project at the 
bottom of the window. 


On the SSIS menu, click Logging. 
-or- 
Right-click anywhere on the design 


surface of the Control Flow tab, and 
then click Logging. 


On the SSIS menu, click Package 
Configurations. 


-or- 
Right-click anywhere on the design 


surface of the Control Flow tab, and 
then click Package Configurations. 


DIALOG BOX PURPOSE 


Digital Signing Sign a package or remove the 
signature from the package. 


Set Breakpoints Enable breakpoints on tasks and set 
breakpoint properties. 


ACCESS 


On the SSIS menu, click Digital 
Signing. 


-or- 


Right-click anywhere on the design 
surface of the Control Flow tab, and 
then click Digital Signing. 


On the design surface of the Control 
Flow tab, right-click a task or 
container, and then click Edit 
Breakpoints. To set a breakpoint on 
the package, right-click anywhere on 
the design surface of the Control 
Flow tab, and then click Edit 
Breakpoints. 


The Getting Started window provides links to samples, tutorials, and videos. To add links to additional content, 


modify the SamplesSites.xml file that is included with the current release of SQL ServerIntegration Services. It is 


recommended that you not modify the <GettingStartedSamples> element value that specifies the RSS feed 
URL. The file is located in the <drive>\Program Files\Microsoft SQL Server\110\DTS\Binn folder. On a 64-bit 
computer, the file is located in the <drive>\Program Files(x86)\Microsoft SQL Server\110\DTS\Binn folder 


If the SamplesSites.xml file does become corrupted, replace the xml in the file with the following default xml. 


<?xml version="1.0" ?> 


- <SamplesSites> 


<GettingStartedSamples>https://go.microsoft.com/fwlink/ ?LinkID=203147</GettingStartedSamples> 


- <ToolboxSamples> 


<Site>https://go.microsoft.com/fwlink/?LinkID=203286&query=SSIS%20{@}</Site> 


</ToolboxSamples> 


</SamplesSites> 


This table lists the windows that are available from the SSIS and View menus and the design surfaces of SSIS 


Designer. 
WINDOW PURPOSE 
Variables Add and manage custom variables. 


ACCESS 


On the SSIS menu, click Variables. 
-or- 

Right-click anywhere in the design 
surface of the Control Flow and 
Data Flow tabs, and then click 
Variables. 


-or- 


On the View menu, point to Other 
Windows, and then click Variables. 


WINDOW PURPOSE ACCESS 


Log Events View log entries at run time. On the SSIS menu, click Log Events. 
-or- 
Right-click anywhere in the design 
surface of the Control Flow and 
Data Flow tabs, and then click Log 
Events. 


-or- 


On the View menu, point to Other 
Windows, and then click Log Events. 


Custom Editors 


Integration Services provides a custom dialog box for most containers, tasks, sources, transformations, and 
destinations. 


The following table describes how to access custom dialog boxes. 


EDITOR TYPE ACCESS 

Container. For more information, see Integration Services On the design surface of the Control Flow tab, double-click 

Containers. the container. 

Task. For more information, see Integration Services Tasks. On the design surface of the Control Flow tab, double-click 
the task. 

Source. On the design surface of the Data Flow tab, double-click 
the source. 

Transformation. For more information, see Integration On the design surface of the Data Flow tab, double-click 

Services Transformations. the transformation. 

Destination. On the design surface of the Data Flow tab, double-click 


the destination. 


Advanced Editor 


The Advanced Editor dialog box is a user interface for configuring data flow components. It reflects the 
properties of the component using a generic layout. The Advanced Editor dialog box is not available to 
Integration Services transformations that have multiple inputs. 


To open this editor, click ShowAdvanced Editor in the Properties window or right-click a data flow 
component, and then click ShowAdvanced Editor. 


If you create a custom source, transformation, or destination but do not want to write a custom user interface, 
you can use the Advanced Editor instead. 


SQL Server Data Tools Features 


SQL Server Data Tools (SSDT) provides windows, dialog boxes, and menu options for working with Integration 
Services packages. 


The following is a summary of the available windows and menus: 


e The Solution Explorer window lists projects, including the Integration Services project in which you 


develop Integration Services packages, and project files. 


To sort by name the packages contained in a project, right-click the SSIS Packages node and then click 


Sort by name. 
@ The Toolbox window lists the control flow and data flow items for building control flows and data flows. 
e The Properties window lists object properties. 
@ The Format menu provides options for sizing and aligning controls in a package. 
e The Edit menu provides copy and paste functionality for copying objects on the design surfaces. 
e The View menu provides options for modifying the graphical representation of objects in SSIS Designer 


For more information about additional windows and menus, see the Visual Studio documentation. 


Related Tasks 


For information about how to create packages in SQL Server Data Tools (SSDT), see Create Packages in SQL 


Server Data Tools 


See Also 


SSIS Designer 


SSIS Designer 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


SSIS Designer is a graphical tool that you can use to create and maintain Integration Services packages. SSIS 
Designer is available in SQL Server Data Tools (SSDT) as part of an Integration Services project. 


You can use SSIS Designer to perform the following tasks: 

e Constructing the control flow in a package. 

e Constructing the data flows in a package. 

e Adding event handlers to the package and package objects. 
e Viewing the package content. 

e Atrun time, viewing the execution progress of the package. 


The following diagram shows SSIS Designer and the Toolbox window. 
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v) Favorites 7] 
Provides convenient access to 
your favorite elements so that 
they are only a click away. 


Connection Managers 





Right-click here to add a new connection manager to the SSIS package. 











Integration Services includes additional dialog boxes and windows for adding functionality to packages, and 
SQL Server Data Tools (SSDT) provides dialog boxes and windows for configuring the development 


environment and working with packages. For more information, see Integration Services User Interface. 


SSIS Designer has no dependency on the Integration Services service, the service that manages and monitors 
packages, and it is not required that the service be running to create or modify packages in SSIS Designer. 
However, if you stop the service while SSIS Designer is open, you can no longer open the dialog boxes that SSIS 
Designer provides and you may receive the error message "RPC server is unavailable." To reset SSIS Designer 
and continue working with the package, you must close the designer, exit SQL Server Data Tools (SSDT), and 
then reopen SQL Server Data Tools (SSDT), the Integration Services project, and the package. 


Undo and Redo 


You can undo and redo up to 20 actions in the SSIS Designer. For a package, undo /redo is available in the 
Control Flow, Data Flow, Event Handlers, and Parameters tabs, and in the Variables window. For a 
project, undo/redo is available in the Project Parameters window. 


You can't undo/redo changes to the new SSIS Toolbox. 


When you make changes to a component using the component editor, you undo and redo the changes as a set 
rather than undoing and redoing individual changes. The set of changes appears as a single action in the undo 
and redo drop-down list. 


To undo an action, click the undo toolbar button, Edit/Undo menu item, or press CTRL+Z. To redo an action, 
click the redo toolbar button, Edit/Redo menu item or press CTRL + Y. You can undo and redo multiple actions, 
by clicking the arrow next to the toolbar button, highlighting multiple actions in the drop-down list, and then 
clicking in the list. 


Parts of the SSIS Designer 


SSIS Designer has five permanent tabs: one each for building package control flow, data flows, parameters, and 
event handlers, and one tab for viewing the contents of a package. At run time a sixth tab appears that shows 
the execution progress of a package while it is running and the execution results after it finishes. 


In addition, SSIS Designer includes the Connection Managers area for adding and configuring the connection 
managers that a package uses to connect to data. 


Control Flow Tab 


You construct the control flow in a package on the design surface of the Control Flow tab. Drag items from 
Toolbox to the design surface and connect them into a control flow by clicking the icon for the item, and then 
dragging the arrow from one item to another. 


For more information, see Control Flow. 


Data Flow Tab 


If a package contains a Data flow task, you can add data flows to the package. You construct the data flows ina 
package on the design surface of the Data Flow tab. Drag items from Toolbox to the design surface and 
connect them into a data flow by clicking the icon for the item, and then dragging the arrow from one item to 
another. 


For more information, see Data Flow. 


Parameters Tab 


Integration Services (SSIS) parameters allow you to assign values to properties within packages at the time of 
package execution. You can create project parameters at the project level and package parameters at the 
package level. Project parameters are used to supply any external input the project receives to one or more 
packages in the project. Package parameters allow you to modify package execution without having to edit and 
redeploy the package. This tab allows you to manage package parameters. 


For more information about parameters, see Integration Services (SSIS) Parameters. 


IMPORTANT!! Parameters are available only to projects developed for the project deployment model. 
Therefore, you will see the Parameters tab only for packages that are part of a project configured to use the 
project deployment model. 


Event Handlers Tab 


You construct the events in a package on the design surface of the Event Handlers tab. On the Event 


Handlers tab, you select the package or package object that you want to create an event handler for, and then 
select the event to associate with the event handler. An event handler has a control flow and optional data flows. 


For more information, see Add an Event Handler to a Package. 


Package Explorer Tab 


Packages can be complex, including many tasks, connection managers, variables, and other elements. The 


explorer view of the package lets you see a complete list of package elements. 
For more information, see View Package Objects. 


Progress/Execution Result Tab 


While a package is running, the Progress tab shows the execution progress of the package. After the package 
has finished running, the execution results remain available on the Execution Result tab. 


NOTE: To enable or disable the display of messages on the Progress tab, toggle the Debug Progress 
Reporting option on the SSIS menu. 


Connection Managers Area 

You add and modify the connection managers that a package uses in the Connection Managers area. 
Integration Services includes connection managers to connect to a variety of data sources, such as text files, OLE 
DB databases, and .NET providers. 


For more information, see Integration Services (SSIS) Connections and Create Connection Managers. 


Control Flow tab 


Use the Control Flow tab of SSIS Designer to build the control flow in a Integration Services package. 


Create the control flow by dragging graphical objects that represent SSIS tasks and containers from the 
Toolbox to the design surface of the Control Flow tab, and then connecting the objects by dragging the 
connector on an object to another object. Each connecting line represents a precedence constraint that specifies 
the order in which the tasks and containers run 


Additionally, you can use SSIS Designer to add the following functionality from the Control Flow tab: 
e Implement logging 

e Create package configurations 

e Sign the package with a certificate 

e@ Manage variables 

e Add annotations 

e Configure breakpoints 


To add these functions to individual tasks or containers in SSIS Designer, right-click the object on the design 
surface, and then select the option. 


Data Flow tab 


Use the Data Flow tab of SSIS Designer to create data flows in a Integration Services package. 


Create the data flows by dragging graphical objects that represent sources, transformations, and destinations 
from the Toolbox to the design surface of the Data Flow tab, and then connecting the objects to create paths 
that determine the sequence in which the transformations run. 


Right-click a path, and then click Data Viewers, to add data viewers to view the data before and after each data 
flow object. 


You can also use SSIS Designer to add the following functionality from the Data Flow tab: 
e Manage variables 
e Add annotations 


To add these functions in SSIS Designer, right-click the design surface, and then select the option you want. 


Event Handlers tab 


Use the Event Handlers tab of SSIS Designer to build a control flow in an Integration Services package. An 
event handler runs in response to an event raised by the package or by a task or container in the package. 


Options 


Executable 
Select the executable for which you want to build an event handler. The executable can be the package, or a task 
or containers in the package. 


Event handler 
Select a type of event handler. Create the event handler by dragging items from the Toolbox. 


Delete 
Select an event handler, and remove it from the package by clicking Delete. 


Click here to create an <event handler name> for the executable <executable name> 
Click to create the event handler. 


Create the control flow by dragging graphical objects that represent SSIS tasks and containers from the 
Toolbox to the design surface of the Event Handlers tab, and then connecting the objects by using precedence 


constraints to define the sequence in which they run. 


Additionally, to add annotations, right-click the design surface, and then on the menu, click Add Annotation. 


Package Explorer tab 


Use the Package Explorer tab of SSIS Designer to see a hierarchical view of all of the elements in a package: 
configurations, connections, event handlers, executable objects such as tasks and containers, log providers, 
precedence constraints, and variables. If a package contains a Data Flow task, the Package Explorer tab 
includes a node that contains a hierarchical view of the data flow components. 


Right-click a package element, and then click Properties to show the properties of the element in the 
Properties window, or click Delete to delete the element. 


Progress tab 


Use the Progress tab of SSIS Designer to view the progress of execution of an Integration Services package 
when you run the package in SQL Server Data Tools (SSDT). The Progress tab lists the start time, the finish 
time, and the elapsed time for validation and execution of the package and its executables; any information or 
warnings for the package; progress notifications; the success or failure of the package; and any error messages 
that are generated during package execution. 


To enable or disable the display of messages on the Progress tab, toggle the Debug Progress Reporting 
option on the SSIS menu. Disabling progress reporting can help improve performance while running a complex 


package in SQL Server Data Tools. 


After the package stops running, the Progress tab becomes the Execution Results tab. 


Connection Managers area 


Packages use connection managers to connect to data sources such as files, relational databases, and servers. 


Use the Connections Managers area of SSIS Designer to add, delete, modify, rename, and copy and paste the 


connection managers. 


Right-click in this area, and then on the menu, click the option for the task you want to perform. 


Related Tasks 


@ Create Packages in SQL Server Data Tools 


See Also 


Integration Services User Interface 


Advanced Editor 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Use the Advanced Editor dialog box to configure to configure properties for the selected Integration Services 
object. 


The Advanced Editor is available for most Integration Services objects that have configurable properties. It is 
the only editor available for those objects that do not expose a custom user interface. 


Integration Services data flow objects have properties that can be set at the component level, the input and 
output level, and the input and output column level. The Advanced Editor enumerates all the common and 
custom properties of the selected object and displays them on up to four of the following five tabs as applicable: 


e Connection Managers -- use this tab to set connection properties 

e Component Properties -- use this tab to set component-level properties 

e Column Mappings -- use this tab to map available columns as output columns 
e Input Columns -- use this tab to select input columns 


e Input and Output Properties -- use this tab to set input and output properties; and to add and remove 
outputs, select or remove columns for inputs and outputs, and set properties for inputs and outputs 


The properties displayed vary by component. For more information on the properties that may be displayed in 
the Advanced Editor, see the following topics: 


@ Common Properties 
© Transformation Custom Properties 


e Path Properties 


For more information about the specific component that you are editing, see the description of the component 
in the Data Flow Elements section of the Integration Services Objects and Concepts documentation: 


e Integration Services Transformations 


See Also 


Integration Services Error and Message Reference 


Group or Ungroup Components 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


The Control Flow, Data Flow, and Event Handlers tabs in SSIS Designer supports collapsible grouping. If a 
package has many components, the tabs can become crowded, making it difficult to view all the components at 
one time and to locate the item with which you want to work. The collapsible grouping feature can conserve 
space on the work surface and make it easier to work with large packages. 


You select the components that you want to group, group them, and then expand or collapse the groups to suit 
your work. Expanding a group provides access to the properties of the components in the group. The 
precedence constraints that connect tasks and containers are automatically included in the group. 


The following are considerations for grouping components. 


e To group components, the control flow, data flow, or event handler must contain more than one 
component. 


e Groups can also be nested, making it possible to create groups within groups. The design surface can 
implement multiple un-nested groups, but a component can belong to only one group, unless the groups 
are nested. 


e@ When a package is saved, SSIS Designer saves the grouping, but the grouping has no effect on package 
execution. The ability to group components is a design-time feature; it does not affect the run-time 
behavior of the package. 


To group components 


1. In SQL Server Data Tools (SSDT), open the Integration Services project that contains the package you 
want. 


2. In Solution Explorer, double-click the package to open it. 
3. Click the Control Flow, Data Flow, or Event Handlers tab. 


4. On the design surface of the tab, select the components you want to group, right-click a selected 
component, and then click Group. 


5. To save the updated package, click Save Selected Items on the File menu. 


To ungroup components 


1. In SQL Server Data Tools (SSDT), open the Integration Services project that contains the package you 
want. 


2. In Solution Explorer, double-click the package to open it. 
3. Click the Control Flow, Data Flow, or Event Handlers tab. 


4. On the design surface of the tab, select the group that contains the component you want to ungroup, 
right-click, and then click Ungroup. 


5. To save the updated package, click Save Selected Items on the File menu. 


See Also 


Add or Delete a Task or a Container in a Control Flow 
Connect Tasks and Containers by Using a Default Precedence Constraint 


Use Annotations in Packages 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


The SSIS Designer provides annotations, which you can use to make packages self-documenting and easier to 
understand and maintain. You can add annotations to the control flow, data flow, and event handler design 
surfaces of SSIS Designer. The annotations can contain any type of text, and they are useful for adding labels, 
comments, and other descriptive information to a package. Annotations are a design-time feature only. For 
example, they are not written to logs. 


When you press ENTER, the text wraps to the next line. The annotation box automatically increases in size as you 
add additional lines of text. Package annotations are persisted as clear text in the CDATA section of the package 
file. 


For more information about changes to the format of the package file, see SSIS Package Format. 


When you save the package, SSIS Designer saves the annotations in the package. 


Add an annotation to a package 


1. In SQL Server Data Tools (SSDT), open the Integration Services project that contains the package to which 
you want to add an annotation. 


2. In Solution Explorer, double-click the package to open it. 


3. In SSIS Designer, right-click anywhere on the design surface of the Control Flow, Data Flow, or Event 
Handler tab, and then click Add Annotation. A text block appears on the design surface of the tab. 


4. Add text. 





NOTE 


If you add no text, the text block is removed when you click outside the block. 





5. To change the size or format of the text in the annotation, right-click the annotation and then click Set 
Text Annotation Font. 


6. To add an additional line of text, press ENTER. 
The annotation box automatically increases in size as you add additional lines of text. 
7. To add an annotation to a group, right-click the annotation and then click Group. 


8. To save the updated package, on the File menu, click Save All. 


Sis] im (ele)| ole) 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


All components installed on the local machine automatically appear in the SSIS Toolbox. When you install 
additional components, right-click inside the toolbox and then click Refresh Toolbox to add the components. 


When you create a new SSIS project or open an existing project, the SSIS Toolbox displays automatically. You 
can also open the toolbox by clicking the toolbox button that is located in the top-right corner of the package 
design surface, or by clicking VIEW -> Other Windows -> SSIS Toolbox. 


NOTE 
If you can't see the toolbox, go to VIEW -> Other Windows -> SSIS Toolbox. 





Get more information about a component in the toolbox by clicking the component to view its description at the 
bottom of the toolbox. For some components you can also access samples that demonstrate how to configure 
and use the components. The samples are available on MSDN. To access the samples from the SSIS Toolbox, 
click the Find Samples link that appears below the description. 





NOTE 


You can't remove installed components from the toolbox. 





Toolbox categories 


In the SSIS Toolbox, control flow and data flow components are organized into categories. You can expand and 
collapse categories, and rearrange components. Restore the default organization by right-clicking inside the 
toolbox and then click Restore Toolbox Defaults. 


The Favorites and Common categories appear in the toolbox when you select the Control Flow, Data Flow, 
and Event Handlers tabs. The Other Tasks category appears in the toolbox when you select the Control 
Flow tab or the Event Handlers tab. The Other Transforms, Other Sources, and Other Destinations 
categories appear in the toolbox when you select the Data Flow tab. 


Add Azure components to the Toolbox 


The Azure Feature Pack for Integration Services contains connection managers to connect to Azure data sources 
and tasks to do common Azure operations. Install the Feature Pack to add these items to the Toolbox. For more 
info, see Azure Feature Pack for Integration Services (SSIS). 


Move a Toolbox item to another category 

1. Right-click an item in the SSIS Toolbox, and then click one of the following: 
e Move to Favorites 
e Move to Common 


e Move to Other Sources 


e Move to Other Destinations 
e Move to Other Transforms 


e Move to Other Tasks 


Refresh the SSIS Toolbox 


1. Right-click in the SSIS Toolbox, and then click Refresh Toolbox. 


General Page of Integration Services Designers 
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Use the General page of the Integration Services Designers page in the Options dialog box to specify the 
options for loading, displaying, and upgrading packages. 


To open the General page, in SQL Server Data Tools (SSDT), on the Tools menu, click Options, expand 
Business Intelligence Designers, and select Integration Services Designers. 


Options 


Check digital signature when loading a package 

Select to have Integration Services check the digital signature when loading a package. Integration Services will 
only check whether the digital signature is present, is valid, and is from a trusted source. Integration Services 
will not check whether the package has been changed since the package was signed. 


If you set the BlockedSignatureStates registry value, this registry value overrides the Check digital 
signature when loading a package option. For more information, see Implement a Signing Policy by Setting 
a Registry Value. 


For more information about digital certificates and packages, see Identify the Source of Packages with Digital 
Signatures. 


Show warning if package is unsigned 
Select to display a warning when loading a package that is not signed. 


Show precedence constraint labels 
Select which label-Success, Failure, or Completion-to display on precedence constraints when viewing packages 
in SQL Server Data Tools (SSDT). 


Scripting language 
Select the default scripting language for new Script tasks and Script components. 


Update connection strings to use new provider names 
When opening or upgrading SQL Server 2005 Integration Services (SSIS) packages, update connection strings 
to use the names for the following providers, for the current release of SQL Serverlntegration Services: 


e Analysis Services OLE DB provider 


e SQL Server Native Client 


The SSIS Package Upgrade Wizard updates only connection strings that are stored in connection managers. The 
wizard does not update connection strings that are constructed dynamically by using the Integration Services 
expression language, or by using code in a Script task. 


Create new package ID 
When upgrading SQL Server 2005 Integration Services (SSIS) packages, create new package IDs for the 
upgraded versions of the packages. 


See Also 


Security Overview (Integration Services) 
Extending Packages with Scripting 


Integration Services (SSIS) Packages 
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A package is an organized collection of connections, control flow elements, data flow elements, event handlers, 
variables, parameters, and configurations, that you assemble using either the graphical design tools that SQL 
Server Integration Services provides, or build programmatically. You then save the completed package to SQL 
Server, the SSIS Package Store, or the file system, or you can deploy the ssISnoversion project to the SSIS server. 
The package is the unit of work that is retrieved, executed, and saved. 


When you first create a package, it is an empty object that does nothing. To add functionality to a package, you 
add a control flow and, optionally, one or more data flows to the package. 


The following diagram shows a simple package that contains a control flow with a Data Flow task, which in turn 
contains a data flow. 


Control Flow 
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Transformation 
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After you have created the basic package, you can add advanced features such as logging and variables to 
extend package functionality. For more information, see the section about Objects that Extend Package 
Functionality. 


The completed package can then be configured by setting package-level properties that implement security, 
enable restarting of packages from checkpoints, or incorporate transactions in package workflow. For more 
information, see the section about Properties that Support Extended Features. 


Contents of a package 


Tasks and containers (control flow). A control flow consists of one or more tasks and containers that 
execute when the package runs. To control order or define the conditions for running the next task or container 
in the package control flow, you use precedence constraints to connect the tasks and containers in a package. A 
subset of tasks and containers can also be grouped and run repeatedly as a unit within the package control flow. 
For more information, see Control Flow. 


Data sources and destinations (data flow). A data flow consists of the sources and destinations that extract 
and load data, the transformations that modify and extend data, and the paths that link sources, transformations, 
and destinations. Before you can add a data flow to a package, the package control flow must include a Data 
Flow task. The Data Flow task is the executable within the SSIS package that creates, orders, and runs the data 
flow. A separate instance of the data flow engine is opened for each Data Flow task in a package. For more 
information, see Data Flow Task and Data Flow. 


Connection managers (connections). A package typically includes at least one connection manager. A 
connection manager is a link between a package and a data source that defines the connection string for 
accessing the data that the tasks, transformations, and event handlers in the package use. Integration Services 
includes connection types for data sources such as text and XML files, relational databases, and Analysis Services 
databases and projects. For more information, see Integration Services (SSIS) Connections. 


Objects that extend package functionality 


Packages can include additional objects that provide advanced features or extend existing functionality, such as 
event handlers, configurations, logging, and variables. 


Event Handlers 


An event handler is a workflow that runs in response to the events raised by a package, task, or container. For 
example, you could use an event handler to check disk space when a pre-execution event occurs or if an error 
occurs, and send an e-mail message that reports the available space or error information to an administrator. An 
event handler is constructed like a package, with a control flow and optional data flows. Event handlers can be 
added to individual tasks or containers in the package. For more information, see Integration Services (SSIS) 
Event Handlers. 


Configurations 


A configuration is a set of property-value pairs that defines the properties of the package and its tasks, 
containers, variables, connections, and event handlers when the package runs. Using configurations makes it 
possible to update properties without modifying the package. When the package is run, the configuration 
information is loaded, updating the values of properties. For example, a configuration can update the connection 
string of connection. 


The configuration is saved and then deployed with the package when the package is installed on a different 
computer. The values in the configuration can be updated when the package is installed to support the package 
in a different environment. For more information, see Create Package Configurations. 


Logging and Log Providers 


A log is a collection of information about the package that is collected when the package runs. For example, a 
log can provide the start and finish time for a package run. A log provider defines the destination type and the 
format that the package and its containers and tasks can use to log run-time information. The logs are 
associated with a package, but the tasks and containers in the package can log information to any package log. 
Integration Services includes a variety of built-in log providers for logging. For example, Integration Services 
includes log providers for SQL Server and text files. You can also create custom log providers and use them for 
logging. For more information, see Integration Services (SSIS) Logging. 


Variables 


Integration Services supports system variables and user-defined variables. The system variables provide useful 
information about package objects at run time, and user-defined variables support custom scenarios in 
packages. Both types of variables can be used in expressions, scripts, and configurations. 


The package-level variables include the pre-defined system variables available to a package and the user- 
defined variables with package scope. For more information, see Integration Services (SSIS) Variables. 


Parameters 


Integration Services parameters allow you to assign values to properties within packages at the time of package 
execution. You can create project parameters at the project level and package parameters at the package level. 
Project parameters are used to supply any external input the project receives to one or more packages in the 
project. Package parameters allow you to modify package execution without having to edit and redeploy the 
package. For more information, see Integration Services (SSIS) Parameters. 


Package properties that support extended features 


The package object can be configured to support features such as restarting the package at checkpoints, signing 
the package with a digital certificate, setting the package protection level, and ensuring data integrity by using 
transactions. 

Restarting Packages 


The package includes checkpoint properties that you can use to restart the package when one or more of its 
tasks fail. For example, if a package has two Data Flow tasks that update two different tables and the second task 
fails, the package can be rerun without repeating the first Data Flow task. Restarting a package can save time for 
long-running packages. Restarting means you can start the package from the failed task instead of having to 
rerun the whole package. For more information, see Restart Packages by Using Checkpoints. 


Securing Packages 


A package can be signed with a digital signature and encrypted by using a password or a user key. A digital 
signature authenticates the source of the package. However, you must also configure Integration Services to 
check the digital signature when the package loads. For more information, see Identify the Source of Packages 
with Digital Signatures and Access Control for Sensitive Data in Packages. 


Supporting Transactions 


Setting a transaction attribute on the package enables tasks, containers, and connections in the package to join 
the transaction. Transaction attributes ensure that the package and its elements succeed or fail as a unit. 
Packages can also run other packages and enroll other packages in transactions, so that you can run multiple 


packages as a single unit of work. For more information, see Integration Services Transactions. 


Custom log entries available on the package 


The following table lists the custom log entries for packages. For more information, see Integration Services 
(SSIS) Logging. 


LOG ENTRY DESCRIPTION 


PackageStart Indicates that the package began to run. 


Note: This log entry is automatically written to the log. You 
cannot exclude it. 


PackageEnd Indicates that the package completed. 


Note: This log entry is automatically written to the log. You 
cannot exclude it. 


Diagnostic Provides information about the system configuration that 
affects package execution such as the number executables 
that can be run concurrently. 


Set the properties of a package 


You can set properties in the Properties window of SQL Server Data Tools (SSDT) or programmatically. 


For information about how to set these properties using SQL Server Data Tools (SSDT), see Set Package 
Properties. 


For information about programmatically setting these properties, see Package. 


Reuse an existing package as a template 


Packages are frequently used as templates from which to build packages that share basic functionality. You build 
the basic package and then copy it, or you can designate the package is a template. For example, a package that 
downloads and copies files and then extracts the data may include the FTP and File System tasks in a Foreach 
Loop that enumerates files in a folder. It may also include Flat File connection managers to access the data, and 
Flat File sources to exact the data. The destination of the data varies, and the destination is added to each new 
package after it is copied from the basic package. You can also create packages and then use them as templates 
for the new packages that you add to an Integration Services project. For more information, see Create Packages 
in SQL Server Data Tools. 


When a package is first created, either programmatically or by using SSIS Designer, a GUID is added to its ID 
property and a name to its Name property. If you create a new package by copying an existing package or by 
using a template package, the name and the GUID are copied as well. This can be a problem if you use logging, 
because the GUID and the name of the package are written to the logs to identify the package to which the 
logged information belongs. Therefore, you should update the name and the GUID of the new packages to help 
differentiate them from the package from which they were copied and from each other in the log data. 


To change the package GUID, you regenerate a GUID in the ID property in the Properties window in SQL Server 
Data Tools (SSDT). To change the package name, you can update the value of the Name property in the 
Properties window. You can also use the dtutil command prompt, or update the GUID and name 
programmatically. For more information, see Set Package Properties and dtutil Utility. 


Related Tasks 


Integration Services includes two graphical tools, SSIS Designer and SQL Server Import and Export Wizard, in 
addition to the SSIS object model for creating packages. See the following topics for details. 


e Import and Export Data with the SQL Server Import and Export Wizard 
@ Create Packages in SQL Server Data Tools 


e See Building Packages Programmatically in the Developer Guide. 


Create Packages in SQL Server Data Tools 
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In SQL Server Data Tools (SSDT), you can create a new package by using one of the following methods: 

e Use the package template that Integration Services includes. 

e Use a custom template 


To use custom packages as templates for creating new packages, you simply copy them to the 
DataTransformationltems folder. By default, this folder is in C:\Program Files\Microsoft Visual Studio 
10.0\Common7\IDE\PrivateAssemblies\Projectltems\DataTransformationProject. 


e Copy an existing package. 


If existing packages include functionality that you want to reuse, you can build the control flow and data 
flows in the new package more quickly by copying and pasting objects from other packages. For more 
information about using copy and paste in Integration Services projects, see Reuse of Package Objects. 


If you create a new package by copying an existing package or by using a custom package as a template, 
the name and the GUID of the existing package are copied as well. You should update the name and the 
GUID of the new package to help differentiate it from the package from which it was copied. For example, 
if packages have the same GUID, it is more difficult to identify the package to which log data belongs. You 
can regenerate the GUID in the ID property and update the value of the Name property by using the 
Properties window in SQL Server Data Tools (SSDT). For more information, see Set Package Properties 
and dtutil Utility. 


e Use a custom package that you have designated as a template. 
e Run the SQL Server Import and Export Wizard 


The SQL Server Import and Export Wizard creates a complete package for a simple import or export. This 
wizard configures the connections, source, and destination, and adds any data transformations that are 
required to let you run the import or export immediately. You can optionally save the package to run it 
again later, or to refine and enhance the package in SQL Server Data Tools. However, if you save the 
package, you must add the package to an existing Integration Services project before you can change the 
package or run the package in SQL Server Data Tools. 


The packages that you create in SQL Server Data Tools (SSDT) using SSIS Designer are saved to the file system. 
To save a package to SQL Server or to the package store, you need to save a copy of the package. For more 
information, see Save a Copy of a Package. 


For a video that demonstrates how to create a basic package using the default package template, see Creating a 
Basic Package (SQL Server Video). 


Get SQL Server Data Tools 


To install SQL Server Data Tools (SSDT), see Download SQL Server Data Tools (SSDT). 


Create a package in SQL Server Data Tools using the Package 
Template 


. In SQL Server Data Tools (SSDT), open the Integration Services project in which you want to create a 


package. 
In Solution Explorer, right-click the SSIS Packages folder, and then click New SSIS Package. 


Optionally, add control flow, data flow tasks, and event handlers to the package. For more information, 


see Control Flow, Data Flow, and Integration Services (SSIS) Event Handlers. 


. On the File menu, click Save Selected Items to save the new package. 





NOTE 


You can save an empty package. 





Choose the target version of a project and its packages 


A, 


In Solution Explorer, right-click on an Integration Services project and select Properties to open the 
property pages for the project. 


. On the General tab of Configuration Properties, select the TargetServerVersion property, and then 


choose SQL Server 2016, SQL Server 2014, or SQL Server 2012. 


Configuration: Active(Development) ~ Platform: N/A v Configuration Manager... 


4 Common Properties ¥ Deployment Target Version {4 Solution "Integration Services Projec 
Project a a sea Server 2017 el <2 Integration Services Project1 
4 Configuration Properties ‘SQL Server 2012 P 

General SQL Server 2014 

Build ‘SQL Server 2016 

Deployment 

Debugging 


TargetServerVersion 
Specifies the version that is used to save, deploy, execute and debug packages in .. 


Ok Cancel 





You can create, maintain, and run packages that target SQL Server 2016, SQL Server 2014, or SQL Server 2012. 
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Use the Add Copy of Existing Package dialog box to add a copy of a package stored in SQL Server, the file 
system, or the SSIS Package Store to an Integration Services project. 


Options 


Package location 
Select the type of storage location from which to copy the package. 


Server 


If copying from SQL Server or the SSIS Package Store, type a server name or select a server from the list. 


Authentication type 
If copying from SQL Server, select an authentication type. 


User name 


If using SQL Server Authentication, provide a user name. 


Password 
If using SQL Server Authentication, provide a password. 


Package path 
Type the package path, or click the browse button (...) and locate the package to copy. 


See Also 


Save Copy of Package 
Save Packages 
Integration Services Service (SSIS Service) 
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When you create a package in SQL Server Data Tools (SSDT) by using the graphical interface that Integration 
Services provides, you set the properties of the package object in the Properties window. 


The Properties window provides a categorized and alphabetical list of properties. To arrange the Properties 
window by category, click the Categorized icon. 


When arranged by category, the Properties window groups properties in the following categories: 
e Checkpoints 

e Execution 

e Forced Execution Value 

e Identification 

e Misc 

e Security 

e Transactions 


e Version 


For information about additional package properties that you cannot set in the Properties window, see 
Package. 
To set package properties in the Properties window 


e Set the Properties of a Package 


Properties by Category 


The following tables list the package properties by category. 


Checkpoints 


You can use the properties in this category to restart the package from a point of failure in the package control 
flow, instead of rerunning the package from the beginning of its control flow. For more information, see Restart 
Packages by Using Checkpoints. 


PROPERTY DESCRIPTION 


CheckpointFileName The name of the file that captures the checkpoint 
information that enables a package to restart. When the 
package finishes successfully, this file is deleted. 


CheckpointUsage Specifies when a package can be restarted. The values are 
Never, IfExists, and Always. The default value of this 
property is Never, which indicates that the package cannot 
be restarted. For more information, see 
DTSCheckpointUsage. 


PROPERTY DESCRIPTION 


SaveCheckpoints Specifies whether the checkpoints are written to the 
checkpoint file when the package runs. The default value of 
this property is False. 


NOTE 
The /CheckPointing on option of dtexec is equivalent to setting the SaveCheckpoints property of the package to 


True, and the CheckpointUsage property to Always. For more information, see dtexec Utility. 





Execution 


The properties in this category configure the run-time behavior of the package object. 
PROPERTY DESCRIPTION 


DelayValidation Indicates whether package validation is delayed until the 
package runs. The default value for this property is False. 


Disable Indicates whether the package is disabled. The default value 
of this property is False. 


DisableEventHandlers Specifies whether the package event handlers run. The 
default value of this property is False. 


FailPackageOnFailure Specifies whether the package fails if an error occurs in a 
package component. The only valid value of this property is 
False. 


FailParentOnError Specifies whether the parent container fails if an error occurs 
in a child container. The default value is of this property is 
False. 


MaxConcurrentExecutables The number of executable files that the package can run 
concurrently. The default value of this property is -1, which 
indicates that there is no limit. 


MaximumeErrorCount The maximum number of errors that can occur before a 
package stops running. The default value of this property is 
1. 

PackagePriorityClass The Win32 thread priority class of the package thread. The 


values are Default, AboveNormal, Normal, 
BelowNormal, Idle. The default value of this property is 
Default. For more information, see DTSPriorityClass. 


Forced Execution Value 


The properties in this category configure an optional execution value for the package. 
PROPERTY DESCRIPTION 


ForcedExecutionValue If ForceExecutionValue is set to True, a value that specifies 
the optional execution value that the package returns. The 
default value of this property is 0. 


PROPERTY 


ForcedExecutionValueType 


ForceExecutionValue 


Identification 


DESCRIPTION 


The data type of ForcedExecutionValue. The default value of 
this property is Int32. 


A Boolean value that specifies whether the optional 
execution value of the container should be forced to contain 
a particular value. The default value of this property is False. 


The properties in this category provide information such as the unique identifier and name of the package. 


PROPERTY 


CreationDate 


CreatorComputerName 


CreatorName 


Description 


ID 


Name 


PackageType 


Misc 


DESCRIPTION 


The date that the package was created. 


The name of the computer on which the package was 
created. 


The name of the person who created the package. 


A description of package functionality. 


The package GUID, which is assigned when the package is 
created. This property is read-only. To generate a new 
random value for the ID property, select <Generate New 
ID> in the drop-down list. 


The name of the package. 


The package type. The values are Default, DTSDesigner, 
DTSDesigner100, DTSWizard, SQLDBMaint, and 
SQLReplication. The default value of this property is 
Default. For more information, see DISPackageType. 


The properties in this category are used to access the configurations and expressions that a package uses and to 


provide information about the locale and logging mode of the package. For more information, see Use Property 


Expressions in Packages. 


PROPERTY 


Configurations 


DESCRIPTION 


The collection of configurations that the package uses. Click 
the browse button (...) to view and configure package 
configurations. 


PROPERTY DESCRIPTION 


Expressions Click the browse button (...) to create expressions for 
package properties. 


Note that you can create property expressions for all the 
package properties that object model includes, not just the 
properties listed in the Properties window. 


For more information, see Use Property Expressions in 
Packages. 


To view existing property expressions, expand Expressions. 
Click the browse button (...) in an expression text box to 
modify and evaluate an expression. 


ForceExecutionResult The execution result of the package. The values are None, 
Success, Failure, and Completion. The default value of 
this property is None. For more information, see 
T:Microsoft.SqlServer.Dts.Runtime.DTSForcedExecResult. 


Localeld A Microsoft Win32 locale. The default value of this property 
is the locale of the operating system on the local computer. 


LoggingMode A value that specifies the logging behavior of the package. 
The values are Disabled, Enabled, and UseParentSetting. 
The default value of this property is UseParentSetting. For 
more information, see DTSLoggingMode. 


OfflineMode Indicates whether the package is in offline mode. This 
property is read-only. The property is set at the project level. 
Normally, SSIS Designer tries to connect to each data source 
used by your package to validate the metadata associated 
with sources and destinations. You can enable Work Offline 
from the SSIS menu, even before you open a package, to 
prevent these connection attempts and the resulting 
validation errors when the data sources are not available. 
You can also enable Work Offline to speed up operations 
in the designer, and disable it only when you want your 
package to be validated. 


SuppressConfigurationWarnings Indicates whether the warnings generated by configurations 
are suppressed. The default value of this property is False. 


UpdateObjects Indicates whether the package is updated to use newer 
versions of the objects it contains, if newer versions are 
available. For example, if this property is set to True, a 
package that includes a Bulk Insert task is updated to use 
the newer version of the Bulk Insert task that Integration 
Services provides. The default value of this property is False. 


Security 


The properties in this category are used to set the protection level of the package. For more information, see 
Access Control for Sensitive Data in Packages. 


PROPERTY DESCRIPTION 


PROPERTY 


PackagePassword 


ProtectionLevel 


Transactions 


DESCRIPTION 


The password for package protection levels 
(EncryptSensitiveWithPassword and 
EncryptAllWithPassword) that require passwords. 


The protection level of the package. The values are 
DontSaveSensitive, EncryptSensitiveWithUserKey, 
EncryptSensitiveWithPassword, 
EncryptAllWithPassword, and ServerStorage. The 
default value of this property is 
EncryptSensitiveWithUserKey. For more information, see 
DTSProtectionLevel. 


The properties in this category configure the isolation level and the transaction option of the package. For more 


information, see Integration Services Transactions. 


PROPERTY 


IsolationLevel 


DESCRIPTION 


The isolation level of the package transaction. The values are 
Unspecified, Chaos, ReadUncommitted, 
ReadCommitted, RepeatableRead, Serializable, and 
Snapshot. The default value of this property is 
Serializable. 


Note: The Snapshot value of the IsolationLevel property 
is incompatible with package transactions. Therefore, you 
cannot use the IsolationLevel property to set the isolation 
level of package transactions to Shapshot. Instead, use an 
SQL query to set package transactions to Snapshot. For 
more information, see SET TRANSACTION ISOLATION LEVEL 
(Transact-SQL). 


The system applies the IlsolationLevel property to package 
transactions only when the value of the 
TransactionOption property is Required. 


The value of the IlsolationLevel property requested by a 
child container is ignored when the following conditions are 
true: 

The value of the child container's TransactionOption 
property is Supported. 

The child container joins the transaction of a parent 
container. 


The value of the IlsolationLevel property requested by the 
container is respected only when the container initiates a 
new transaction. A container initiates a new transaction 
when the following conditions are true: 

The value of the container's TransactionOption property is 
Required. 

The parent has not already started a transaction. 


For more information, see |solationLevel. 


PROPERTY DESCRIPTION 


TransactionOption The transactional participation of the package. The values 
are NotSupported, Supported, Required. The default 
value of this property is Supported. For more information, 
see DTSTransactionOption. 


Version 


The properties in this category provide information about the version of the package object. 


PROPERTY DESCRIPTION 

VersionBuild The version number of the build of the package. 

VersionComments Comments about the version of the package. 

VersionGUID The GUID of the version of the package. This property is 
read-only. 

VersionMajor The latest major version of the package. 

VersionMinor The latest minor version of the package. 


Set package properties in the Properties window 


ile 


In SQL Server Data Tools (SSDT), open the Integration Services project that contains the package you 
want to configure. 


. InSolution Explorer, double-click the package to open it in SSIS Designer, or right-click and select View 


Designer. 


. Click the Control Flow tab and then do one of the following: 


e Right-click anywhere in the background of the control flow design surface, and then click 
Properties. 


e Onthe View menu, click Properties Window. 


Edit the package properties in the Properties window. 


. On the File menu, click Save Selected Items to save the updated package. 


View Package Objects 
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In SSIS Designer, the Package Explorer tab provides an explorer view of the package. The view reflects the 
container hierarchy of the Integration Services architecture. The package container is at the top of the hierarchy, 
and you expand the package to view the connections, executables, event handlers, log providers, precedence 
constraints, and variables in the package. 


The executables, which are the containers and tasks in the package, can include event handlers, precedence 
constraints, and variables. Integration Services supports a nested hierarchy of containers, and the For Loop, 
Foreach Loop, and Sequence containers can include other executables. 


If a package includes a data flow, the Package Explorer lists the Data Flow task and includes a Components 
folder that lists the data flow components. 


From the Package Explorer tab, you can delete objects in a package and access the Properties window to 
view object properties. 


The following diagram shows a tree view of a simple package. 
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View the package structure and content 


1. In SQL Server Data Tools (SSDT), open the Integration Services project that contains the package you 
want to view in Package Explorer. 


2. Click the Package Explorer tab. 


3. To view the contents of the Variables, Precedence Constraints, Event Handlers, Connection 
Managers, Log Providers, or Executables folders, expand each folder. 


4. Depending on the package structure, expand any next-level folders. 


View the properties of a package object 


e Right-click an object and then click Properties to open the Properties window. 


Delete an object in a package 


e Right-click an object and then click Delete. 


See Also 


Integration Services Tasks 

Integration Services Containers 
Precedence Constraints 

Integration Services (SSIS) Variables 
Integration Services (SSIS) Event Handlers 
Integration Services (SSIS) Logging 


Copy a Package in SQL Server Data Tools 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


This topic describes how to create a new Integration Services package by copying an existing package, and how 
to update the Name and GUID properties of the new package. 


To copy a package 


1. In SQL Server Data Tools (SSDT), open the Integration Services project that contains the package that you 
want to copy. 


2. In Solution Explorer, double-click the package. 


3. Verify either the package to copy is selected in Solution Explorer or the tab in SSIS Designer that contains 
the package is the active tab 


4. On the File menu, click Save <package name> As. 





NOTE 


The package must be opened in SSIS Designer before the Save As option appears on the File menu. 





5. Optionally, browse to a different folder. 
6. Update the name of the package file. Make sure that you retain the .dtsx file extension. 
7. Click Save. 


8. At the prompt, choose whether to update the name of the package object to match the file name. If you 
click Yes, the Name property of the package is updated. The new package is added to the Integration 
Services project and opened in SSIS Designer. 


9. Optionally, click in the background of the Control Flow tab, and the click Properties. 


10. In the Properties window, click the value of the ID property, and then in the drop-down list click 
<Generate New ID>. 


11. On the File menu, click Save Selected Items to save the new package. 


See Also 


Save a Copy of a Package 
Create Packages in SQL Server Data Tools 


Integration Services (SSIS) Packages 


Copy Package Objects 
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This topic describes how to copy control flow items, data flow items, and connection managers within a package 
or between packages. 


To copy control and data flow items 


1. In SQL Server Data Tools (SSDT), open the Integration Services project that contains the packages that 
you want work with. 


2. In Solution Explorer, double-click the packages that you want to copy between. 


3. In SSIS Designer, click the tab for the package that contains the items to copy and click the Control Flow, 
Data Flow, or Event Handlers tab. 


4. Select the control flow or data flow items to copy. You can either select items one at a time by pressing 
the Shift key and clicking the item or select items as a group by dragging the pointer across the items you 


want to select. 





IMPORTANT 


The precedence constraints and paths that connect items are not selected automatically when you select the two 
items that they connect. To copy an ordered workflow-a segment of control flow or data flow-make sure to also 


copy the precedence constrains and the paths. 








5. Right-click a selected item and click Copy. 


6. If copying items to a different package, click the package that you want to copy to, and then click the 


appropriate tab for the item type. 





IMPORTANT 


You cannot copy a data flow to a package unless the package contains at least one Data Flow task. 





7. Right-click and click Paste. 


To copy connection managers 


1. In SQL Server Data Tools (SSDT), open the Integration Services project that contains the package that you 
want to work with. 


2. In Solution Explorer, double-click the package. 
3. In SSIS Designer, click the Control Flow, Data Flow, or Event Handler tab. 


4. In the Connection Managers area, right-click the connection manager, and then click Copy. You can 
copy only one connection manager at a time. 


5. If you are copying items to a different package, click the package that you want to copy to and then click 
the Control Flow, Data Flow, or Event Handler tab. 


6. Right-click in the Connection Managers area and click Paste. 


See Also 


Control Flow 

Data Flow 

Integration Services (SSIS) Connections 
Copy Project Items 


Save Packages 
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In SQL Server Data Tools (SSDT) you build packages by using SSIS Designer and save the packages to the file 
system as XML files (.dtsx files). You can also save copies of the package XML file to the msdb database in SQL 
Server or to the package store. The package store represents the folders in the file system location that the 
Integration Services service manages. 


If you save a package to the file system, you can later use the Integration Services service to import the package 
to SQL Server or to the package store. For more information, see Integration Services Service (SSIS Service). 


You can also use a command prompt utility, dtutil, to copy a package between the file system and msdb. For 
more information, see dtutil Utility. 


Save a package to the file system 


1. In SQL Server Data Tools (SSDT), open the Integration Services project that contains the package you 
want to save to a file. 


2. In Solution Explorer, click the package you want to save. 


3. On the File menu, click Save Selected Items. 





NOTE 


You can verify the path and file name where the package was saved in the Properties window. 





Save a copy of a package 


This section describes how to save a copy of a package to the file system, to the package store, or to the msdb 
database in Microsoft SQL Server. When you specify a location to save the package copy, you can also update 
the name of the package. 


The package store can include both the msdb database and the folders in the file system, only msdb, or only 
folders in the file system. In msdb, packages are saved to the sysssispackages table. This table includes a 
folderid column that identifies the logical folder to which the package belongs. The logical folders provide a 
useful way to group packages saved to msdb in the same way that folders in the file system provide a way to 
group packages saved to the file system. Rows in the sysssispackagefolders table in msdb define the folders. 


If msdb is not defined as part of the package store, you can continue to associate packages with existing logical 
folders when you select SQL Server in the Package Path option. 





NOTE 


The package must be opened in SSIS Designer before you can save a copy of the package. 





To save a copy of a package 


1. In Solution Explorer, double-click the package of which you want to save a copy. 


2. On the File menu, click Save Copy of <package file> As. 


3. In the Save Copy of Package dialog box, select a package location in the Package location list. The 


following options are available: 


e SQL Server 
e File System 
e@ SSIS Package Store 


4. If the location is SQL Server or SSIS Package Store, provide a server name. 


5. If saving to SQL Server, specify the authentication type and, if using SQL Server Authentication, provide a 


user name and password. 


6. To specify the package path, either type the path or click the browse button (...) to specify the location of 
the package. The default name of the package is Package. Optionally, update the package name to one 
that suits your needs. 


If you select SQL Server as the Package Path option, the package path consists of logical folders in 
msdb and the package name. For example, if the package DownloadMonthlyData is associated with the 
Finance folder within the MSDB folder (the default name of the root logical folder in msdb), the package 
path for the package named DownloadMonthlyData is MSDB/Finance/DownloadMonthlyData 


If you select SSIS Package Store as the Package Path option, the package path consists of the folder 
that the Integration Services service manages. For example, if the package UpdateDeductions is located in 
the HumanResources folder within the file system folder that the service manages, the package path is 
/File System/HumanResources/UpdateDeductions; likewise, if the package PostResumes is associated 
with the HumanResources folder within the MSDB folder, the package path is 
MSDB/HumanResources/PostResumes. 


If you select File System as the Package Path option, the package path is the location in the file system 
and the file name. For example, if the package name is UpdateDemographics the package path is 
C:\HumanResources\Quarterly\UpdateDemographics.dtsx. 


7. Review the package protection level. 

8. Optionally, click the browse button (...) by the Protection level box to change the protection level. 
e Inthe Package Protection Level dialog box, select a different protection level. 
@ Click OK. 


9. Click OK. 


Save a package as a package template 


This section describes how to designate and use custom packages as templates when you create new 
Integration Services packages in SQL Server Data Tools (SSDT). By default, Integration Services uses a package 
template that creates an empty package when you add a new package to an Integration Services project. You 
cannot replace this default template, but you can add new templates. 


You can designate multiple packages to use as templates. Before you can implement custom packages as 
templates, you must create the packages. 


When you create package using custom packages as templates, the new packages have the same name and 
GUID as the template. To differentiate among packages you should update the value of the Name property and 
generate a new GUID for the ID property. For more information, see Create Packages in SQL Server Data Tools 
and Set Package Properties. 


To designate a custom package as a package template 


1. In the file system, locate the package that you want to use as template. 


2. Copy the package to the DataTransformationltems folder. By default this folder is in C:\Program 
Files\Microsoft Visual Studio 
9.0\Common/7\IDE\PrivateAssemblies\Projectitems\DataTransformationProject. 


3. Repeat steps 1 and 2 for each package that you want to use as a template. 


To use a custom package as a package template 


1. In SQL Server Data Tools (SSDT), open the Integration Services project in which you want to create a 
package. 


2. In Solution Explorer, right-click the project, point to Add, and then click New Item. 


3. In the Add New Item -<project name> dialog box, click the package that you want to use as a 
template. 


The list of templates includes the default package template named New SSIS Package. The package icon 
identifies templates that can be used as package templates. 


4. Click Add. 


Reuse Control Flow across Packages by Using 


Control Flow Package Parts 
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Applies to: Q sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Save a commonly used control flow task or container to a standalone part file - a ".dtsxp" file - and reuse it 
multiple times in one or more packages by using control flow package parts. This reusability makes SSIS 
packages easier to design and maintain. 


Create a new control flow package part 


To create a new control flow package part, in Solution Explorer, expand the Package Parts folder. Right-click on 
Control Flow and select New Control Flow Package Part. 


4 f@) SSIS Packages 
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New Control Flow Package Part P PackagePartl.dtsxp 


Add Existing Control Flow Package Part... 


A new part file with the ".dtsxp" extension is created under the Package Parts | Control Flow folder. At the 
same time, a new item with the same name is also added to the SSIS toolbox. (The toolbox item is only visible 
while you have a project that contains the part open in Visual Studio.) 
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Design a control flow package part 


To open the package part editor, double-click on the part file in Solution Explorer. You can design the part just 
like you design a package. 


PackagePart1.dtsxp [Design] # X 
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Control flow package parts have the following limitations. 


e Apart can have only one top-level task or container. If you want to include multiple tasks or containers, 


put them all in a single sequence container. 


e You can't run or debug a part directly in the designer. 


Add an existing control flow package part to a package 


You can reuse parts that are saved in the current Integration Services project or in a different project. 
@ To reuse a part that's part of the current project, drag and drop the part from the toolbox. 


e To reuse a part that's part of a different project, use the Add Existing Control Flow Package Part 


command. 


Drag and drop a control flow package part 

To reuse a part in a project, simply drag and drop the part item from the toolbox just like any other task or 
container. You can drag and drop the part into a package multiple times to reuse the logic in multiple locations 
in the package. Use this method to reuse a part that is part of the current project. 
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Coanecton Manages 


When you save the package, SSIS designer checks whether there are any part instances in the package. 


e Ifthe package contains part instances, the designer generates a new .dtsx.designer file which contains all 


part-related information. 


e If the package does not use parts, the designer deletes any previously created .dtsx.designer file for the 
package (that is, any .dtsx.designer file that has the same name as the package). 
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Add a copy of an existing control flow package part or a reference to an existing part 


To add a copy of an existing part in the file system to a package, in Solution Explorer, expand the Package Parts 
folder. Right-click on Control Flow and select Add Existing Control Flow Package Part. 
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Add Existing Control Flow Package Part... 
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Specify the location of the package part to be added. 


Package Part path: | on 


(D Add as a reference 





Cancel Help 


Options 


Package Part path 
Type the path to the part file, or click the browse button (...) and locate the part file to copy or to reference. 


Add as a reference 


e If selected, the part is added to the Integration Services project as a reference. Select this option when 
you when want to reference a single copy of a part file in multiple Integration Services projects. 


e If cleared, a copy of the part file is added to the project. 


Configure a control flow package part 


To configure control flow package parts after you've added them to the control flow of a package, use the 
Package Part Configuration dialog box. 


To open the Package Part Configuration dialog box 
1. To configure a part instance, double-click the part instance in the control flow. Or right-click on the part 
instance and select Edit. The Package Part Configuration dialog box opens. 


2. Configure the properties and connection managers for the part instance. 


Properties tab 


Use the Properties tab of the Package Part Configuration dialog box to specify the properties of the part. 
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The tree view hierarchy in the left pane lists all configurable properties of the part instance. 


e If cleared, the property is not configured in the part instance. The part instance uses the default value for 
the property, which is defined in the control flow package part. 


e If selected, the value that you enter or select overrides the default value. 
The table in the right pane lists the properties to configure. 

e Property Path. The property path of the property. 

e Property Type. The data type of the property. 

e Value. The configured value. This value overrides the default value. 


Connection Managers tab 


Use the Connection Managers tab of the Package Part Configuration dialog box to specify the properties 
of connection managers for the part instance. 
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The table in the left pane lists all the connection managers defined in the control flow part. Choose the 
connection manager that you want to configure. 


The list in the right pane lists the properties of the selected connection manager. 
@ Set. Checked if the property is configured for the part instance. 
e Property Name. The name of the property. 


e Value. The configured value. This value overrides the default value. 


Delete a control flow part 


To delete a part, in Solution Explorer, right-click the part, and then select Delete. Select OK to confirm the 
deletion or select Cancel to keep the part. 


If you delete a part from a project, it is deleted permanently from the file system and it cannot be restored. 





NOTE 


If you want to remove a part from an Integration Services project, but continue to use it in other projects, use the 
Exclude from Project option instead of the Delete option. 











Package parts are a design-time feature only 


Package parts are purely a design-time feature. SSIS designer creates, opens, saves, and updates parts, and 
adds, configures, or deletes part instances in a package. However, the SSIS runtime is not aware of the parts. 
Here is how the designer achieves this separation. 


e The designer saves package part instances with their configured properties to a ".dtsx.designer" file. 


e When the designer saves the ".dtsx.designer" file, it also extracts the content from the parts referenced by 
this file and replaces the part instances in the package with the content of the parts. 


e Finally all the content, which no longer includes part information, is saved back to the ".dtsx" package file. 
This is the file that the SSIS runtime runs. 


The diagram below demonstrates the relationship among parts (".dtsxp" files), SSIS designer, and the SSIS 
runtime. 


SSIS designer 
SSIS designer 





Reuse of Package Objects 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Frequently packages functionality that you want to reuse. For example, if you created a set of tasks, you might 
want to reuse the items together as a group, or you might want to reuse a single item such as a connection 
manager that you created in a different Integration Services project. 


Copy and Paste 


SQL Server Data Tools (SSDT) and SSIS Designer support copying and pasting package objects, which can 
include control flow items, data flow items, and connection managers. You can copy and paste between projects 
and between packages. If the solution contains multiple projects you can copy between projects, and the 
projects can be of different types. 


If a solution contains multiple packages, you can copy and paste between them. The packages can be in the 
same or different Integration Services projects. However, package objects may have dependencies on other 
objects, without which they are not valid. For example, an Execute SQL task uses a connection manager, which 
you must copy as well to make the task work. Also, some package objects require that the package already 
contain a certain object, and without this object you cannot successfully paste the copied objects into a package. 
For example, you cannot paste a data flow into a package that does not have at least one Data Flow task. 


You may find that you copy the same packages repeatedly. To avoid the copy process, you can designate these 
packages as templates and use them when you create new packages. 


When you copy a package object, Integration Services automatically assigns a new GUID to the ID property of 
the new object and updates the Name property. 


You cannot copy variables. If an object such as a task uses variables, then you must re-create the variables in the 
destination package. In contrast, if you copy the entire package, then the variables in the package are also 
copied. 


Related Tasks 


e@ Copy Package Objects 
@ Copy Project Items 


e Save a Package as a Package Template 


Delete Packages 
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In SQL Server Data Tools (SSDT), you can delete packages saved to the file system. If you delete a package, it is 
deleted permanently and it cannot be restored to an Integration Services project. 





NOTE 


If you want to remove packages from an Integration Services project, but use them in other projects, then you should use 
the Exclude From Project option instead of the Delete option. 








To delete a package in Business Intelligence 


1. In SQL Server Data Tools (SSDT), open the Integration Services project that contains the package you 
want to delete. 


2. In Solution Explorer, right-click the package, and then click Delete. 


3. Click OK to confirm the deletion or click Cancel to keep the package. 


dtutil Utility 
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The dtutil command prompt utility is used to manage SQL Server Integration Services packages. The utility can 
copy, move, delete, or verify the existence of a package. These actions can be performed on any SSIS package 
that is stored in one of three locations: a Microsoft SQL Server database, the SSIS Package Store, and the file 
system. If the utility accesses a package that is stored in msdb, the command prompt may require a user name 
and a password. If the instance of SQL Server uses SQL Server Authentication, the command prompt requires 
both a user name and a password. If the user name is missing, dtutil tries to log on to SQL Server using 
Windows Authentication. The storage type of the package is identified by the /SQL, /FILE, and /DTS options. 


The dtutil command prompt utility does not support the use of command files or redirection. 
The dtutil command prompt utility includes the following features: 


e@ Remarks in the command prompt, which makes the command prompt action self-documenting and 
easier to understand. 


e@ Overwrite protection, to prompt for a confirmation before overwriting an existing package when you are 
copying or moving packages. 


e Console help, to provide information about the command options for dtutil. 


NOTE 


Many of the operations that are performed by dtutil can also be performed visually in SQL Server Management Studio 
when you are connected to an instance of Integration Services. For more information, see Package Management (SSIS 
Service). 











The options can be typed in any order. The pipe ("|") character is the OR operator and is used to show possible 
values. You must use one of the options that are delimited by the OR pipe. 


All options must start with a slash (/) or a minus sign (-). However, do not include a space between the slash or 
minus sign and the text for the option; otherwise, the command will fail. 


Arguments must be strings that are either enclosed in quotation marks or contain no white space. 


Double quotation marks within strings that are enclosed in quotation marks represent escaped single quotation 
marks. 


Options and arguments, except for passwords, are not case sensitive. 
Installation Considerations on 64-bit Computers 


On a 64-bit computer, Integration Services installs a 64-bit version of the dtexec utility (dtexec.exe) and the 
dtutil utility (dtutil.exe). To install 32-bit versions of these Integration Services tools, you must select either 
Client Tools or SQL Server Data Tools (SSDT) during setup. 


By default, a 64-bit computer that has both the 64-bit and 32-bit versions of an Integration Services command 
prompt utility installed will run the 32-bit version at the command prompt. The 32-bit version runs because the 
directory path for the 32-bit version appears in the PATH environment variable before the directory path for the 
64-bit version. (Typically, the 32-bit directory path is <drive>:\Program Files(x86)\Microsoft SQL 


Server\130\DTS\Binn, while the 64-bit directory path is <drive>:\Program Files\Microsoft SQL 
Server\130\DTS\Binn.) 





NOTE 


If you use SQL Server Agent to run the utility, SQL Server Agent automatically uses the 64-bit version of the utility. SQL 


Server Agent uses the registry, not the PATH environment variable, to locate the correct executable for the utility. 











To ensure that you run the 64-bit version of the utility at the command prompt, you can take one of the 
following actions: 


@ Open a Command Prompt window, change to the directory that contains the 64-bit version of the utility 
(<drive>:\Program Files\Microsoft SQL Server\130\DTS\Binn), and then run the utility from that location. 


e Atthe command prompt, run the utility by entering the full path (<drive>:\Program Files\Microsoft SQL 
Server\130\DTS\Binn) to the 64-bit version of the utility. 


e Permanently change the order of the paths in the PATH environment variable by placing the 64-bit path 
(<drive>\Program Files\Microsoft SQL Server\130\DTS\Binn) before the 32-bit path (<drive>:\\ Program 
Files(x86)\Microsoft SQL Server\130\DTS\Binn) in the variable. 


Syntax 
dtutil /option [value] [/option [value]]... 


Parameters 


OPTION DESCRIPTION 
P? Displays the command prompt options. 


/C[opy] /ocation;destinationPathandPackageName Specifies a copy action on an SSIS package. Use of this 
parameter requires that you first specify the location of the 
package using the /Fl, /SQ, or /DT option. Next, specify the 
destination location destination package name. The 
destinationPathandPackageName argument specifies where 
the SSIS package is copied to. If the destination /ocation is 
SQL, the DestUser, DestPassword and DestServer 
arguments must also be specified in the command. 


When the Copy action encounters an existing package at 
the destination, dtutil prompts the user to confirm package 
deletion. The Y reply overwrites the package and the N reply 
ends the program. When the command includes the Quiet 
argument, no prompt appears and any existing package is 
overwritten. 


/Dec[rypt] password (Optional). Sets the decryption password that is used when 
you load a package with password encryption. 


/Del[ete] Deletes the package specified by the SQL, DTS or FILE 
option. If dtutil cannot delete the package, the program 
ends. 


OPTION 


/DestP[assword] password 


/DestS[erver] server_instance 


/DestU[ser] username 


/Dump process /D 


DESCRIPTION 


Specifies the password that is used with the SQL option to 
connect to a destination SQL Server instance using SQL 
Server Authentication. An error is generated if 
DESTPASSWORD is specified in a command line that does 
not include the D7SUSER option. 


Note: When possible, use Windows authentication.. 


Specifies the server name that is used with any action that 
causes a destination to be saved to SQL Server. It is used to 
identify a non-local or non-default server when saving an 
SSIS package. It is an error to specify DESTSERVER in a 
command line that does not have an action associated with 
SQL Server. Actions such as S/GN SQL, COPY SQL, or MOVE 
SQL options would be appropriate commands to combine 
with this option. 


A SQL Server instance name can be specified by adding a 
backslash and the instance name to the server name. 


Specifies the user name that is used with the S/GN SQL, 
COPY SQL, and MOVE SQL options to connect to a SQL 
Server instance that uses SQL Server Authentication. It is an 
error to specify DESTUSER in a command line that does not 
include the SIGN SQL, COPY SQL, or MOVE SQL option. 


(Optional) Causes the specified process, either the dtexec 
utility or the dtsDebugHost.exe process, to pause and 
create the debug dump files, .ndmp and .tmp. 


Note: To use the /Dumpoption, you must be assigned the 
Debug Programs user right (SeDebugPrivilege). 


To find the process /D for the process that you want to 
pause, use Windows Task Manager. 


By default, Integration Services stores the debug dump files 
in the folder, <drive>:\Program Files\Microsoft SQL 
Server\130\Shared\ErrorDumps. 


For more information about the dtexec utility and the 
dtsDebugHost.exe process, see dtexec Utility and Building, 
Deploying, and Debugging Custom Objects. 


For more information about debug dump files, see 
Generating Dump Files for Package Execution. 


Note: Debug dump files may contain sensitive information. 
Use an access control list (ACL) to restrict access to the files, 
or copy the files to a folder with restricted access. 


OPTION 


/DT[S] filespec 


/En[crypt] {SQL / FILE}; Path;ProtectionLevell,passworal] 


/Ex{ists] 


/FC[reate] {SQL | DTS}; ParentFolderPath;NewFolderName 


DESCRIPTION 


Specifies that the SSIS package to be operated on is located 
in the SSIS Package Store. The fi/lespec argument must 
include the folder path, starting with the root of the SSIS 
Package Store. By default, the names of the root folders in 
the configuration file are "MSDB" and "File System." Paths 
that contain a space must be delimited by using double 
quotation marks. 


If the DT[S] option is specified on the same command line as 
any of the following options, a DTEXEC_DTEXECERROR is 
returned: 

FILE 

SQL 

SOURCEUSER 


SOURCEPASSWORD 


SOURCESERVER 


(Optional). Encrypts the loaded package with the specified 
protection level and password, and saves it to the location 
specified in Path. The ProtectionLeve/ determines whether a 
password is required. 


SQL - Path is the destination package name. 


FILE - Path is the fully-qualified path and file name for the 
package. 


DTS - This option is not supported currently. 
ProtectionL evel options: 
Level 0: Strips sensitive information. 


Level 1: Sensitive information is encrypted by using local 
user credentials. 


Level 2: Sensitive information is encrypted by using the 
required password. 


Level 3: Package is encrypted by using the required 
password. 


Level 4: Package is encrypted by using local user credentials. 


Level 5 Package uses SQL Server storage encryption. 


(Optional). Used to determine whether a package exists. 
dtutil tries to locate the package specified by either the 
SQL, DTS or FILE options. If dtutil cannot locate the package 
specified, a DTEXEC_DTEXECERROR is returned. 


(Optional). Create a new folder that has the name that you 
specified in NewFolderName. The location of the new folder 
is indicated by the ParentFolderPath. 


OPTION 


/FDe[lete] {SQL | D75}[; ParentFolderPath;FolderName] 


/FDif[rectory] {SQL | DTS}; FolderPath[-s] 


/FE[xists ] {SQL | DTS};FolderPath 


/Fifle] filespec 


/FR[ename] {SQL | DT} [;ParentFolderPath; 
OldFolderName;NewFolderName] 


/H[{elp] option 


DESCRIPTION 


(Optional). Deletes from SQL Server or SSIS the folder that 
was specified by the name in Fo/derName. The location of 
the folder to delete is indicated by the ParentFolderPath. 


(Optional). Lists the contents, both folders and packages, in 
a folder on SSIS or SQL Server. The optional Fo/derPath 
parameter specifies the folder that you want to view the 
content of. The optional S parameter specifies that you want 
to view a listing of the contents of the subfolders for the 
folder specified in FolderPath. 


(Optional). Verifies if the specified folder exists on SSIS or 
SQL Server. The Fo/derPath parameter is the path and name 
of the folder to verify. 


This option specifies that the SSIS package to be operated 
on is located in the file system. The fi/espec value can be 
provided as either a Universal Naming Convention (UNC) 
path or local path. 


If the File option is specified on the same command line as 
any of the following options, a DTEXEC_DTEXECERROR is 
returned: 

DTS 

SQL 

SOURCEUSER 


SOURCEPASSWORD 


SOURCESERVER 


(Optional). Renames a folder on the SSIS or SQL Server. The 
ParentFolderPath is the location of the folder to rename. The 
OldFolderName is the current name of the folder, and 
NewFolderName is the new name to give the folder. 


Displays text extensive help that shows the dtutil options 
and describes their use. The option argument is optional. If 
the argument is included, the Help text includes detailed 
information about the specified option. The following 
example displays help for all options: 


dtutil /H 
The following two examples show how to use the /H option 
to display extended help for a specific option, the /Q /u/et] 
option, in this example: 


dtutil /Help Quiet 


dtutil /H Q 


OPTION 


/\[DRegenerate] 


/M{ove] {SQL | File | DTS}; pathandname 


/Ql{uiet] 


/R[emark] text 


DESCRIPTION 


Creates a new GUID for the package and updates the 
package ID property. When a package is copied, the package 
ID remains the same; therefore, the log files contain the 
same GUID for both packages. This action creates a new 
GUID for the newly-copied package to distinguish it from 
the original. 


Specifies a move action on an SSIS package. To use this 
parameter, first specify the location of the package using the 
/FI, /SQ, or /DT option. Next, specify the Move action. This 
action requires two arguments, which are separated by a 
semicolon: 


The destination argument can specify SQL, FILE, or DTS. A 
SQL destination can include the DESTUSER, 
DESTPASSWORD, and DESTSERVER options. 


The pathandname argument specifies the package location: 
SQL uses the package path and package name, F/lF uses a 
UNC or local path, and D7S uses a location that is relative to 
the root of the SSIS Package Store. When the destination is 
FILE or DTS, the path argument does not include the file 
name. Instead, it uses the package name at the specified 
location as the file name. 


When the MOVE action encounters an existing package at 
the destination, dtutil prompts you to confirm that you 
want to overwrite the package. The Y reply overwrites the 
package and the N reply ends the program. When the 
command includes the QU/ET option, no prompt appears 
and any existing package is overwritten. 


Stops the confirmation prompts that can appear when a 
command including the COPY, MOVE, or SIGN option is 
executed. These prompts appear if a package with the same 
name as the specified package already exists at the 
destination computer or if the specified package is already 
signed. 


Adds a comment to the command line. The comment 
argument is optional. If the comment text includes spaces, 
the text must be enclosed in quotation marks. You can 
include multiple REM options in a command line. 


OPTION 


/Si[gn] {SQL | File| DT5}; path; hash 


/SourceP[assword] password 


/SourceS[erver] server_instance 


/SourceU[ser] username 


DESCRIPTION 


Signs an SSIS package. This action uses three required 
arguments, which are separated by semicolons; destination, 
path, and hash: 


The destination argument can specify SQL, FILE, or DTS. A 
SQL destination can include the DESTUSER, DESTPASSWORD 
and DESTSERVER options. 


The path argument specifies the location of the package to 
take action on. 


The hash argument specifies a certificate identifier expressed 
as a hexadecimal string of varying length. 


For more information, see Identify the Source of Packages 
with Digital Signatures. 


** Important ** When configured to check the signature 
of the package, Integration Services only checks whether the 
digital signature is present, is valid, and is from a trusted 
source. Integration Services does not check whether the 
package has been changed. 


Specifies the password that is used with the SQZ and 
SOURCEUSER options to enable the retrieval of an SSIS 
package that is stored in a database on a SQL Server 
instance that uses SQL Server Authentication. It is an error 
to specify SOURCEPASSWORD in a command line that does 
not include the SOURCEUSER option. 


Note: When possible, use Windows authentication. 


Specifies the server name that is used with the SQL option 
to enable the retrieval of an SSIS package that is stored in 
SQL Server. It is an error to specify SOURCESERVER in a 
command line that does not include the S/GN SQL, COPY 
SQL, or MOVE SQL option. 


A SQL Server instance name can be specified by adding a 
backslash and the instance name to the server name. 


Specifies the user name that is used with the 
SOURCESERVER option to enable the retrieval of an SSIS 
package stored in SQL Server using SQL Server 
Authentication. It is an error to specify SOURCEUSER in a 
command line that does not include the S/GN SQL, COPY 
SQL, or MOVE SQL option. 


Note: When possible, use Windows authentication. 


OPTION 


/SQ{L] package_path 


dtutil Exit Codes 


DESCRIPTION 


Specifies the location of an SSIS package. This option 
indicates that the package is stored in the msdb database. 
The package_path argument specifies the path and name of 
the SSIS package. Folder names are terminated with back 
slashes. 


If the SQL option is specified on the same command line as 
any of the following options, a DTEXEC_DTEXECERROR is 
returned: 

DTS 


FILE 


The SQL option may be accompanied by zero or one 
instance of the following options: 


SOURCEUSER 
SOURCEPASSWORD 


SOURCESERVER 


If SOURCEUSERNAME is not included, Windows 
Authentication is used to access the package. 
SOURCEPASSWORD is allowed only if SOURCEUSER is 
present. If SOURCEPASSWORD is not included, a blank 
password is used. 


** Important ** Do not use a blank password. Use a 
strong password. 


dtutil sets an exit code that alerts you when syntax errors are detected, incorrect arguments are used, or invalid 


combinations of options are specified. Otherwise, the utility reports "The operation completed successfully". The 


following table lists the values that the dtutil utility can set when exiting. 


VALUE 


Remarks 


You cannot use command files or redirection with dtutil. 


DESCRIPTION 


The utility executed successfully. 


The utility failed. 


The utility cannot locate the requested package. 


The utility cannot load the requested package 


The utility cannot resolve the command line because it 
contains either syntactic or semantic errors. 


The order of the options within the command line is not significant. 


Examples 


The following examples detail typical command line usage scenarios. 


Copy Examples 
To copy a package that is stored in the msdb database on a local instance of SQL Server using Windows 


Authentication to the SSIS Package Store, use the following syntax: 


dtutil /SQL srcPackage /COPY DTS;destFolder\destPackage 


To copy a package from a location on the File system to another location and give the copy a different name, use 
the following syntax: 


dtutil /FILE c:\myPackages\mypackage.dtsx /COPY FILE;c:\myTestPackages\mynewpackage.dtsx 


To copy a package on the local file system to an instance of SQL Server hosted on another computer, use the 


following syntax: 


dtutil /FILE c:\sourcepkg.dtsx /DestServer <servername> /COPY SQL;destpkgname 


Because the /DestU/ser] and /DestP/assword] options were not used, Windows Authentication is assumed. 


To create a new ID for a package after it is copied, use the following syntax: 
dtutil /I /FILE copiedpkg.dtsx 

To create a new ID for all the packages in a specific folder, use the following syntax: 
for “*Ff in (C:\test\SSISPackages\*.dtsx) do dtutil.exe /I /FILE %%F 


Use a single percent sign (%) when typing the command at the command prompt. Use a double percent sign 
(%%) if the command is used inside a batch file. 


Delete Examples 
To delete a package that is stored in the msdb database on an instance of SQL Server that uses Windows 
Authentication, use the following syntax: 


dtutil /SQL delPackage /DELETE 


To delete a package that is stored in the msdb database on an instance of SQL Server that uses SQL Server 
Authentication, use the following syntax: 


dtutil /SQL delPackage /SOURCEUSER srcUserName /SOURCEPASSWORD #8nGs*w7F /DELETE 





NOTE 


To delete a package from a named server, include the SOURCESERVER option and its argument. You can only specify a 
server by using the SQL option. 











To delete a package that is stored in the SSIS Package Store, use the following syntax: 


dtutil /DTS delPackage.dtsx /DELETE 


To delete a package that is stored in the file system, use the following syntax: 


dtutil /FILE c:\delPackage.dtsx /DELETE 


Exists Examples 
To determine whether a package exists in the msdb database on a local instance of SQL Server that uses 
Windows Authentication, use the following syntax: 


dtutil /SQL srcPackage /EXISTS 


To determine whether a package exists in the msdb database on a local instance of SQL Server that uses SQL 
Server Authentication, use the following syntax: 


dtutil /SQL srcPackage /SOURCEUSER srcUserName /SOURCEPASSWORD *hY$d56b /EXISTS 


NOTE 


To determine whether a package exists on a named server, include the SOURCESERVER option and its argument. You 


can only specify a server by using the SQL option. 





To determine whether a package exists in the local package store, use the following syntax: 


dtutil /DTS srcPackage.dtsx /EXISTS 


To determine whether a package exists in the local file system, use the following syntax: 


dtutil /FILE c:\srcPackage.dtsx /EXISTS 


Move Examples 


To move a package that is stored in the SSIS Package Store to the msdb database on a local instance of SQL 
Server that uses Windows Authentication, use the following syntax: 


dtutil /DTS srcPackage.dtsx /MOVE SQL;destPackage 


To move a package that is stored in the msdb database on a local instance of SQL Server that uses SQL Server 
Authentication to the msdb database on another local instance of SQL Server that uses SQL Server 
Authentication, use the following syntax: 


dtutil /SQL srcPackage /SOURCEUSER srcUserName /SOURCEPASSWORD $Hj45jhd@xX /MOVE SQL;destPackage /DESTUSER 
destUserName /DESTPASSWORD !38dsFH@v 





NOTE 


To move a package from one named server to another, include the SOURCES and the DESTS option and their 
arguments. You can only specify servers by using the SQL option. 











To move a package that is stored in the SSIS Package Store, use the following syntax: 


dtutil /DTS srcPackage.dtsx /MOVE DTS;destPackage.dtsx 


To move a package that is stored in the file system, use the following syntax: 


dtutil /FILE c:\srcPackage.dtsx /MOVE FILE;c:\destPackage.dtsx 


Sign Examples 


To sign a package that is stored in a SQL Server database on a local instance of SQL Server that uses Windows 
Authentication, use the following syntax: 


dtutil /FILE srcPackage.dtsx /SIGN FILE;destpkg.dtsx;1767832648918a9d989fdac9819873a91f919 


To locate information about your certificate, use CertMgr. The hash code can be viewed in the CertMgr utility 
by selecting the certificate, and then clicking View to view the properties. The Details tab provides more 


information about the certificate. The Thumbprint property is used as the hash value, with spaces removed. 





NOTE 


The hash used in this example is not a real hash. 





For more information, see the CertMgr section in Signing and Checking Code with Authenticode. 


Encrypt Examples 


The following sample encrypts the file-based PackageToEncrypt.dtsx to the file-based EncryptedPackage.dts 
using full package encryption, with a password. The password that is used for the encryption is EncPswd. 


dtutil /FILE PackageToEncrypt.dtsx /ENCRYPT file;EncryptedPackage.dtsx;3;EncPswd 


See Also 


Run Integration Services (SSIS) Packages 


SSIS Package Upgrade Wizard F1 Help 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Use the SSIS Package Upgrade Wizard to upgrade packages created by earlier versions of SQL Server to the 
package format for the current release of SQL Server Integration Services. 


To run the SSIS Package Upgrade Wizard 


e Upgrade Integration Services Packages Using the SSIS Package Upgrade Wizard 


SSIS Upgrade Wizard 


Options 
Do not show this page again. 
Skip the Welcome page the next time that you open the wizard. 


Select Source Location page 


Use the Select Source Location page to specify the source from which to upgrade packages. 





NOTE 


This page is only available when you run the SSIS Package Upgrade Wizard from SQL Server Management Studio or at the 
command prompt. 











Static Options 


Package source 
Select the storage location that contains the packages to be upgraded. This option has the values listed in the 
following table. 


VALUE DESCRIPTION 


File System Indicates that the packages to be upgraded are in a folder 
on the local computer. 


To have the wizard back up the original packages before 
upgrading those packages, the original packages must be 
stored in the file system. For more information, see How To 
Topic. 


SSIS Package Store Indicates that the packages to be upgraded are in the 
package store. The package store consists of the set of file 
system folders that the Integration Services service 
manages. For more information, see Package Management 
(SSIS Service). 


Selecting this value displays the corresponding Package 
source dynamic options. 


VALUE DESCRIPTION 


Microsoft SQL Server Indicates the packages to be upgraded are from an existing 
instance of SQL Server. 


Selecting this value displays the corresponding Package 
source dynamic options. 


Folder 
Type the name of a folder that contains the packages you want to upgrade or click Browse and locate the folder. 


Browse 


Browse to locate the folder that contains the packages you want to upgrade. 


Package Source Dynamic Options 

Package source = SSIS Package Store 

Server 

Type the name of the server that has the packages to be upgraded, or select this server in the list. 


Package source = Microsoft SQL Server 
Server 
Type the name of the server that has the packages to be upgraded, or select this server from the list. 


Use Windows authentication 
Select to use Windows Authentication to connect to the server. 


Use SQL Server authentication 
Select to use SQL Server Authentication to connect to the server. If you use SQL Server Authentication, you must 
provide a user name and password. 


User name 


Type the user name that SQL Server Authentication will use to connect to the server. 


Password 
Type the password that SQL Server Authentication will use to connect to the server. 


Select Destination Location page 


Use the Select Destination Location page to specify the destination to which to save the upgraded packages. 





NOTE 
This page is only available when you run the SSIS Package Upgrade Wizard from SQL Server Management Studio or at the 


command prompt. 











Static Options 


Save to source location 
Save the upgraded packages to the same location as specified on the Select Source Location page of the 
wizard. 


If the original packages are stored in the file system and you want the wizard to back up those packages, select 
the Save to source location option. For more information, see Upgrade Integration Services Packages Using 
the SSIS Package Upgrade Wizard. 


Select new destination location 
Save the upgraded packages to the destination location that is specified on this page. 


Package source 
Specify where the upgrade packages are to be stored. This option has the values listed in the following table. 


VALUE DESCRIPTION 


File System Indicates that the upgraded packages are to be saved to a 
folder on the local computer. 


SSIS Package Store Indicates that the upgraded packages are to be saved to the 
Integration Services package store. The package store 
consists of the set of file system folders that the Integration 
Services service manages. For more information, see Package 
Management (SSIS Service). 


Selecting this value displays the corresponding Package 
source dynamics options. 


Microsoft SQL Server Indicates that the upgraded packages are to be saved to an 
existing instance of SQL Server. 


Selecting this value displays the corresponding dynamic 
Package source dynamic options. 


Folder 
Type the name of a folder to which the upgraded packages will be saved, or click Browse and locate the folder. 


Browse 
Browse to locate the folder to which the upgraded packages will be saved. 


Package Source Dynamic Options 
Package source = SSIS Package Store 


Server 
Type the name of the server to which the upgrade packages will be saved, or select a server in the list. 


Package source = Microsoft SQL Server 


Server 
Type the name of the server to which the upgrade packages will be saved, or select this server in the list. 


Use Windows authentication 
Select to use Windows Authentication to connect to the server. 


Use SQL Server authentication 
Select to use SQL Server Authentication to connect to the server. If you use SQL Server Authentication, you must 


provide a user name and password. 


User name 
Type the user name to be used when using SQL Server Authentication to connect to the server. 


Password 
Type the password to be used when using SQL Server Authentication to connect to the server. 


Select Package Management Options page 
Use the Select Package Management Options page to specify options for upgrading packages. 
To run the SSIS Package Upgrade Wizard 


e Upgrade Integration Services Packages Using the SSIS Package Upgrade Wizard 


Options 
Update connection strings to use new provider names 
Update the connection strings to use the names for the following providers for the current release of Integration 


Services: 
e@ OLE DB Provider for Analysis Services 
e SQL Server Native Client 


The SSIS Package Upgrade Wizard updates only connection strings that are stored in connection managers. The 
wizard does not update connection strings that are constructed dynamically by using the Integration Services 
expression language, or by using code in a Script task. 


Validate upgrade packages 
Validate the upgrade packages and save only those upgrade packages that pass validation. 


If you do not select this option, the wizard will not validate upgrade packages. Therefore, the wizard will save all 
upgrade packages, regardless of whether the packages are valid or not. The wizard saves upgrade packages to 
the destination that is specified on the SelectDestination Location page of the wizard. 


Validation adds time to the upgrade process. We recommend that you do not select this option for large 
packages that are likely to be upgraded successfully. 


Create new package IDs 
Create new package IDs for the upgrade packages. 


Continue upgrade process when a package upgrade fails 
Specify that when a package cannot be upgraded, the SSIS Package Upgrade Wizard continues to upgrade the 


remaining packages. 


Package name conflicts 
Specify how the wizard should handle packages that have the same name. This option has the values listed in 
the following table. 


Overwrite existing package files 
Replaces the existing package with the upgrade package of the same name. 


Add numeric suffixes to upgrade package names 
Adds a numeric suffix to the name of the upgrade package. 


Do not upgrade packages 
Stops the packages from being upgraded and displays an error when you complete the wizard. 


These options are not available when you select the Save to source location option on the Select 
Destination Location page of the wizard. 


Ignore Configurations 
Does not load package configurations during the package upgrade. Selecting this option reduces the time 
required to upgrade the package. 


Backup original packages 

Have the wizard back up the original packages to an SSISBackupFolder folder. The wizard creates the 
SSISBackupFolder folder as a subfolder to the folder that contains the original packages and the upgraded 
packages. 





NOTE 


This option is available only when you specify that the original packages and the upgraded packages are stored in the file 


system and in the same folder. 











Select Packages page 


Use the Select Packages page to select the packages to upgrade. This page lists the packages that are stored in 
the location that was specified on the Select Source Location page of the wizard. 


Options 
Existing package name 
Select one or more packages to upgrade. 


Upgrade package name 
Provide the destination package name, or use the default name that the wizard provides. 





NOTE 
You can also change the destination package name after upgrading the package. In SQL Server Data Tools (SSDT) or SQL 


Server Management Studio, open the upgraded package and change the package name. 











Password 
Specify the password that is used to decrypt the selected upgrade packages. 


Apply to selection 
Apply the specified password to decrypt the selected upgrade packages. 


Complete the Wizard page 


Use the Complete the Wizard page to review and confirm the package upgrade options that you have 
selected. This is the last wizard page from which you can go back and change options for this session of the 


wizard. 


Options 


Summary of options 
Review the upgrade options that you have selected in the wizard. To change any options, click Back to return to 
previous wizard pages. 


Upgrading the Packages page 


Use the Upgrading the Packages page to view the progress of package upgrade and to interrupt the upgrade 
process. The SSIS Package Upgrade Wizard upgrades the selected packages one by one. 


Options 
Message pane 
Displays progress messages and summary information during the upgrade process. 


Action 
View the actions in the upgrade. 


Status 
View the result of each action. 


Message 


View the error messages that each action generates. 


Stop 
Stop the package upgrade. 


Report 
Select what you want to do with the report that contains the results of the package upgrade: 


e View the report online. 
e Save the report to a file. 
e Copy the report to the Clipboard 


e Send the report as an e-mail message. 


View upgraded packages 


View upgraded packages that were saved to a SQL Server database or to the package store 


In Management Studio, in Object Explorer, connect to the local instance of Integration Services, and then expand 
the Stored Packages node to see the packages that were upgraded. 


View upgraded packages that were upgraded from SQL Server Data Tools 


In SQL Server Data Tools (SSDT), in Solution Explorer, open the Integration Services project, and then expand the 
SSIS Packages node to see the upgraded packages. 


See Also 


Upgrade Integration Services Packages 


Integration Services (SSIS) Package and Project 


Parameters 
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Applies to: Q sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Integration Services (SSIS) parameters allow you to assign values to properties within packages at the time of 
package execution. You can create project parameters at the project level and package parameters at the 
package level. Project parameters are used to supply any external input the project receives to one or more 
packages in the project. Package parameters allow you to modify package execution without having to edit and 
redeploy the package. 


In SQL Server Data Tools you create, modify, or delete project parameters by using the Project.params 
window. You create, modify, and delete package parameters by using the Parameters tab in the SSIS Designer. 
You associate a new or an existing parameter with a task property by using the Parameterize dialog box. For 
more about using the Project.params window and the Parameters tab, see Create Parameters. For more 
information about the Parameterize dialog box, see Parameterize Dialog Box. 


Parameters and Package Deployment Model 


In general, if you are deploying a package using the package deployment model, you should use configurations 
instead of parameters. 


When you deploy a package that contains parameters using the package deployment model and then execute 
the package, the parameters are not called during execution. If the package contains package parameters and 

expressions within the package use the parameters, the resulting values are applied at runtime. If the package 
contains project parameters, the package execution may fail. 


Parameters and Project Deployment Model 


When you deploy a project to the Integration Services (SSIS) server, you use views, stored procedures, and the 
SQL Server Management Studio UI to manage project and package parameters. For more information, see the 
following topics. 


e Views (Integration Services Catalog) 

e Stored Procedures (Integration Services Catalog) 
e Configure Dialog Box 

e Execute Package Dialog Box 


Parameter Values 


You can assign up to three different types of values to a parameter. When a package execution is started, a single 
value is used for the parameter, and the parameter is resolved to its final literal value. 


The following table lists the types of values. 


VALUE NAME DESCRIPTION TYPE OF VALUE 


VALUE NAME DESCRIPTION TYPE OF VALUE 


Execution Value The value that is assigned to a specific Literal 
instance of package execution. This 
assignment overrides all other values, 
but applies to only a single instance of 
package execution. 


Server Value The value assigned to the parameter Literal or Environment Variable 
within the scope of the project, after Reference 
the project is deployed to the 
Integration Services server. This value 
overrides the design default. 


Design Value The value assigned to the parameter Literal 
when the project is created or edited in 
SQL Server Data Tools. This value 
persists with the project. 


You can use a single parameter to assign a value to multiple package properties. A single package property can 
be assigned a value only from a single parameter. 


Executions and Parameter Values 


The execution is an object that represents a single instance of package execution. When you create an execution, 
you specify all of the details necessary to run a package such as execution parameter values. You can also 
modify the parameters values for existing executions. 


When you explicitly set an execution parameter value, the value is applicable only to that particular instance of 
execution. The execution value is used instead of a server value or a design value. If you do not explicitly set an 
execution value, and a server value has been specified, the server value is used. 


When a parameter is marked as required, a server value or execution value must be specified for that parameter. 
Otherwise, the corresponding package does not execute. Although the parameter has a default value at design 
time, it will never be used once the project is deployed. 


Environment Variables 

If a parameter references an environment variable, the literal value from that variable is resolved through the 
specified environment reference and applied to the parameter. The final literal parameter value that is used for 
package execution is referred to as the execution parameter value. You specify the environment reference for an 
execution by using the Execute dialog box 


If a project parameter references an environment variable and the literal value from the variable cannot be 


resolved at execution, the design value is used. The server value is not used. 


To view the environment variables that are assigned to parameter values, query the catalog.object_parameters 
view. For more information, see catalog.object_parameters (SSISDB Database). 


Determining Execution Parameter Values 


The following Transact-SQL views and stored procedure can be used to display and set parameter values. 


catalog.execution_parameter_values (SSISDB Database)(view) 
Shows the actual parameter values in a specific execution. 


catalog.get_parameter_values (SSISDB Database) (stored procedure) 
Resolves and shows the actual values for the specified package and environment reference. 


catalog.object_parameters (SSISDB Database) (view) 
Displays the parameters and properties for all packages and projects in the Integration Services catalog, 


including the design default and server default values. 


catalog.set_execution_parameter_value (SSISDB Database) 
Sets the value of a parameter for an instance of execution in the Integration Services catalog. 


You can also use the Execute Package dialog box in SQL Server Data Tools (SSDT) modify the parameter value. 
For more information, see Execute Package Dialog Box. 


You can also use the dtexec /Parameter option to modify a parameter value. For more information, see dtexec 
Utility. 


Parameter Validation 


If parameter values cannot be resolved, the corresponding package execution will fail. To help avoid failures, you 
can validate projects and packages by using the Validate dialog box in SQL Server Data Tools (SSDT). Validation 
allows you to confirm that all parameters have the necessary values or can resolve the necessary values with 
specific environment references. Validation also checks for other common package issues. 


For more information, see Validate Dialog Box. 


Parameter Example 


This example describes a parameter named pkgOptions that is used to specify options for the package in 
which it resides. 


During design time, when the parameter was created in SQL Server Data Tools, a default value of 1 was 
assigned to the parameter. This default value is referred to as the design default. If the project was deployed to 
the SSISDB catalog and no other values were assigned to this parameter, the package property corresponding to 
the pkgOptions parameter would be assigned the value of 1 during package execution. The design default 
persists with the project throughout its life cycle. 


While preparing a specific instance of package execution, a value of 5 is assigned to the pkgOptions parameter. 
This value is referred to as the execution value because it applies to the parameter only for that particular 
instance of execution. When execution starts, the package property corresponding to the pkgOptions 
parameter is assigned the value of 5. 


Create parameters 


You use SQL Server Data Tools (SSDT) to create project parameters and package parameters. The following 
procedures provide step-by-step instructions for creating package/project parameters. 


NOTE: If you are converting a project that you created using an earlier version of Integration Services to the 
project deployment model, you can use the Integration Services Project Conversion Wizard to create 
parameters based on configurations. For more information, see Deploy Integration Services (SSIS) Projects 
and Packages. 


Create package parameters 


1. Open the package in SQL Server Data Tools, and then click the Parameters tab in the SSIS Designer. 








| 
Project.params [Design] Start Page Packagel.dtsx [Design]* > [GEIST Reiss (esl | 
Zea Control Flow | (2) Data Fon (@ Paranetes Event Handlers | Tf Package Explorer l 
x @ | 
Name Data type Value | 


2. Click the Add Parameter button on the toolbar. 


@)ena! 
| Add Parameter | 


3. Enter values for the Name, Data Type, Value, Sensitive, and Required properties in the list itself or in 
the Properties window. The following table describes these properties. 


PROPERTY DESCRIPTION 

Name The name of the parameter. 

Data type The data type of the parameter. 

Default value The default value for the parameter assigned at design 


time. This is also known as the design default. 


Sensitive Sensitive parameter values are encrypted in the catalog 
and appear as a NULL value when viewed with Transact- 
SQL or SQL Server Management Studio. 


Required Requires that a value, other than the design default, is 
specified before the package can execute. 


Description For maintainability, the description of the parameter. In 
SQL Server Data Tools (SSDT), set the parameter 
description in the Visual Studio Properties window when 
the parameter is selected in the applicable parameters 
window. 


NOTE: When you deploy a project to the catalog, several more properties become associated with 
the project. To see all properties for all parameters in the catalog, use the catalog.object_parameters 
(SSISDB Database) view. 


4. Save the project to save changes to parameters. Parameter values are stored in the project file. 


WARNING!! You can in-place edit in the list or use the Properties window to modify the values of 
parameter properties. You can delete a parameter by using the Delete (X) toolbar button. Using the 
last toolbar button, you can specify a value for a parameter that is used only when you execute the 
package in SQL Server Data Tools. 


NOTE: If you re-open the package file without opening the project in SQL Server Data Tools, the 
Parameters tab will be empty and disabled. 


Create project parameters 


1. Open the project in SQL Server Data Tools. 


2. Right-click Project.params in Solution Explorer, and then click Open (OR) double-click Project.params 
to open it. 


Name Data type 
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er button on the toolbar. 


4. Enter values for the Name, Data Type, Value, Sensitive, and Required properties. 


PROPERTY 


Name 


Data type 


Default value 


Sensitive 


Required 


Description 


DESCRIPTION 


The name of the parameter. 


The data type of the parameter. 


The default value for the parameter assigned at design 
time. This is also known as the design default. 


Sensitive parameter values are encrypted in the catalog 
and appear as a NULL value when viewed with Transact- 
SQL or SQL Server Management Studio. 


Requires that a value, other than the design default, is 
specified before the package can execute. 


For maintainability, the description of the parameter. In 
SQL Server Data Tools, set the parameter description in 
the Visual Studio Properties window when the parameter 
is selected in the applicable parameters window. 


5. Save the project to save changes to parameters. Parameter values are stored in configurations in the 


project file. Save the project file to commit to disk any changes in the parameter values. 


WARNING!!! You can in-place edit in the list or use the Properties window to modify the values of 


parameter properties 
last toolbar button to 


. You can delete a parameter by using the Delete (X) toolbar button. Using the 
open the Manage Parameter Values dialog box, you can specify a value for a 


parameter that is used only when you execute the package in SQL Server Data Tools. 


Parameterize Dialog Box 


The Parameterize dialog box lets you associate a new or an existing parameter with a property of a task. You 


open the dialog box by right-clicking a task or the Control Flow tab in SSIS Designer and then by clicking 


Parameterize. The followi 


ng list describes Ul elements in the dialog box. For more information about 


parameters, see Integration Services (SSIS) Parameters. 


Options 

Property 

Select the property of the task that you want to associate with a parameter. This list is populated with all the 
properties that can be parameterized. 


Use existing parameter 
Select this option to associate the property of task with an existing parameter and then select the parameter 
from drop-down list. 


Do not use parameter 
Select this option to remove a reference to a parameter. The parameter is not deleted. 


Create new parameter 
Select this option to create a new parameter that you want to associate with the property of the task. 


Name 
Specify the name of the parameter you want to create. 


Description 
Specify the description for parameter. 


Value 
Specify the default value for the parameter. This is also known as the design default, which can be overridden 
later at the deployment time. 


Scope 

Specify the scope of the parameter by selecting either Project or Package option. Project parameters are used 
to supply any external input the project receives to one or more packages in the project. Package parameters 
allow you to modify package execution without having to edit and redeploy the package. 


Sensitive 

Specify whether the parameter is a sensitive by checking or clearing the check box. Sensitive parameter values 
are encrypted in the catalog and appear as a NULL value when viewed with Transact-SQL or SQL Server 
Management Studio. 


Required 
Specify whether the parameter requires that a value, other than the design default, is specified before the 
package can execute. 


Set parameter values after the project is deployed 


The Deployment Wizard allows you to set server default parameter values when you deploy your project to the 
catalog. After your project is in the catalog, you can use SQL Server Management Studio (SSMS) Object Explorer 
or Transact-SQL to set server default values. 


Set server defaults with SSMS Object Explorer 


1. Select and right-click the project under the Integration Services node. 
2. Click Properties to open the Project Properties dialog window. 
3. Open the parameters page by clicking Parameters under Select a page. 


4. Select the desired parameter in the Parameters list. Note: The Container column helps distinguish 
project parameters from package parameters. 


5. In the Value column, specify the desired server default parameter value. 


Set server defaults with Transact-SQL 


To set server defaults with Transact-SQL, use the catalog.set_object_parameter_value (SSISDB Database) stored 
procedure. To view current server defaults, query the catalog.object_parameters (SSISDB Database) view. To 
clear a server default value, use the catalog.clear_object_parameter_value (SSISDB Database) stored procedure. 


Related Content 


Blog entry, SSIS Quick Tip: Required Parameters, on mattmasson.com. 


Integration Services (SSIS) Connections 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Microsoft SQL Server Integration Services packages use connections to perform different tasks and to 
implement Integration Services features: 


e Connecting to source and destination data stores such as text, XML, Excel workbooks, and relational 
databases to extract and load data. 


e Connecting to relational databases that contain reference data to perform exact or fuzzy lookups. 


e® Connecting to relational databases to run SQL statements such as SELECT, DELETE, and INSERT 
commands and also stored procedures. 


e Connecting to SQL Server to perform maintenance and transfer tasks such as backing up databases and 
transferring logins. 


e Writing log entries in text and XML files and SQL Server tables and package configurations to SQL Server 
tables. 


e Connecting to SQL Server to create temporary work tables that some transformations require to do their 
work. 


e Connecting to Analysis Services projects and databases to access data mining models, process cubes and 
dimensions, and run DDL code. 


e Specifying existing or creating new files and folders to use with Foreach Loop enumerators and tasks. 


e Connecting to message queues and to Windows Management Instrumentation (WMI), SQL Server 
Management Objects (SMO), Web, and mail servers. 


To make these connections, Integration Services uses connection managers, as described in the next section. 


Connection Managers 


Integration Services uses the connection manager as a logical representation of a connection. At design time, 
you set the properties of a connection manager to describe the physical connection that Integration Services 
creates when the package runs. For example, a connection manager includes the ConnectionString property 
that you set at design time; at run time, a physical connection is created using the value in the connection string 
property. 


A package can use multiple instances of a connection manager type, and you can set the properties on each 
instance. At run time, each instance of a connection manager type creates a connection that has different 
attributes. 


SQL Server Integration Services provides different types of connection managers that enable packages to 
connect to a variety of data sources and servers: 


e@ There are built-in connection managers that Setup installs when you install Integration Services. 
e There are connection managers that are available for download from the Microsoft website. 


e You can create your own custom connection manager if the existing connection managers do not meet 
your needs. 


Package level and project level connection managers 


A connection manager can be created at the package level or at the project level. The connection manager 


created at the project level is available all the packages in the project. Whereas, connection manager created at 


the package level is available to that specific package. 


You use connection managers that are created at the project level in place of data sources, to share connections 


to sources. To add a connection manager at the project level, the Integration Services project must use the 


project deployment model. When a project is configured to use this model, the Connection Managers folder 


appears in Solution Explorer, and the Data Sources folder is removed from Solution Explorer. 





NOTE 





Deploy Integration Services (SSIS) Projects and Packages. 


If you want to use data sources in your package, you need to convert the project to the package deployment model. 


For more information about the two models, and about converting a project to the project deployment model, see 





Built-in Connection Managers 


The following table lists the connection manager types that SQL Server Integration Services provides. 


TYPE 


ADO 


ADO.NET 


CACHE 


DQS 


EXCEL 


FILE 


FLATFILE 


FTP 


HTTP 


MSMQ 


MSOLAP100 


MULTIFILE 


DESCRIPTION 


Connects to ActiveX Data Objects 
(ADO) objects. 


Connects to a data source by using a 
.NET provider. 


Reads data from the data flow or from 
a cache file (.caw), and can save data to 
the cache file. 


Connects to a Data Quality Services 
server and a Data Quality Services 
database on the server. 


Connects to an Excel workbook file. 


Connects to a file or a folder. 


Connect to data in a single flat file. 


Connect to an FTP server. 


Connects to a webserver. 


Connects to a message queue. 


Connects to an instance of SQL Server 
Analysis Services or an Analysis 
Services project. 


Connects to multiple files and folders. 


TOPIC 


ADO Connection Manager 


ADO.NET Connection Manager 


Cache Connection Manager 


DQS Cleansing Connection Manager 


Excel Connection Manager 


File Connection Manager 


Flat File Connection Manager 


FTP Connection Manager 


HTTP Connection Manager 


MSMQ Connection Manager 


Analysis Services Connection Manager 


Multiple Files Connection Manager 





TYPE 


MULTIFLATFILE 


OLEDB 


ODBC 


SMOServer 


SMTP 


SQLMOBILE 


WMI 


DESCRIPTION 


Connects to multiple data files and 
folders. 


Connects to a data source by using an 
OLE DB provider. 


Connects to a data source by using 
ODBC. 


Connects to a SQL Server 
Management Objects (SMO) server. 


Connects to an SMTP mail server. 


Connects to a SQL Server Compact 
database. 


Connects to a server and specifies the 
scope of Windows Management 
Instrumentation (WMI) management 
on the server. 


Connection Managers available for download 


TOPIC 


Multiple Flat Files Connection Manager 


OLE DB Connection Manager 


ODBC Connection Manager 


SMO Connection Manager 


SMTP Connection Manager 


SQL Server Compact Edition 
Connection Manager 


WMI Connection Manager 


The following table lists additional types of connection manager that you can download from the Microsoft 











website. 

IMPORTANT 

The connection managers listed in the following table work only with SQL Server Enterprise and SQL Server Developer 

edition. 

TYPE DESCRIPTION TOPIC 

ORACLE Connects to an Oracle <version info> The Oracle connection manager is the 

server. connection manager component of the 

Microsoft Connector for Oracle by 
Attunity. The Microsoft Connector for 
Oracle by Attunity also includes a 
source and a destination. For more 
information, see the download page, 
Microsoft Connectors for Oracle and 
Teradata by Attunity. 

SAPBI Connects to an SAP NetWeaver BI 


version 7 system. 


The SAP BI connection manager is the 
connection manager component of the 
Microsoft Connector for SAP BI. The 
Microsoft Connector for SAP BI also 
includes a source and a destination. 
For more information, see the 
download page, Microsoft SQL Server 
2008 Feature Pack. 





TYPE DESCRIPTION TOPIC 


TERADATA Connects to a Teradata <version info> The Teradata connection manager is 

server. the connection manager component of 
the Microsoft Connector for Teradata 
by Attunity. The Microsoft Connector 
for Teradata by Attunity also includes a 
source and a destination. For more 
information, see the download page, 
Microsoft Connectors for Oracle and 
Teradata by Attunity. 


Custom Connection Managers 


You can also write custom connection managers. For more information, see Developing a Custom Connection 


Manager. 


Create connection managers 


Integration Services includes a variety of connection managers to suit the needs of tasks that connect to 
different types of servers and data sources. Connection managers are used by the data flow components that 
extract and load data in different types of data stores, and by the log providers that write logs to a server, SQL 
Server table, or file. For example, a package with a Send Mail task uses an SMTP connection manager type to 
connect to a Simple Mail Transfer Protocol (SMTP) server. A package with an Execute SQL task can use an OLE 
DB connection manager to connect to a SQL Server database. For more information, see Integration Services 
(SSIS) Connections. 


To automatically create and configure connection managers when you create a new package, you can use the 
SQL Server Import and Export Wizard. The wizard also helps you create and configure the sources and 
destinations that use the connection managers. For more information, see Create Packages in SQL Server Data 
Tools. 


To manually create a new connection manager and add it to an existing package, you use the Connection 
Managers area that appears on the Control Flow, Data Flow, and Event Handlers tabs of SSIS Designer. 
From the Connection Manager area, you choose the type of connection manager to create, and then set the 
properties of the connection manager by using a dialog box that SSIS Designer provides. For more information, 
see the section, "Using the Connection Managers Area," later in this topic. 


After the connection manager is added to a package, you can use it in tasks, Foreach Loop containers, sources, 
transformations, and destinations. For more information, see Integration Services Tasks, Foreach Loop 
Container, and Data Flow. 


Using the Connection Managers Area 


You can create connection managers while the Control Flow, Data Flow, or Event Handlers tab of SSIS 


Designer is active. 


The following diagram shows the Connection Managers area on the Control Flow tab of SSIS Designer. 


aan Package. dtsx (Design]* x 


at Genatiee tk [=.. Control Flow |(5 Data Flow | F Event Handlers | “2 Package Explorer 
Uy Geecute SQL Task 

4 Common 
]D Anaiysis Services Process: 
(G9 Bulk trsert Task 
B) Dota Profiling Tack 
Q® Execute OTS 2000 Packa 
a, Execute Package Task 
["] Beecute Process Task 
_}) File System Task 
@) FTP Task 
SD serigt Task 

") Send Mail Task 

@ Wed Service Task 
XML Task 

4 Containers 
U1] For Loop Container 
S] Foreach Loop Container 
iF} Sequence Cortaner 

4 Other Tasks 
SG Activex Script Task 
%) Analysis Services Execute 
ay) Sack Up Database Task 


Lg Check Database Integrity 
4 Data Mining Query Task 


Yt) Rebuild Index Task 

$i, Receganize Index Task 

& Shrink Database Task 
Transfer Database Task 

4 Transfer Error Messages 

GS Treesfer Jobs Task 

8% Treesfer Logins Task 

T) Trawsfer Master Stored Pr 

a> Treesfer SQL Server Obje. 


Right-click here to add a new connection manager to the SSIS package. 





32-Bit and 64-Bit Providers for Connection Managers 


Many of the providers that connection managers use are available in 32-bit and 64-bit versions. The Integration 
Services design environment is a 32-bit environment and you see only 32-bit providers while you are designing 
a package. Therefore, you can only configure a connection manager to use a specific 64-bit provider if the 32-bit 
version of the same provider is also installed. 


At run time, the correct version is used, and it does not matter that you specified the 32-bit version of the 
provider at design time. The 64-bit version of the provider can be run even if the package is run in SQL Server 
Data Tools (SSDT). 


Both versions of the provider have the same ID. To specify whether the Integration Services runtime uses an 
available 64-bit version of the provider, you set the Run64BitRuntime property of the Integration Services 
project. If the Run64BitRuntime property is set to true, the runtime finds and uses the 64-bit provider; if 
Run64BitRuntime is false, the runtime finds and uses the 32-bit provider. For more information about 
properties you can set on Integration Services projects, see Integration Services &(SSIS) and Studio 
Environments. 


Add a connection manager 


Add a connection manager when you create a package 


e Use the SQL Server Import and Export Wizard 


In addition to creating and configuring a connection manager, the wizard also helps you create and 
configure the sources and destinations that use the connection manager. For more information, see 
Create Packages in SQL Server Data Tools. 


Add a connection manager to an existing package 


1. In SQL Server Data Tools (SSDT), open the Integration Services project that contains the package you 
want. 


2. In Solution Explorer, double-click the package to open it 


3. In SSIS Designer, click the Control Flow tab, the Data Flow tab, or the Event Handler tab to make the 
Connection Managers area available. 


4. Right-click anywhere in the Connection Managers area, and then do one of the following: 
@ Click the connection manager type to add to the package. 
-Or- 


e If the type that you want to add is not listed, click New Connection to open the Add SSIS 
Connection Manager dialog box, select a connection manager type, and then click OK. 


The custom dialog box for the selected connection manager type opens. For more information about 
connection manager types and the options that are available, see the following options table. 


CONNECTION MANAGER OPTIONS 

ADO Connection Manager Configure OLE DB Connection Manager 

ADO.NET Connection Manager Configure ADO.NET Connection Manager 

Analysis Services Connection Manager Add Analysis Services Connection Manager Dialog Box 
UI Reference 

Excel Connection Manager Excel Connection Manager Editor 

File Connection Manager File Connection Manager Editor 

Multiple Files Connection Manager Add File Connection Manager Dialog Box UI Reference 

Flat File Connection Manager Flat File Connection Manager Editor (General Page) 


Flat File Connection Manager Editor (Columns Page) 
Flat File Connection Manager Editor (Advanced Page) 


Flat File Connection Manager Editor (Preview Page) 


Multiple Flat Files Connection Manager Multiple Flat Files Connection Manager Editor (General 
Page) 


Multiple Flat Files Connection Manager Editor (Columns 
Page) 


Multiple Flat Files Connection Manager Editor (Advanced 
Page) 


Multiple Flat Files Connection Manager Editor (Preview 
Page) 


FTP Connection Manager FTP Connection Manager Editor 


CONNECTION MANAGER 


HTTP Connection Manager 


MSMQ Connection Manager 


ODBC Connection Manager 


OLE DB Connection Manager 


SMO Connection Manager 


SMTP Connection Manager 


SQL Server Compact Edition Connection Manager 


WMI Connection Manager 


OPTIONS 


HTTP Connection Manager Editor (Server Page) 


HTTP Connection Manager Editor (Proxy Page) 


MSMQ Connection Manager Editor 


ODBC Connection Manager UI Reference 


Configure OLE DB Connection Manager 


SMO Connection Manager Editor 


SMTP Connection Manager Editor 


SQL Server Compact Edition Connection Manager Editor 
(Connection Page) 


SQL Server Compact Edition Connection Manager Editor 
(All Page) 


WMI Connection Manager Editor 


The Connection Managers area lists the added connection manager. 


5. Optionally, right-click the connection manager, click Rename, and then modify the default name of the 


connection manager. 


6. To save the updated package, click Save Selected Item on the File menu. 


Add aconnection manager at the project level 


1. In SQL Server Data Tools (SSDT), open the Integration Services project. 


2. In Solution Explorer, right-click Connection Managers, and click New Connection Manager. 


3. In the Add SSIS Connection Manager dialog box, select the type of connection manager, and then click 


Add. 


The custom dialog box for the selected connection manager type opens. For more information about 


connection manager types and the options that are available, see the following options table. 


CONNECTION MANAGER 


ADO Connection Manager 


ADO.NET Connection Manager 


Analysis Services Connection Manager 


Excel Connection Manager 


File Connection Manager 


Multiple Files Connection Manager 


OPTIONS 


Configure OLE DB Connection Manager 


Configure ADO.NET Connection Manager 


Add Analysis Services Connection Manager Dialog Box 
UI Reference 


Excel Connection Manager Editor 


File Connection Manager Editor 


Add File Connection Manager Dialog Box UI Reference 


CONNECTION MANAGER 


Flat File Connection Manager 


Multiple Flat Files Connection Manager 


FTP Connection Manager 


HTTP Connection Manager 


MSMQ Connection Manager 


ODBC Connection Manager 


OLE DB Connection Manager 


SMO Connection Manager 


SMTP Connection Manager 


SQL Server Compact Edition Connection Manager 


WMI Connection Manager 


OPTIONS 


Flat File Connection Manager Editor (General Page) 
Flat File Connection Manager Editor (Columns Page) 
Flat File Connection Manager Editor (Advanced Page) 


Flat File Connection Manager Editor (Preview Page) 


Multiple Flat Files Connection Manager Editor (General 
Page) 


Multiple Flat Files Connection Manager Editor (Columns 
Page) 


Multiple Flat Files Connection Manager Editor (Advanced 
Page) 


Multiple Flat Files Connection Manager Editor (Preview 
Page) 


FTP Connection Manager Editor 


HTTP Connection Manager Editor (Server Page) 


HTTP Connection Manager Editor (Proxy Page) 


MSMQ Connection Manager Editor 


ODBC Connection Manager UI Reference 


Configure OLE DB Connection Manager 


SMO Connection Manager Editor 


SMTP Connection Manager Editor 


SQL Server Compact Edition Connection Manager Editor 
(Connection Page) 


SQL Server Compact Edition Connection Manager Editor 
(All Page) 


WMI Connection Manager Editor 


The connection manager you added will show up under the Connections Managers node in the 


Solution Explorer. It will also appear in the Connection Managers tab in the SSIS Designer window 


for all the packages in the project. The name of the connection manager in this tab will have a (project) 


prefix in order to differentiate this project level connection manager from the package level connection 


managers. 


. Optionally, right-click the connection manager in the Solution Explorer window under Connection 


Managers node (or) in the Connection Managers tab of the SSIS Designer window, click Rename, 


and then modify the default name of the connection manager. 





NOTE 


In the Connection Managers tab of the SSIS Designer window, you won't be able to overwrite the (project) 
prefix from the connection manager name. This is by design. 








Add SSIS Connection Manager dialog box 


Use the Add SSIS Connection Manager dialog box to select the type of connection to add to a package. 


To learn more about connection managers, see Integration Services (SSIS) Connections. 


Options 

Connection manager type 

Select a connection type and then click Add, or double-click a connection type, to specify connection properties 
using the editor for each type of connection. 


Add 
Specify connection properties using the editor for each type of connection. 


Create a parameter for a connection manager property 


1. In the Connection Managers area, right-click the connection manager that you want to create a 
parameter for and then click Parameterize. 


2. Configure the parameter settings in the Parameterize dialog box. For more information, see 
Parameterize Dialog Box. 





NOTE 


Property ConnectionString is not sensitive and designed not to contain sensitive password information. it is 
recommended to use property Password to parameterize sensitive password. 











Delete a connection manager 


Delete a connection manager from a package 


1. In SQL Server Data Tools (SSDT), open the Integration Services project that contains the package you 
want. 


2. In Solution Explorer, double-click the package to open it. 


3. In SSIS Designer, click the Control Flow tab, the Data Flow tab, or the Event Handler tab to make the 
Connection Managers area available. 


4. Right-click the connection manager that you want to delete, and then click Delete. 


If you delete a connection manager that a package element, such as an Execute SQL task or an OLE DB 
source, uses, you will experience the following results: 


e An error icon appears on the package element that used the deleted connection manager. 
e The package fails to validate. 
e@ The package cannot be run. 

5. To save the updated package, click Save Selected Items on the File menu. 


Delete a shared connection manager (project level connection manager) 


1. To delete a project-level connection manager, right-click the connection manager under Connection 


Managers node in the Solution Explorer window, and then click Delete. SQL Server Data Tools 
displays the following warning message: 


WARNING 


When you delete a project connection manager, packages that use the connection manager might not run. You 


cannot undo this action. Do you want to delete the connection manager? 





2. Click OK to delete the connection manager or Cancel to keep it. 





NOTE 

You can also delete a project level connection manager from the Connection Manager tab of the SSIS 
Designer window opened for any package in the project. You do so by right-clicking the connection manager in 
the tab and then by clicking Delete. 








Set the Properties of a Connection Manager 


All connection managers can be configured using the Properties window. 


Integration Services also provides custom dialog boxes for modifying the different types of connection 
managers in Integration Services. The dialog box has a different set of options depending on the connection 


manager type. 


Modify a connection manager using the Properties window 


1. In SQL Server Data Tools (SSDT), open the Integration Services project that contains the package you 
want. 


2. In Solution Explorer, double-click the package to open it. 


3. In SSIS Designer, click the Control Flow tab, the Data Flow tab, or the Event Handler tab to make the 
Connection Managers area available. 


4. Right-click the connection manager and click Properties. 


5. In the Properties window, edit the property values. The Properties window provides access to some 
properties that are not configurable in the standard editor for a connection manager. 


6. Click OK. 
7. To save the updated package, click Save Selected Items on the File menu. 


Modify a connection manager using a connection manager dialog box 
1. In SQL Server Data Tools (SSDT), open the Integration Services project that contains the package you 
want. 


2. In Solution Explorer, double-click the package to open it. 


3. In SSIS Designer, click the Control Flow tab, the Data Flow tab, or the Event Handler tab to make the 
Connection Managers area available. 


4. In the Connection Managers area, double-click the connection manager to open the Connection 
Manager dialog box. For information about specific connection manager types, and the options available 
for each type, see the following table. 


CONNECTION MANAGER 


ADO Connection Manager 


ADO.NET Connection Manager 


Analysis Services Connection Manager 


Excel Connection Manager 


File Connection Manager 


Multiple Files Connection Manager 


Flat File Connection Manager 


Multiple Flat Files Connection Manager 


FTP Connection Manager 


HTTP Connection Manager 


MSMQ Connection Manager 


ODBC Connection Manager 


OLE DB Connection Manager 


SMO Connection Manager 


SMTP Connection Manager 


SQL Server Compact Edition Connection Manager 


OPTIONS 


Configure OLE DB Connection Manager 


Configure ADO.NET Connection Manager 


Add Analysis Services Connection Manager Dialog Box 
UI Reference 


Excel Connection Manager Editor 


File Connection Manager Editor 


Add File Connection Manager Dialog Box UI Reference 


Flat File Connection Manager Editor (General Page) 
Flat File Connection Manager Editor (Columns Page) 
Flat File Connection Manager Editor (Advanced Page) 


Flat File Connection Manager Editor (Preview Page) 


Multiple Flat Files Connection Manager Editor (General 
Page) 


Multiple Flat Files Connection Manager Editor (Columns 
Page) 


Multiple Flat Files Connection Manager Editor (Advanced 
Page) 


Multiple Flat Files Connection Manager Editor (Preview 
Page) 


FTP Connection Manager Editor 


HTTP Connection Manager Editor (Server Page) 


HTTP Connection Manager Editor (Proxy Page) 


MSMQ Connection Manager Editor 


ODBC Connection Manager UI Reference 


Configure OLE DB Connection Manager 


SMO Connection Manager Editor 


SMTP Connection Manager Editor 


SQL Server Compact Edition Connection Manager Editor 
(Connection Page) 


SQL Server Compact Edition Connection Manager Editor 
(All Page) 


CONNECTION MANAGER OPTIONS 
WMI Connection Manager WMI Connection Manager Editor 


5. To save the updated package, click Save Selected Items on the File menu. 


Related Content 


e Video, Leverage Microsoft Attunity Connector for Oracle to enhance Package Performance, on 
technet.microsoft.com 


e Wiki articles, SSIS Connectivity, on social.technet.microsoft.com 
e Blog entry, Connecting to MySQL from SSIS, on blogs.msdn.com. 


e Technical article, Extracting and Loading SharePoint Data in SQL Server Integration Services, on 
msdn.microsoft.com. 


@ Technical article, You get "DTS_E_ CANNOTACQUIRECONNECTIONFROMCONNECTIONMANAGER" error 
message when using Oracle connection manager in SSIS, on support.microsoft.com. 


Data Sources for Integration Services packages 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


SQL Server Data Tools (SSDT) includes a design-time object that you can use in Microsoft Integration Services 
packages: the data source. 


A data source object is a reference to a connection, and at a minimum, it includes a connection string and a data 
source identifier. It can also include additional metadata such a description, a name, a user name, and a 
password. 


NOTE: You can add data sources only to projects that are configured to use the package deployment model. 
If a project is configured to use the project deployment model, you use connection managers created at the 
project level to share connections, in place of using data sources. 


For more information about the deployment models, see Deployment of Projects and Packages. For more 
information about converting a project to the project deployment model, see Deploy Projects to Integration 
Services Server. 


The advantages of using data sources in Integration Services packages include the following: 


e A data source has project scope, which means that a data source created in an Integration Services 
project is available to all the packages in the project. A data source can be defined one time and then 
referenced by connection managers in multiple packages. 


e A data source offers synchronization between the data source object and its package references. If the 
data source and the packages that reference it reside in the same project, the connection string property 
of the data source references is automatically updated when the data source changes. 


Reference Data Sources 


To add a data source object to an Integration Services project, right-click the Data Sources folder in Solution 
Explorer and then click New Data Source. The item is added to the Data Sources folder. If you want to use 
data source objects that were created in other projects, you must first add them to the project. 


You use a data source object in a package by adding a connection manager that references the data source 
object to the package. You can add it to the package before you build the package control flow and data flows, or 
as a step in constructing the control flow or data flow. 


A data source object represents a simple connection to a data source and provides access to the objects in the 
data store that it references. For example, a data source object that connects to the SQL ServerAdventureWorks 
Sample Database includes all 60 tables from the database. 


There is no dependency between a data source and the connection managers that reference it. If a data source is 
no longer part of the project, the packages continue to be valid, because information about the data source, such 
as its connection type and connection string, is included in the package definition. 
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An ADO connection manager enables a package to connect to ActiveX Data Objects (ADO) objects, such as a 
recordset. This connection manager is typically used in custom tasks written in an earlier version of a language, 
such as Microsoft Visual Basic 6.0, or in custom tasks that are part of an existing application that uses ADO to 
connect to a data source. 


When you add an ADO connection manager to a package, Microsoft SQL Server Integration Services creates a 
connection manager that will resolve to an ADO connection at run time, sets the connection manager 
properties, and adds the connection manager to the Connections collection on the package. The 
ConnectionManagerType property of the connection manager is set to ADO. 


Troubleshooting the ADO Connection Manager 


When being read by an ADO connection manager, certain SQL Server date data types will generate the results 
shown in the following table. 


SQL SERVER DATA TYPE RESULT 


time, datetimeoffset The package fails unless the package uses parameterized 
SQL commands. To use parameterized SQL commands, use 
the Execute SQL Task in your package. For more information, 
see Execute SQL Task and Parameters and Return Codes in 
the Execute SQL Task. 


datetime2 The ADO connection manager truncates the millisecond 
value. 


NOTE 


For more information about SQL Server data types and how they map to Integration Services data types, see Data Types 
(Transact-SQL) and Integration Services Data Types. 





Configuring the ADO Connection Manager 

You can configure an ADO connection manager in the following ways: 

e Provide a specific connection string configured to meet the requirements of the selected provider. 

e Depending on the provider, include the name of the data source to connect to. 

e Provide security credentials as appropriate for the selected provider. 

e Indicate whether the connection that is created from the connection manager is retained at run time. 
You can set properties through SSIS Designer or programmatically. 

For more information about the properties that you can set in SSIS Designer, click the following topic: 


e Configure OLE DB Connection Manager 


For information about configuring a connection manager programmatically, see ConnectionManager and 
Adding Connections Programmatically. 


See Also 


Integration Services (SSIS) Connections 
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An ADO.NET connection manager enables a package to access data sources by using a .NET provider. Typically, 
you use this connection manager to access data sources such as Microsoft SQL Server. You can also access data 
sources exposed through OLE DB and XML in custom tasks that are written in managed code, by using a 
language such as C#. 


When you add an ADO.NET connection manager to a package, SQL Server Integration Services creates a 
connection manager that is resolved as an ADO.NET connection at runtime. It sets the connection manager 
properties, and adds the connection manager to the Connections collection on the package. 


The ConnectionManagerType property of the connection manager is set to aDo.NET . The value of 
ConnectionManagerType is qualified to include the name of the .NET provider that the connection manager uses. 


ADO.NET connection manager troubleshooting 


You can log the calls that the ADO.NET connection manager makes to external data providers. You can then 
troubleshoot the connections that the ADO.NET connection manager makes to external data sources. To log the 
calls that the ADO.NET connection manager makes to external data providers, enable package logging, and 
select the Diagnostic event at the package level. For more information, see Troubleshooting Tools for Package 
Execution. 


When being read by an ADO.NET connection manager, data of certain SQL Server date data types generates the 
results shown in the following table. 


SQL SERVER DATA TYPE RESULT 


time, datetimeoffset The package fails unless the package uses parameterized 
SQL commands. To use parameterized SQL commands, use 
the Execute SQL Task in your package. For more information, 
see Execute SQL Task and Parameters and Return Codes in 
the Execute SQL Task. 


datetime2 The ADO.NET connection manager truncates the millisecond 
value. 


NOTE 


For more information about SQL Server data types and how they map to Integration Services data types, see Data Types 
(Transact-SQL) and Integration Services Data Types. 











ADO.NET connection manager configuration 


You can set properties through SSIS Designer, or programmatically. 
e Provide a specific connection string configured to meet the requirements of the selected .NET provider. 


e Depending on the provider, include the name of the data source to connect to. 


e Provide security credentials as appropriate for the selected provider. 
e Indicate whether the connection created from the connection manager is retained at runtime. 


Many of configuration options of the ADO.NET connection manager depend on the .NET provider that the 


connection Manager uses. 


For more information about the properties that you can set in SSIS Designer, see Configure ADO.NET 


Connection Manager. 


For information about configuring a connection manager programmatically, see ConnectionManager and 
Adding Connections Programmatically. 


Configure ADO.NET connection manager 
Use the Configure ADO.NET Connection Manager dialog box to add a connection to a data source that can 
be accessed by using a .NET Framework data provider. For example, one such provider is the SqlClient provider. 


The connection manager can use an existing connection, or you can create a new one. 


To learn more about the ADO.NET connection manager, see ADO.NET Connection Manager. 


Options 
Data connections 
Select an existing ADO.NET data connection from the list. 


Data connection properties 
View properties and values for the selected ADO.NET data connection. 


New 
Create an ADO.NET data connection by using the Connection Manager dialog box. 


Delete 
Select a connection, and then delete it by selecting Delete. 


Managed identities for Azure resources authentication 

When running SSIS packages on Azure-SSIS integration runtime (IR) in Azure Data Factory (ADF), you can use 
Azure Active Directory (AAD) authentication with the specified system/user-assigned managed identity for your 
ADF to access Azure SQL Database server/Managed Instance. Your Azure-SSIS IR can access and copy data from 


or to your database by using this managed identity. 


NOTE 
When you use AAD authentication to access Azure SQL Database server/Managed Instance, you might encounter a 
problem related to package execution failure or unexpected behavior change. For more information, see AAD features and 


limitations. 











To use AAD authentication with the specified system/user-assigned managed identity for your ADF to access 
Azure SQL Database server, follow these steps: 


1. Provision an AAD administrator for your Azure SQL Database server in Azure portal, if you haven't 
already done so. The AAD administrator can be an AAD user or group. If you grant the group with 
specified system/user-assigned managed identity for your ADF an admin role, skip step 2 - 3. The 
administrator will have full access to your Azure SQL Database server. 


2. Create a contained database user to represent the specified system/user-assigned managed identity for 
your ADF. Connect to the database from or to which you want to copy data using SQL Server 
Management Studio (SSMS) with an AAD user that has at least ALTER ANY USER permission. Run the 
following T-SQL statement: 


CREATE USER [your managed identity name] FROM EXTERNAL PROVIDER; 


If you use the system managed identity for your ADF, then your managed identity name should be your 
ADF name. If you use a user-assigned managed identity for your ADF, then your managed identity name 
should be the specified user-assigned managed identity name. 


. Grant the specified system/user-assigned managed identity for your ADF the required permissions, as 


you normally do for SQL users. Refer to Database-level roles for appropriate roles. Run the following T- 
SQL statement. For more options, see this article. 


EXEC sp_addrolemember [role name], [your managed identity name]; 


To use AAD authentication with the specified system/user-assigned managed identity for your ADF to access 


Azure SQL Managed Instance, follow these steps: 


A. 


Provision an AAD administrator for your Azure SQL Managed Instance in Azure portal, if you haven't 
already done so. The AAD administrator can be an AAD user or group. If you grant the group with 
specified system/user-assigned managed identity for your ADF an admin role, skip step 2 - 4. The 
administrator will have full access to your Azure SQL Managed Instance. 


. Create a login assigned to the specified system/user-assigned managed identity for your ADF. On SSMS, 


connect to your Azure SQL Managed Instance using SQL Server account that is asysadmin. In master 
database, run the following T-SQL statement: 


CREATE LOGIN [your managed identity name] FROM EXTERNAL PROVIDER; 


If you use the system managed identity for your ADF, then your managed identity name should be your 
ADF name. If you use a user-assigned managed identity for your ADF, then your managed identity name 
should be the specified user-assigned managed identity name. 


. Create a contained database user representing the specified system/user-assigned managed identity for 


your ADF. Connect to the database from or to which you want to copy data using SSMS and run the 
following T-SQL statement: 


CREATE USER [your managed identity name] FROM EXTERNAL PROVIDER; 


. Grant the specified system/user-assigned managed identity for your ADF the required permissions, as 


you normally do for SQL users. Run the following T-SQL statement. For more options, see this article. 


ALTER ROLE [role name e.g., db_owner] ADD MEMBER [your managed identity name]; 


Finally, you can configure AAD authentication with the specified system/user-assigned managed identity for 


your ADF on the ADO.NET connection manager. Here are the options to do this: 


e Configure at design time. In SSIS Designer, right-click on your ADO.NET connection manager, and 


select Properties. Update the property ConnectUsingManagedIdentity to True . 





NOTE 


Currently, the connection manager property ConnectUsingManagedIdentity doesn't take effect (indicating that 
AAD authentication with the specified system/user-assigned managed identity for your ADF doesn't work) when 
you run your package in SSIS Designer or on SQL Server. 








e Configure at run time. When you run your package via SSMS or Execute SSIS Package activity in ADF 
pipeline, find the ADO.NET connection manager and update its property cConnectUsingManagedidentity to 


True . 


NOTE 


On Azure-SSIS IR, all other authentication methods (for example, integrated security and password) preconfigured 
on your ADO.NET connection manager are overridden when using AAD authentication with the specified 
system/user-assigned managed identity for your ADF. 





To configure AAD authentication with the specified system/user-assigned managed identity for your ADF on 

your existing packages, the preferred way is to rebuild your SSIS project with the latest SSIS Designer at least 
once. Redeploy your SSIS project to run on Azure-SSIS IR, so that the new connection manager property 
ConnectUsingManagedIdentity is automatically added to all ADO.NET connection managers in your project. The 


alternative way is to directly use property overrides with the property path \Package.Connections[{the name of 
your connection manager}].Proper ties[ConnectUsingManagedidentity] assigned to True at run time. 


See also 


e ADO.NET Source 
e ADO.NET Destination 


e Integration Services (SSIS) Connections 
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An SQL Server Analysis Services connection manager enables a package to connect to a server that runs an 
Analysis Services database or to an Analysis Services project that provides access to cube and dimension data. 
You can only connect to an Analysis Services project while developing packages in SQL Server Data Tools 
(SSDT). At run time, packages connect to the server and the database to which you deployed the Analysis 
Services project. 


Both tasks, such as the Analysis Services Execute DDL task and the Analysis Services Processing task, and 
destinations, such as the Data Mining Model Training destination, use an Analysis Services connection manager. 


For more information about Analysis Services databases, see Multidimensional Model Databases (SSAS). 


Configuration of the Analysis Services Connection Manager 


When you add an Analysis Services connection manager to a package, SQL Server Integration Services creates a 
connection manager that is resolved as an Analysis Services connection at run time, sets the connection 
manager properties, and adds the connection manager to the Connections collection on the package. The 
ConnectionManagerType property of the connection manager is set to MSOLAP100. 


You can configure the Analysis Services connection manager in the following ways: 


e Provide a connection string configured to meet the requirements of the Microsoft OLE Provider for 
Analysis Services provider. 


e Specify the instance of Analysis Services or the Analysis Services project to connect to. 


e Ifyou are connecting to an instance of Analysis Services, specify the authentication mode. 





NOTE 


If you use SSIS in Azure Data Factory (ADF) and want to connect to Azure Analysis Services (AAS) instance, you can not 
use an account with Multi-Factor Authentication (MFA) enabled, but must use an account that does not require any 
interactivity/MFA or a service principal instead. To use the latter, see here to create one and assign the server 
administrator role to it, then select Use a specific user name and password to log on to the server in your 


connection manager, and finally enter User name: app:YourApplicationID and Password: YourAuthorizationkKey . 











e Indicate whether the connection that is created from the connection manager is retained at run time. 

You can set properties through SSIS Designer or programmatically. 

For more information about the properties that you can set in SSIS Designer, click one of the following topic: 
e Add Analysis Services Connection Manager Dialog Box UI Reference 


For information about configuring a connection manager programmatically, see ConnectionManager and 
Adding Connections Programmatically. 


Add Analysis Services Connection Manager Dialog 


Box UI Reference 
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Use the Add Analysis Services Connection Manager dialog box to create a connection to a server running 
SQL Server Analysis Services, or to edit connection properties. 


To learn more about the Analysis Services connection manager, see Analysis Services Connection Manager. 


Options 


Create a connection to a computer running Analysis Services 
Use the default connection to a server that is running an instance of Analysis Services, or create a new 
connection by clicking Edit. 


Edit 
Use the Connection Manager dialog box to create a connection to a server that is running an instance of 
Analysis Services, and to edit connection properties. 


Create a connection to an Analysis Services project in this solution 


Specify that the connection will use an Analysis Services project in the open solution. 





NOTE 


Analysis Services tabular model projects are not supported for this scenario. 





Analysis Services project 
Select an Analysis Services project from the list. 


See Also 


Integration Services Error and Message Reference 
Integration Services (SSIS) Connections 
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A SQL Server Integration Services (SSIS) package can use the Azure Data Lake Analytics connection manager to 
connect to a Data Lake Analytics account with one of the two following authentication types: 


e Azure Active Directory (Azure AD) User Identity 
e Azure AD Service Identity 


The Data Lake Analytics connection manager is a component of the SQL Server Integration Services (SSIS) 
Feature Pack for Azure. 


Configure the connection manager 


1. Inthe Add SSIS Connection Manager dialog box, select AzureDataLakeAnalytics > Add. The Azure 
Data Lake Analytics Connection Manager Editor dialog box opens. 


2. In the Azure Data Lake Analytics Connection Manager Editor dialog box, in the ADLA Account 
Name field, provide the Data Lake Analytics account name. For example: myadlaaccountname. 


3. In the Authentication field, choose the appropriate authentication type to access the data in Data Lake 
Analytics. 


a. If you select the Azure AD User Identity authentication option: 


i. Provide values for the User Name and Password fields. 

ii. To test the connection, select Test Connection. If you or the tenant administrator didn't previously 
consent to allow SSIS to access your Data Lake Analytics account, select Accept when prompted. For 
more information about this consent experience, see Integrating applications with Azure Active Directory. 


NOTE 


When you select the Azure AD User Identity authentication option, multi-factor authentication and Microsoft 


account authentication are not supported. 





b. If you select the Azure AD Service Identity authentication option: 


i. Create an Azure AD application and service principal to access the Data Lake Analytics account. For 
more information about this authentication option, see Use portal to create Active Directory application 
and service principal that can access resources. 

ii. Assign appropriate permissions to let this Azure AD application access your Data Lake Analytics 
account. Learn how to grant permissions to your Data Lake Analytics account by using the Add User 
wizard. 

iii. Provide values for the Application ID, Authentication Key, and Tenant ID fields. 

iv. To test the connection, select Test Connection. 


4. Select OK to close the Azure Data Lake Analytics Connection Manager Editor dialog box. 


View the properties of the connection manager 


You can see the properties of the connection manager you created in the Properties window. 


Azure Data Lake Store Connection Manager 
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A SQL Server Integration Services (SSIS) package can use the Azure Data Lake Store Connection Manager to 
connect to an Azure Data Lake Storage Gen1 account with one of the two following authentication types: 


e Azure AD User Identity 
e Azure AD Service Identity 


The Azure Data Lake Store Connection Manager is a component of the SQL Server Integration Services (SSIS) 
Feature Pack for Azure. 





NOTE 


To ensure that the Azure Data Lake Store Connection Manager and the components that use it - that is, the Data Lake 
Storage Gen1 source and the Data Lake Storage Gen1 destination - can connect to services, make sure you download the 
latest version of the Azure Feature Pack here. 





Configure the Azure Data Lake Store Connection Manager 


1. Inthe Add SSIS Connection Manager dialog box, select AzureDataLake, and then select Add. The 
Azure Data Lake Store Connection Manager Editor dialog box opens. 


2. Inthe Azure Data Lake Store Connection Manager Editor dialog box, in the ADLS Host field, 
provide the Data Lake Storage Gen1 host URL. For example: https://test.azuredatalakestore.net OF 


test.azuredatalakestore.net . 


3. In the Authentication field, choose the appropriate authentication type to access the data in Data Lake 
Storage Gen1. 


a. If you select the Azure AD User Identity authentication option, do the following things: 
a. Provide values for the User Name and Password fields. 


b. To test the connection, select Test Connection. If you or the tenant administrator didn't 
previously consent to allow SSIS to access your Data Lake Storage Gen1 data, select Accept 
when prompted. For more information about this consent experience, see Integrating 
applications with Azure Active Directory. 


NOTE 


When you select the Azure AD User Identity authentication option, multi-factor authentication and 
Microsoft account authentication are not supported. 











b. If you select the Azure AD Service Identity authentication option, do the following things: 


a. Create an Azure Active Directory (AAD) application and service principal to access the Data 
Lake Storage Gen1 data. 


b. Assign appropriate permissions to let this AAD application access your Data Lake Storage 





Gen1 resources. For more information about this authentication option, see Use portal to 
create Active Directory application and service principal that can access resources. 


c. Provide values for the Client Id, Secret Key, and Tenant Name fields. 
d. To test the connection, select Test Connection. 


4. Select OK to close the Azure Data Lake Store Connection Manager Editor dialog box. 


View the properties of the connection manager 


You can see the properties of the connection manager you created in the Properties window. 


Azure HDInsight Connection Manager 
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The Azure HDInsight Connection Manager enables an SSIS package to connect to an Azure HDInsight 
cluster. 


The Azure HDInsight Connection Manager is a component of the SQL Server Integration Services (SSIS) 
Feature Pack for Azure. 


To create and configure an Azure HDInsight Connection Manager, follow the steps below: 


1. Inthe Add SSIS Connection Manager dialog box, select AZureHDInsight, and click Add. 


2. In the Azure HDInsight Connection Manager Editor dialog box, specify the Cluster DNS name 
(without the protocol prefix), Username, and Password for the HDInsight cluster to connect to. 
3. Click OK to close the dialog box. 


4. You can see the properties of the connection manager you created in the Properties window. 


Azure Resource Manager Connection Manager 
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The Azure Resource Manager Connection Manager enables an SSIS package to manage Azure resources 
using a service principal. 


The Azure Resource Manager Connection Manager is a component of the SQL Server Integration Services 
(SSIS) Feature Pack for Azure. 


To create and configure an Azure Resource Manager Connection Manager, follow the steps below: 


1. Inthe Add SSIS Connection Manager dialog box, select AZureResourceManager, and click Add. 
2. In the Azure Resource Manager Connection Manager Editor dialog box, specify the Application ID, 


Application Key, and Tenant ID for the service principal. For details about these properties, please refer to 
this article. 


3. Click OK to close the dialog box. 


4. You can see the properties of the connection manager you created in the Properties window. 


Azure Storage connection manager 
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The Azure Storage connection manager enables a SQL Server Integration Services (SSIS) package to connect to 
an Azure Storage account. The connection manager is a component of the SQL Server Integration Services 
(SSIS) Feature Pack for Azure. 


In the Add SSIS Connection Manager dialog box, select AzureStorage > Add. 
The following properties are available. 


e Service: Specifies the storage service to connect to. 
e Account name: Specifies the storage account name. 
e Authentication: Specifies the authentication method to use. AccessKey, ServicePrincipal, and 

SharedAccessSignature authentication are supported. 

o AccessKey: For this authentication method, specify the Account key. 

o ServicePrincipal: For this authentication method, specify the Application ID, Application key, and 
Tenant ID of the service principal. For Test Connection to work, the service principal should be 
assigned at least the Storage Blob Data Reader role to the storage account. For more information, 
see Grant access to Azure blob and queue data with RBAC in the Azure portal. 

o SharedAccessSignature: For this authentication method, specify at least the Token of the shared 
access signature. To test connection, specify additionally the resource scope to test against. It may be 
Service, Container, or Blob. For Container and Blob, specify container name and blob path, 
respectively. For more information, see Azure Storage shared access signature overview. 


e Environment: Specifies the cloud environment hosting the storage account. 


Managed identities for Azure resources authentication 


When running SSIS packages on Azure-SSIS integration runtime (IR) in Azure Data Factory (ADF), you can use 
Azure Active Directory (AAD) authentication with the specified system/user-assigned managed identity for your 
ADF to access Azure Storage. Your Azure-SSIS IR can access and copy data from or to your storage account by 
using this managed identity. 


Refer to the Authenticate access to Azure Storage using AAD article for Azure Storage authentication in general. 
To use AAD authentication with the specified system/user-assigned managed identity for your ADF to access 
Azure Storage, follow these steps: 


1. Find the specified system/user-assigned managed identity for your ADF from Azure portal. Go to your 
data factory's Properties. Copy the Managed Identity Application ID (not the Managed Identity 
Object ID). 


2. Grant the specified system/user-assigned managed identity for your ADF the required permissions to 
access Azure Storage. For more details about roles, see the Manage access rights to Azure Storage data 
with RBAC article. 


e As source, in Access control (IAM), grant at least the Storage Blob Data Reader role. 


e As destination, in Access control (IAM), grant at least the Storage Blob Data Contributor role. 


Finally, you can configure AAD authentication with the specified system/user-assigned managed identity for 
your ADF on the Azure Storage connection manager. Here are the options to do this: 


e Configure at design time. In SSIS Designer, double-click on your Azure Storage connection manager 
to open the Azure Storage Connection Manager Editor. Select the Use managed identity to 


authenticate on Azure option. 





NOTE 
Currently, this option doesn't take effect (indicating that AAD authentication with the specified system/user- 


assigned managed identity for your ADF doesn't work) when you run your package in SSIS Designer or on SQL 
Server. 








e Configure at run time. When you run your package via SQL Server Management Studio (SSMS) or 
Execute SSIS Package activity in ADF pipeline, find the Azure Storage connection manager and update its 
property ConnectUsingManagedIdentity to True. 





NOTE 

On Azure-SSIS IR, all other authentication methods (for example, integrated security and password) preconfigured 
on your Azure Storage connection manager are overridden when using AAD authentication with the specified 
system/user-assigned managed identity for your ADF. 








To configure AAD authentication with the specified system/user-assigned managed identity for your ADF on 
your existing packages, the preferred way is to rebuild your SSIS project with the latest SSIS Designer at least 
once. Redeploy your SSIS project to run on Azure-SSIS IR, so that the new connection manager property 
ConnectUsingManagedIdentity is automatically added to all Azure Storage connection managers in your project. 
The alternative way is to directly use property overrides with the property path |Package.Connections[{the name 
of your connection manager}].Proper ties[ConnectUsingManagedidentity] assigned to True at run time. 


Secure network traffic to your storage account 


ADF is now a trusted Microsoft service to Azure Storage. When you use AAD authentication with the specified 
system/user-assigned managed identity for your ADF, it's possible to secure your storage account by limiting 
access to selected networks while still allowing your ADF to access it. Please refer to the Managing exceptions 
article for instructions. 


See also 


e Integration Services (SSIS) Connections 


Azure Subscription Connection Manager 
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The Azure Subscription connection manager enables an SSIS package to connect to an Azure subscription 
by using the values you specify for the properties: Azure Subscription ID and Management Certificate. 


The Azure Subscription connection manager is a component of the SQL Server Integration Services (SSIS) 
Feature Pack for Azure. 


1. Inthe Add SSIS Connection Manager dialog box shown above, you select Azure Subscription, and 
click Add. You should see the following Azure Subscription Connection Manager Editor dialog box. 


Azure s subscription ID: 





Management certificate store location: 
Current User 








Management certificate store name: 
My 


Management certificate thumbprint: 








2. Enter your Azure subscription ID, which uniquely identifies an Azure subscription, for the Azure 
subscription ID. The value can be found on the Azure Management Portal under Settings page: 


settings 
SUBSCRIPTIONS MANAGEMENT CERTIFICATES ADMINISTRATORS AFFINITY GROUPS USAGE REMOTEAPP 
SUBSCRIPTION SUBSCRIPTION ID ACCOUNT ADMINISTRATOR DIRECTORY Pp 





380d69be3228 


3. Choose Management certificate store location and Management certificate store name from 
the drop-down lists. 


4. Enter Management certificate thumbprint or click the Browse... to choose a certificate from the 
selected store. The certificate must be uploaded as a management certificate for the subscription. To do 
so, click Upload on the following page of the Azure Portal (see this MSDN post for more detail). 


settings 


SUBSCRIPTIONS MANAGEMENT CERTIFICATES ADMINISTRATORS AFFINITY GROUPS USAGE REMOTEAPP 





5. Click Test Connection to test the connection. 


6. Click OK to close the dialog box. 


Excel Connection Manager 
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An Excel connection manager enables a package to connect to a Microsoft Excel workbook file. The Excel source 
and the Excel destination that Microsoft SQL Server Integration Services includes use the Excel connection 
manager. 


IMPORTANT 


For detailed info about connecting to Excel files, and about limitations and known issues for loading data from or to Excel 


files, see Load data from or to Excel with SQL Server Integration Services (SSIS). 











When you add an Excel connection manager to a package, Integration Services creates a connection manager 
that is resolved as an Excel connection at run time, sets the connection manager properties, and adds the 
connection manager to the Connections collection on the package. 


The ConnectionManagerType property of the connection manager is set to EXCEL. 


Configure the Excel Connection Manager 


You can configure the Excel connection manager in the following ways: 

e Specify the path of the Excel workbook file. 

e Specify the version of Excel that was used to create the file. 

e Indicate whether the first row in the selected worksheets or ranges contains column names. 
You can set properties through SSIS Designer or programmatically. 


For more information about the properties that you can set in SSIS Designer, see Excel Connection Manager 
Editor. 


For information about configuring a connection manager programmatically, see ConnectionManager and 
Adding Connections Programmatically. 


Excel Connection Manager Editor 


Use the Excel Connection Manager Editor dialog box to add a connection to an existing or a new Microsoft 
Excel workbook file. 


Options 
Excel file path 
Type the path and file name of an existing or a new Excel workbook file. 


Browse 
Use the Open dialog box to navigate to the folder in which the Excel file exists or where you want to create the 
new file. 


Excel version 


Specify the version of Microsoft Excel that was used to create the file. 


First row has column names 
Specify whether the first row of data in the selected worksheet contains column names. The default value of this 


option is True. 


Solution to import data with mixed data types from Excel 


If you use data that contains mixed data types, by default, the Excel driver reads the first 8 rows (configured by 
the TypeGuessRows register key). Based on the first 8 rows of data, the Excel driver tries to guess the data type 
of each column. For example, if your Excel data source has numbers and text in one column, if the first 8 rows 
contain numbers, the driver might determine based on those first 8 rows that the data in the column is the 
integer type. In this case, SSIS skips text values and imports them as NULL into the destination. 


To resolve this issue, you can try one of following solutions: 
e@ Change the Excel column type to Text in the Excel file. 


e Add the IMEX extended property to the connection string to override the driver's default behavior. When 
you add the ";IMEX=1" extended property to the end of the connection string, Excel treats all data as text. 


See the following example: 


Provider=Microsoft.ACE.OLEDB.12.0;Data Source=C:\ExcelFileName.xlsx;Extended Properties="EXCEL 12.0 
XML; HDR=YES; IMEX=1" ; 


For this solution to work reliably, you might have to also modify the registry settings. The main.cmd file is 


as follows: 


reg add "HKEY_LOCAL_MACHINE\SOFTWARE \WOW6432Node\Microsoft\Office\12.0\Access Connectivity 
Engine\Engines\Excel" /t REG_DWORD /v TypeGuessRows /d @ /f 

reg add "HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\O0ffice\12.0\Access Connectivity Engine\Engines\Excel" 
/t REG_DWORD /v TypeGuessRows /d 0 /f 

reg add "HKEY_LOCAL_MACHINE\SOFTWARE \WOW6432Node\Microsoft\Office\14.0\Access Connectivity 
Engine\Engines\Excel" /t REG_DWORD /v TypeGuessRows /d @ /f 

reg add "HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\O0ffice\14.0\Access Connectivity Engine\Engines\Excel" 
/t REG_DWORD /v TypeGuessRows /d @ /f 

reg add "HKEY_LOCAL_MACHINE\SOFTWARE \WOW6432Node\Microsoft\Office\15.0\Access Connectivity 
Engine\Engines\Excel" /t REG_DWORD /v TypeGuessRows /d @ /f 

reg add "HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\O0ffice\15.0\Access Connectivity Engine\Engines\Excel" 
/t REG_DWORD /v TypeGuessRows /d 0 /f 

reg add "HKEY_LOCAL_MACHINE\SOFTWARE \WOW6432Node\Microsoft\Office\16.0\Access Connectivity 
Engine\Engines\Excel" /t REG_DWORD /v TypeGuessRows /d @ /f 

reg add "HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\O0ffice\16.0\Access Connectivity Engine\Engines\Excel" 
/t REG_DWORD /v TypeGuessRows /d @ /f 


e Save the file in CSV format and change the SSIS package to support a CSV import. 


Related Tasks 


Load data from or to Excel with SQL Server Integration Services (SSIS) 
Excel Source 
Excel Destination 


File Connection Manager 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


A File connection manager enables a package to reference an existing file or folder, or to create a file or folder at 
run time. For example, you can reference an Excel file. Certain components in Microsoft SQL Server Integration 
Services use information in files to perform their work. For example, an Execute SQL task can reference a file 
that contains the SQL statements that the task executes. Other components perform operations on files. For 
example, the File System task can reference a file to copy it to a new location. 


Usage Types of the File Connection Manager 


The FileUsageType property of the File connection manager specifies how the file connection is used. The File 
connection manager can create a file, create a folder, use an existing file, or use an existing folder. 


The following table lists the values of FileUsageType. 


VALUE DESCRIPTION 

0 File connection manager uses an existing file. 

1 File connection manager creates a file. 

2 File connection manager uses an existing folder. 
3 File connection manager creates a folder. 


Multiple File or Folder Connections 


The File connection manager can reference only one file or folder. To reference multiple files or folders, use a 
Multiple Files connection manager instead of a File connection manager. For more information, see Multiple 
Files Connection Manager. 


Configuration of the File Connection Manager 


When you add a File connection manager to a package, Integration Services creates a connection manager that 
will resolve to a File connection at run time, sets the File connection properties, and adds the File connection to 
the Connections collection of the package. 


The ConnectionManagerType property of the connection manager is set to FILE. 
You can configure a File connection manager in the following ways: 

e Specify the usage type. 

e Specify a file or folder. 


You can set the ConnectionString property for the File connection manager by specifying an expression in the 
Properties window of SQL Server Data Tools (SSDT). However, to avoid a validation error when you use an 
expression to specify the file or folder, in the File Connection Manager Editor, for File/Folder, add a file or 
folder path. 


You can set properties through SSIS Designer or programmatically. 


For more information about the properties that you can set in SSIS Designer, see File Connection Manager 
Editor. 


For information about configuring a connection manager programmatically, see ConnectionManager and 
Adding Connections Programmatically. 


File Connection Manager Editor 


Use the File Connection Manager Editor dialog box to specify the properties used to connect to a file or a 
folder. 


NOTE 

You can set the ConnectionString property for the File connection manager by specifying an expression in the Properties 
window of SQL Server Data Tools (SSDT). However, to avoid a validation error when you use an expression to specify the 
file or folder, in the File Connection Manager Editor, for File/Folder, add a file or folder path. 





To learn more about the File connection manager, see File Connection Manager. 


Options 
Usage Type 
Specify whether the File Connection Manager connects to an existing file or folder or creates a new file or 
folder. 
VALUE DESCRIPTION 
Create file Create a new file at run time. 
Existing file Use an existing file. 
Create folder Create a new folder at run time. 
Existing folder Use an existing folder. 
File / Folder 


If File, specify the file to use. 
If Folder, specify the folder to use. 


Browse 


Select the file or folder by using the Select File or Browse for Folder dialog box. 





Add File Connection Manager Dialog Box UI 


Reference 
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Applies to: Q sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 
Use the Add File Connection Manager dialog box to define a connection to a group of files or folders. 


To learn more about the Multiple Files connection manager, see Multiple Files Connection Manager. 


NOTE 


The built-in tasks and data flow components in Integration Services do not use the Multiple Files connection manager. 
However, you can use this connection manager in the Script task or Script component. 











Options 


Usage type 
Specify the type of files to use for the multiple files connection manager. 


VALUE DESCRIPTION 

Create files The connection manager will create the files. 
Existing files The connection manager will use existing files. 
Create folders The connection manager will create the folders. 
Existing folders The connection manager will use existing folders. 


Files / Folders 
View the files or folders that you have added by using the buttons described as follows. 


Add 
Add a file by using the Select Files dialog box, or add a folder by using the Browse for Folder dialog box. 


Edit 
Select a file or folder, and then replace it with a different file or folder by using the Select Files or Browse for 
Folder dialog box. 


Remove 


Select a file or folder, and then remove it from the list by using the Remove button. 
Arrow buttons 


Select a file or folder, and then use the arrow buttons to move it up or down to specify the sequence of access. 


See Also 


Integration Services Error and Message Reference 


Suggest Column Types Dialog Box UI Reference 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Use the Suggest Column Types dialog box to identify the data type and length of columns in a Flat File 
Connection Manager based on a sampling of the file content. 


To learn more about the data types used by Integration Services, see Integration Services Data Types. 


Options 


Number of rows 
Type or select the number of rows in the sample that the algorithm uses. 


Suggest the smallest integer data type 
Clear this check box to skip the assessment. If selected, determines the smallest possible integer data type for 
columns that contain integral numeric data. 


Suggest the smallest real data type 
Clear this check box to skip the assessment. If selected, determines whether columns that contain real numeric 
data can use the smaller real data type, DT_R4. 


Identify Boolean columns using the following values 
Type the two values that you want to use as the Boolean values true and false. The values must be separated by 
a comma, and the first value represents True. 


Pad string columns 
Select this check box to enable string padding. 


Percent padding 
Type or select the percentage of the column lengths by which to increase the length of columns for character 
data types. The percentage must be an integer. 


See Also 


Integration Services Error and Message Reference 
Flat File Connection Manager 


Flat File Connection Manager 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


A Flat File connection manager enables a package to access data in a flat file. For example, the Flat File source 
and destination can use Flat File connection managers to extract and load data. 


The Flat File connection manager can access only one file. To reference multiple files, use a Multiple Flat Files 
connection manager instead of a Flat File connection manager. For more information, see Multiple Flat Files 
Connection Manager. 


Column Length 


By default, the Flat File connection manager sets the length of string columns to 50 characters. In the Flat File 
Connection Manager Editor dialog box, you can evaluate sample data and automatically resize the length of 
these columns to prevent truncation of data or excess column width. Also, unless you subsequently resize the 
column length in a Flat File source or a transformation, the column length of string column remains the same 
throughout the data flow. If these string columns map to destination columns that are narrower, warnings 
appear in the user interface. Moreover, at run time, errors may occur due to data truncation. To avoid errors or 
truncation, you can resize the columns to be compatible with the destination columns in the Flat File connection 
manager, the Flat File source, or a transformation. To modify the length of output columns, you set the Length 
property of the output column on the Input and Output Properties tab in the Advanced Editor dialog box. 


If you update column lengths in the Flat File connection manager after you have added and configured the Flat 
File source that uses the connection manager, you do not have to manually resize the output columns in the Flat 
File source. When you open the Flat File Source dialog box, the Flat File source provides an option to 
synchronize the column metadata. 


Configuration of the Flat File Connection Manager 


When you add a Flat File connection manager to a package, SQL Server Integration Services creates a 
connection manager that will resolve to a Flat File connection at run time, sets the Flat File connection 
properties, and adds the Flat File connection manager to the Connections collection of the package. 


The ConnectionManagerType property of the connection manager is set to FLATFILE. 


By default, the Flat File connection manager always checks for a row delimiter in unquoted data, and starts a 
new row when a row delimiter is found. This enables the connection manager to correctly parse files with rows 
that are missing column fields. 


In some cases, disabling this feature may improve package performance. You can disable this feature by setting 
the Flat File connection manager property, AlwaysCheckForRowDelimiters, to False. 


You can configure the Flat File connection manager in the following ways: 


e Specify the file, locale, and code page to use. The locale is used to interpret locale-sensitive data such as 
dates, and the code page is used to convert string data to Unicode. 


e Specify the file format. You can use a delimited, fixed width, or ragged right format. 


e Specify a header row, data row, and column delimiters. Column delimiters can be set at the file level and 
overwritten at the column level. 


e Indicate whether the first row in the file contains column names. 
e Specify a text qualifier character. Each column can be configured to recognize a text qualifier. 


The use of a qualifier character to embed a qualifier character into a qualified string is supported by the 
Flat File Connection Manager. The double instance of a text qualifier is interpreted as a literal, single 
instance of that string. For example, if the text qualifier is a single quote and the input data is ‘abc’, ‘def’, 
‘g'hi’, the output data is abc, def, g'hi. However, an instance of a qualifier embedded in a qualified string 
causes the Flat File Source to fail with the error DTS_E_PRIMEOUTPUTFAILED. 


e Set properties such as the name, data type, and maximum width on individual columns. 


You can set the ConnectionString property for the Flat File connection manager by specifying an expression in 
the Properties window of SQL Server Data Tools (SSDT). To avoid a validation error, do the following. 


e When you use an expression to specify the file, add a file path in the File name box in the Flat File 
Connection Manager Editor. 


e Set the DelayValidation property on the Flat File connection manager to True. 


You can use an expression to create a file name at runtime by using the Flat File connection manager with the 


Flat File destination. 
You can set properties through SSIS Designer or programmatically. 


For information about configuring a connection manager programmatically, see ConnectionManager and 
Adding Connections Programmatically. 


Flat File Connection Manager Editor (General Page) 


Use the General page of the Flat File Connection Manager Editor dialog box to select a file and data 
format. A flat file connection enables a package to connect to a text file. 


To learn more about the Flat File connection manager, see Flat File Connection Manager. 


Options 
Connection manager name 


Provide a unique name for the flat file connection in the workflow. The name provided will be displayed within 
SSIS Designer. 


Description 
Describe the connection. As a best practice, describe the connection in terms of its purpose, to make packages 


self-documenting and easier to maintain. 


File name 


Type the path and file name to use in the flat file connection. 


Browse 


Locate the file name to use in the flat file connection. 


Locale 
Specify the locale to provide language-specific information for ordering and for date and time formats. 


Unicode 
Indicate whether to use Unicode. If you use Unicode, you cannot specify a code page. 


Code page 
Specify the code page for non-Unicode text. 


Format 


Indicate whether the file uses delimited, fixed width, or ragged right formatting. 
VALUE DESCRIPTION 


Delimited Columns are separated by delimiters, specified on the 
Columns page. 


Fixed width Columns have a fixed width. 


Ragged right Ragged right files are files in which every column has a fixed 
width, except for the last column. It is delimited by the row 
delimiter. 


Text qualifier 


Specify the text qualifier to use. For example, you can specify that text fields are enclosed in quotation marks. 





NOTE 


After you select a text qualifier, you cannot re-select the None option. Type None to de-select the text qualifier. 





Header row delimiter 
Select from the list of delimiters for header rows, or enter the delimiter text. 


VALUE DESCRIPTION 

{CR}{LF} The header row is delimited by a carriage return-line feed 
combination. 

{CR} The header row is delimited by a carriage return. 

{LF} The header row is delimited by a line feed. 

Semicolon {;} The header row is delimited by a semicolon. 

Colon {:} The header row is delimited by a colon. 

Comma {,} The header row is delimited by a comma. 

Tab {t} The header row is delimited by a tab. 

Vertical bar {|} The header row is delimited by a vertical bar. 


Header rows to skip 
Specify the number of header rows or initial data rows to skip, if any. 


Column names in the first data row 
Indicate whether to expect or provide column names in the first data row. 


Flat File Connection Manager Editor (Columns Page) 


Use the Columns page of the Flat File Connection Manager Editor dialog box to specify the row and 


column information, and to preview the file. 


To learn more about the Flat File connection manager, see Flat File Connection Manager. 


Static Options 


Connection manager name 
Provide a unique name for the Flat File connection in the workflow. The name provided will be displayed within 
SSIS Designer. 


Description 
Describe the connection. As a best practice, describe the connection in terms of its purpose, to make packages 
self-documenting and easier to maintain. 


Flat File Format Dynamic Options 

Format = Delimited 

Row delimiter 

Select from the list of available row delimiters, or enter the delimiter text. 


VALUE DESCRIPTION 

{CR}{LF} Rows are delimited by a carriage return-line feed 
combination. 

{CR} Rows are delimited by a carriage return. 

{LF} Rows are delimited by a line feed. 

Semicolon {;} Rows are delimited by a semicolon. 

Colon {:} Rows are delimited by a colon. 

Comma {,} Rows are delimited by a comma. 

Tab {t} Rows are delimited by a tab. 

Vertical bar {|} Rows are delimited by a vertical bar. 


Column delimiter 


Select from the list of available column delimiters, or enter the delimiter text. 


VALUE DESCRIPTION 

{CR}{LF} Columns are delimited by a carriage return-line feed 
combination. 

{CR} Columns are delimited by a carriage return. 

{LF} Columns are delimited by a line feed. 

Semicolon {;} Columns are delimited by a semicolon. 

Colon {:} Columns are delimited by a colon. 

Comma {,} Columns are delimited by a comma. 


Tab {t} Columns are delimited by a tab. 


VALUE DESCRIPTION 


Vertical bar {|} Columns are delimited by a vertical bar. 


Refresh 
View the effect of changing the delimiters to skip by clicking Refresh. This button only becomes visible after 
you have changed other connection options. 


Preview rows 
View sample data in the flat file, divided into columns and rows by using the options selected. 


Reset Columns 
Remove all but the original columns by clicking Reset Columns. 


Format = Fixed Width 
Font 
Select the font in which to display the preview data. 


Source data columns 
Adjust the width of the row by sliding the vertical red row marker, and adjust the width of the columns by 
clicking the ruler at the top of the preview window 


Row width 
Specify the length of the row before adding delimiters for individual columns. Or, drag the vertical red line in the 
preview window to mark the end of the row. The row width value is automatically updated. 


Reset Columns 
Remove all but the original columns by clicking Reset Columns. 


Format = Ragged Right 


NOTE 


Ragged right files are files in which every column has a fixed width, except for the last column. It is delimited by the row 


delimiter. 





Font 
Select the font in which to display the preview data. 


Source data columns 
Adjust the width of the row by sliding the vertical red row marker, and adjust the width of the columns by 
clicking the ruler at the top of the preview window 


Row delimiter 
Select from the list of available row delimiters, or enter the delimiter text. 


VALUE DESCRIPTION 

{CR}{LF} Rows are delimited by a carriage return-line feed 
combination. 

{CR} Rows are delimited by a carriage return. 

{LF} Rows are delimited by a line feed. 


Semicolon {;} Rows are delimited by a semicolon. 


VALUE DESCRIPTION 


Colon {:} Rows are delimited by a colon. 
Comma {,} Rows are delimited by a comma. 
Tab {t} Rows are delimited by a tab. 
Vertical bar {|} Rows are delimited by a vertical bar. 


Reset Columns 
Remove all but the original columns by clicking Reset Columns. 


Flat File Connection Manager Editor (Advanced Page) 


Use the Advanced page of the Flat File Connection Manager Editor dialog box to set properties that 
specify how Integration Services reads and writes data in flat files. You can change the names of columns in the 
flat file, and set properties that include data type and delimiters for each column in the file. 


By default, the length of string columns is 50 characters. You can resize the length of these columns to prevent 
truncation of data or excess column width. You can also update other metadata to enable compatibility with 
destination columns. For example, you might change the data type of a column that contains only integer data 
to a numeric data type, such as DT_I2. You can make these modifications manually, or you can click the Select 
Types button to use the Suggest Column Types dialog box to evaluate sample data and make some of these 
changes for you automatically. 


To learn more about the Flat File connection manager, see Flat File Connection Manager. 


Options 
Connection manager name 


Provide a unique name for the flat file connection manager in the workflow. The name provided will be 
displayed within SSIS Designer. 


Description 
Describe the connection manager. As a best practice, describe the connection manager in terms of its purpose, to 


make packages self-documenting and easier to maintain. 


Configure the properties of each column 
Select a column in the left pane to view its properties in the right pane. See the following table for a description 
of data type properties. Some of the properties listed are configurable only for some flat file formats. 


PROPERTY DESCRIPTION 


ColumnType Denotes whether the column is delimited, fixed width, or 
ragged right. This property is read-only. Ragged right files 
are files in which every column has a fixed width, except for 
the last column. It is delimited by the row delimiter. 


OutputColumnWidth Specify a value to be stored as a count of bytes; for Unicode 
files, this value corresponds to a count of characters. In the 
Data Flow task, this value is used to set the output column 
width for the Flat File source. In the object model, the name 
of this property is MaximumWidth. 


PROPERTY 


DataType 


Text Qualified 


Name 


DataScale 


ColumnDelimiter 


DataPrecision 


InputColumnWidth 


New 


DESCRIPTION 


Select from the list of available data types. For more 
information, see Integration Services Data Types. 


Indicate whether text data is surrounded by text qualifier 
characters such as quote characters. 


True: Text data in the flat file is qualified. False: Text data in 
the flat file is NOT qualified. 


Provide a descriptive column name. If you do not enter a 
name, Integration Services automatically creates a name in 
the format Column 0, Column 1 and so forth. 


Specify the scale of numeric data. Scale refers to the number 
of decimal places. For more information, see Integration 
Services Data Types. 


Select from the list of available column delimiters. Choose 
delimiters that are not likely to occur in the text. This value is 
ignored for fixed-width columns. 


{CR}{LF}. Columns are delimited by a carriage return-line 
feed combination. 


{CR}. Columns are delimited by a carriage return. 
{LF}. Columns are delimited by a line feed. 
Semicolon {;}. Columns are delimited by a semicolon. 
Colon {:}. Columns are delimited by a colon. 

Comma {,}. Columns are delimited by a comma. 

Tab {t}. Columns are delimited by a tab. 


Vertical bar {|}. Columns are delimited by a vertical bar. 


Specify the precision of numeric data. Precision refers to the 
number of digits. For more information, see Integration 
Services Data Types. 


Specify a value to be stored as a count of bytes; for Unicode 
files, this will display as a count of characters. This value is 
ignored for delimited columns. 


Note In the object model, the name of this property is 
ColumnWidth. 


Add a new column by clicking New. By default, the New button adds a new column at the end of the list. The 


button also has the following options, available in the drop-down list. 


VALUE 


Add Column 


DESCRIPTION 


Add a new column at the end of the list. 


VALUE DESCRIPTION 


Insert Before Insert a new column before the selected column. 
Insert After Insert a new column after the selected column. 
Delete 


Select a column, and then remove it by clicking Delete. 


Suggest Types 

Use the Suggest Column Types dialog box to evaluate sample data in the file and to obtain suggestions for 
the data type and length of each column. For more information, see Suggest Column Types Dialog Box UI 
Reference. 


Flat File Connection Manager Editor (Preview Page) 


Use the Preview node of the Flat File Connection Manager Editor dialog box to view the contents of the 


source file in a tabular format. 
To learn more about the Flat File connection manager, see Flat File Connection Manager. 


Options 

Connection manager name 

Provide a unique name for the Flat File connection in the workflow. The name provided will be displayed within 
SSIS Designer. 


Description 
Describe the connection. As a best practice, describe the connection in terms of its purpose, to make packages 
self-documenting and easier to maintain. 


Data rows to skip 
Specify how many rows to skip at the beginning of the flat file. 


Refresh 
View the effect of changing the number of rows to skip by clicking Refresh. This button only becomes visible 
after you have changed other connection options. 


Preview rows 
View sample data in the flat file, divided into columns and rows according to the options you have selected. 


FTP Connection Manager 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


An FTP connection manager enables a package to connect to a File Transfer Protocol (FTP) server. The FTP task 
that SQL Server Integration Services includes uses this connection manager. 


When you add an FTP connection manager to a package, Integration Services creates a connection manager that 
can be resolved as an FTP connection at run time, sets the connection manager properties, and adds the 
connection manager to the Connections collection on the package. 


The ConnectionManagerType property of the connection manager is set to FTP. 
You can configure the FTP connection manager in the following ways: 
e Specify a server name and server port. 


e Specify anonymous access, or provide a user name and a password for basic authentication. 





IMPORTANT 


The FTP connection manager supports only anonymous authentication and basic authentication. It does not 
support Windows Authentication. 








e Set the time-out, number of retries, and the amount of data to copy at a time. 
e Indicate whether the FTP connection manager uses passive or active mode. 


Depending on the configuration of the FTP site to which the FTP connection manager connects, you may need to 
change the following default values of the connection manager: 


e The server port is set to 21. You should specify the port that the FTP site listens to. 


e The user name is set to “anonymous”. You should provide the credentials that the FTP site requires. 


Active/Passive Modes 


An FTP connection manager can send and receive files using either active mode or passive mode. In active 
mode, the server initiates the data connection, and in passive mode, the client initiates the data connection. 


Configuration of the FTP Connection Manager 
You can set properties through SSIS Designer or programmatically. 
For information about the properties that you can set in SSIS Designer, see FTP Connection Manager Editor. 


For information about configuring a connection manager programmatically, see ConnectionManager and 
Adding Connections Programmatically. 


FTP Connection Manager Editor 


Use the FTP Connection Manager Editor dialog box to specify properties for connecting to an FTP server. 





IMPORTANT 


The FTP connection manager supports only anonymous authentication and basic authentication. It does not support 
Windows Authentication. 











To learn more about the FTP connection manager, see FTP Connection Manager. 


Options 
Server name 


Provide the name of the FTP server. 


Server port 
Specify the port number on the FTP server to use for the connection. The default value of this property is 21. 


User name 


Provide a user name to access the FTP server. The default value of this property is anonymous. 


Password 
Provide the password to access the FTP server. 


Time-out (in seconds) 
Specify the number of seconds the task takes before timing out. A value of 0 indicates an infinite amount of 
time. The default value of this property is 60. 


Use passive mode 

Specify whether the server or the client initiates the connection. The server initiates the connection in active 
mode, and the client activates the connection in passive mode. The default value of this property is active 
mode. 


Retries 
Specify the number of times the task attempts to make a connection. A value of 0 indicates no limit to the 
number of attempts. 


Chunk size (in KB) 
Provide a chunk size in kilobytes for transmitting data. 


Test Connection 
After configuring the FTP Connection Manager, confirm that the connection is viable by clicking Test 
Connection. 


See Also 


FTP Task 
Integration Services (SSIS) Connections 


Hadoop Connection Manager 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


The Hadoop Connection Manager enables a SQL Server Integration Services (SSIS) package to connect to a 
Hadoop cluster, by using the values you specify for the properties. 


Configure the Hadoop Connection Manager 


1. Inthe Add SSIS Connection Manager dialog box, select Hadoop > Add. The Hadoop Connection 
Manager Editor dialog box opens. 


2. To configure related Hadoop cluster information, choose the WebHCat or WebHDFS tab in the left pane. 
3. If you enable the WebHCat option to invoke a Hive or Pig job on Hadoop, do the following: 
a. For WebHCat Host, enter the server that hosts the WebHCat service. 


b. For WebHCat Port, enter the port of the WebHCat service, which by default is 50111. 


c. Select the Authentication method for accessing the WebHCat service. The available values are 
Basic and Kerberos. 





Hadoop Connection Manager Editor 





[_] Enable WebHCat Connection 











WebHCat Host: 





WebHCat Port: 50111 
WebHDFS 


























Test Connection | 0K | | Cancel | 

















+ Hadoop Connection Manager Editor 

















& Enable WebHCat Connection 
WebHCat 
WebHCat Host: 
pd WebHCat Port: 50111 
WebHDFS 
Authentication: Kerberos v 
WebHCat User: 
Password: 
Domain 
Test Connection OK Cancel 











d. For WebHCat User, enter the User authorized to access WebHCat. 
e. If you select Kerberos authentication, enter the user's Password and Domain. 
4. If you enable the WebHDFS option to copy data from or to HDFS, do the following: 
a. For WebHDFS Host, enter the server that hosts the WebHDFS service. 
b. For WebHDFS Port, enter the port of the WebHDFS service, which by default is 50070. 


c. Select the Authentication method for accessing the WebHDFS service. The available values are 
Basic and Kerberos. 


d. For WebHDFS User, enter the user authorized to access HDFS. 
e. If you select Kerberos authentication, enter the user's Password and Domain. 
5. Select Test Connection. (Only the connection that you enabled is tested.) 


6. Select OK to close the dialog box. 


Connect with Kerberos authentication 


There are two options to set up the on-premises environment so you can use Kerberos authentication with the 
Hadoop Connection Manager. You can choose the option that better fits your circumstances. 


e@ Option 1: Join the SSIS computer to the Kerberos realm 


e Option 2: Enable mutual trust between the Windows domain and the Kerberos realm 


Option 1: Join the SSIS computer to the Kerberos realm 


Requirements: 


e The gateway computer needs to join the Kerberos realm, and can't join any Windows domain. 


How to configure: 


On the SSIS computer: 
1. Run the Ksetup utility to configure the Kerberos Key Distribution Center (KDC) server and realm. 


The computer must be configured as a member of a workgroup, because a Kerberos realm is different 
from a Windows domain. Set the Kerberos realm and add a KDC server, as shown in the following 


example. Replace REALM.com with your own respective realm, as needed. 


C:> Ksetup /setdomain REALM.COM 
C:> Ksetup /addkdc REALM.COM <your_kdc_server_address> 


After running these commands, restart the computer. 
2. Verify the configuration with Ksetup command. The output should look like the following sample 


C:> Ksetup 


default realm = REALM.COM (external) 
REALM. com: 


kdc = <your_kdc_server_address> 


Option 2: Enable mutual trust between the Windows domain and the Kerberos realm 
Requirements: 


e The gateway computer must join a Windows domain. 
e You need permission to update the domain controller's settings. 


How to configure: 





NOTE 


Replace REALM.coM and AbD.com in the following tutorial with your own respective realm and domain controller, as 
needed. 





On the KDC server: 


1. Edit the KDC configuration in the krb5.conf file. Allow KDC to trust the Windows domain by referring to 
the following configuration template. By default, the configuration is located at /etc/krb5.conf. 





[logging] 

default = FILE:/var/log/krb5libs.log 

kdc = FILE:/var/log/krb5kdc.1log 
admin_server = FILE:/var/log/kadmind.1log 


[libdefaults] 
default_realm = REALM.COM 
dns_lookup_realm = false 
dns_lookup_kdc = false 
ticket_lifetime = 24h 
renew_lifetime = 7d 
forwardable = true 


[realms] 

REALM.COM = { 
kdc = node.REALM.COM 
admin_server = node.REALM.COM 


} 

AD.COM = { 
kde = windc.ad.com 
admin_server = windc.ad.com 


} 


[domain_realm] 
»REALM.COM = REALM.COM 
REALM.COM = REALM.COM 
-ad.com = AD.COM 
ad.com = AD.COM 
[capaths ] 


AD.COM = { 
REALM.COM = . 


} 


Restart the KDC service after configuration. 


2. Prepare a principal named krbtgt/REALM.COM@AD.COM on the KDC server. Use the following 


command: 
Kadmin> addprinc krbtgt/REALM.COM@AD.COM 


3. In the hadoop.security.auth_to_local HDFS service configuration file, add 
RULE: [1:$1@$0](.*@AD.COM)s/@.*// . 


On the domain controller: 


1. Run the following Ksetup commands to add a realm entry: 


C:> Ksetup /addkdc REALM.COM <your_kdc_server_address> 
C:> ksetup /addhosttorealmmap HDFS-service-FQDN REALM.COM 


2. Establish trust from the Windows domain to the Kerberos realm. In the following example, [password] is 
the password for the principal krbtgt/REALM.COM@AD.COM. 


C:> netdom trust REALM.COM /Domain: AD.COM /add /realm /password: [password] 
3. Select an encryption algorithm to use with Kerberos. 


a. Go to Server Manager > Group Policy Management > Domain. From there, go to Group 
Policy Objects > Default or Active Domain Policy > Edit. 


b. In the Group Policy Management Editor pop-up window, go to Computer Configuration > 


Policies > Windows Settings. From there, go to Security Settings > Local Policies > 
Security Options. Configure Network security: Configure Encryption types allowed for 
Kerberos. 


c. Select the encryption algorithm you want to use to connect to the KDC. Typically you can select 
any of the options. 
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d. Use the Ksetup command to specify the encryption algorithm to be used on the specific realm. 


C:> ksetup /SetEncTypeAttr REALM.COM DES-CBC-CRC DES-CBC-MD5 RC4-HMAC-MD5 AES128-CTS-HMAC-SHA1- 
96 AES256-CTS-HMAC-SHA1-96 


4. To use the Kerberos principal in the Windows domain, create the mapping between the domain account 
and Kerberos principal. 


a. Go to Administrative tools > Active Directory Users and Computers. 
b. Configure advanced features by selecting View > Advanced Features. 


c. Locate the account to which you want to create mappings, right-click to view Name Mappings, 
and then select the Kerberos Names tab. 


d. Add a principal from the realm. 
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On the gateway computer: 


Run the following Ksetup commands to add a realm entry. 


C:> Ksetup /addkdc REALM.COM <your_kdc_server_address> 
C:> ksetup /addhosttorealmmap HDFS-service-FQDN REALM.COM 


See also 


Hadoop Hive Task 
Hadoop Pig Task 
Hadoop File System Task 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


An HTTP connection enables a package to access a Web server by using HTTP to send or receive files. The Web 
Service task that SQL Server Integration Services includes uses this connection manager. 


When you add an HTTP connection manager to a package, Integration Services creates a connection manager 
that will resolve to an HTTP connection at run time, sets the connection manager properties, and adds the 
connection manager to the Connections collection on the package. 


The ConnectionManagerType property of the connection manager is set to HTTP. 
You can configure the HTTP connection manager the following ways: 


e Use credentials. If the connection manager uses credentials, its properties include the user name, 
password, and domain. 





IMPORTANT 


The HTTP connection manager supports only anonymous authentication and basic authentication. It does not 
support Windows Authentication. 








e Use a client certificate. If the connection manager uses a client certificate, its properties include the 
certificate name. 


e Provide a time-out for connecting to the server and a chunk size for writing data. 


e Use a proxy server. The proxy server can also be configured to use credentials and to bypass the proxy 
server and use local addresses instead. 


Configuration of the HTTP Connection Manager 


You can set properties through SSIS Designer or programmatically. 


For information about configuring a connection manager programmatically, see ConnectionManager. 


HTTP Connection Manager Editor (Server Page) 


Use the Server tab of the HTTP Connection Manager Editor dialog box to configure the HTTP Connection 
Manager by specifying properties such as the URL and security credentials. An HTTP connection enables a 
package to access a Web server by using HTTP to send or receive files. After configuring the HTTP Connection 
Manager, you can also test the connection. 





IMPORTANT 


The HTTP connection manager supports only anonymous authentication and basic authentication. It does not support 
Windows Authentication. 











To learn more about the HTTP connection manager, see HTTP Connection Manager. To learn more about a 
common usage scenario for the HTTP Connection Manager, see Web Service Task. 


Options 
Server URL 
Type the URL for the server. 


If you plan to use the Download WSDL button on the General page of the Web Service Task Editor to 
download a WSDL file, type the URL for the WSDL file. This URL ends with "?wsdl". 


Use credentials 
Specify whether you want the HTTP Connection Manager to use the user's security credentials for 
authentication. 


User name 


If the HTTP Connection Manager uses credentials, you must specify a user name, password, and domain. 


Password 
If the HTTP Connection Manager uses credentials, you must specify a user name, password, and domain. 


Domain 
If the HTTP Connection Manager uses credentials, you must specify a user name, password, and domain. 


Use client certificate 
Specify whether you want the HTTP Connection Manager to use a client certificate for authentication. 


Certificate 
Select a certificate from the list by using the Select Certificate dialog box. The text box displays the name 
associated with this certificate. 


Time-out (in seconds) 
Provide a time-out for connecting to the Web server. The default value of this property is 30 seconds. 


Chunk size (in KB) 
Provide a chunk size for writing data. 


Test Connection 
After configuring the HTTP Connection Manager, confirm that the connection is viable by clicking Test 
Connection. 


HTTP Connection Manager Editor (Proxy Page) 


Use the Proxy tab of the HTTP Connection Manager Editor dialog box to configure the HTTP Connection 
Manager to use a proxy server. An HTTP connection enables a package to access a Web server by using HTTP to 


send or receive files. 


To learn more about the HTTP connection manager, see HTTP Connection Manager. To learn more about a 
common usage scenario for the HTTP Connection Manager, see Web Service Task. 


Options 
Use proxy 


Specify whether you want the HTTP Connection Manager to connect through a proxy server. 


Proxy URL 
Type the URL for the proxy server. 


Bypass proxy on local 
Specify whether you want the HTTP Connection Manager to bypass the proxy server for local addresses. 


Use credentials 
Specify whether you want the HTTP Connection Manager to use security credentials for the proxy server. 


User name 
If the HTTP Connection Manager uses credentials, you must specify a user name, password, and domain. 


Password 
If the HTTP Connection Manager uses credentials, you must specify a user name, password, and domain. 


Domain 
If the HTTP Connection Manager uses credentials, you must specify a user name, password, and domain. 


Proxy bypass list 
The list of addresses for which you want to bypass the proxy server. 


Add 
Type an address for which you want to bypass the proxy server. 


Remove 
Select an address, and then remove it by clicking Remove. 


See Also 


Web Service Task 
Integration Services (SSIS) Connections 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


An MSMQ connection manager enables a package to connect to a message queue that uses Message Queuing 
(also known as MSMQ). The Message Queue task that Microsoft SQL Server Integration Services includes uses 
an MSMQ connection manager. 


When you add an MSMQ connection manager to a package, Integration Services creates a connection manager 
that will resolve to an MSMQ connection at run time, sets the connection manager properties, and adds the 
connection manager to the Connections collection on the package. The ConnectionManager Type property 
of the connection manager is set to MSMQ. 


You can configure an MSMQ connection manager in the following ways: 
e Provide a connection string. 
e Provide the path of the message queue to connect to. 


The format of the path depends on the type of queue, as shown in the following table. 


QUEUE TYPE SAMPLE PATH 
Public <computer name>\< queue name> 
Private <computer name> \Private$\< queue name> 


You can use a period (.) to represent the local computer. 


Configuration of the MSMQ Connection Manager 


You can set properties through SSIS Designer or programmatically. 


For more information about the properties that you can set in SSIS Designer, see MSMQ Connection Manager 
Editor. 


For information about configuring a connection manager programmatically, see ConnectionManager and 
Adding Connections Programmatically. 


MSMQ Connection Manager Editor 


Use the MSMQ Connection Manager dialog box to specify the path to a Message Queuing (also known as 
MSMQ) message queue. 


To learn more about the MSMQ connection manager, see MSMQ Connection Manager. 





NOTE 


The MSMQ connection manager supports local public and private queues and remote public queues. It does not support 
remote private queues. For a workaround that uses the Script Task, see Sending to a Remote Private Message Queue with 
the Script Task. 








Options 
Name 


Provide a unique name for the MSMQ connection manager in the workflow. The name provided will be 
displayed within SSIS Designer. 


Description 
Describe the connection manager. As a best practice, describe the connection manager in terms of its purpose, to 
make packages self-documenting and easier to maintain. 


Path 
Type the complete path of the message queue. The format of the path depends on the type of queue. 


QUEUE TYPE SAMPLE PATH 

Public <computer name>\< queue name> 

Private <computer name> \Private$\< queue name> 
p q 


You can use "." to represent the local computer. 


Test 


After configuring the MSMQ connection manager, confirm that the connection is viable by clicking Test. 


See Also 


Message Queue Task 
Integration Services (SSIS) Connections 
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Applies to: Q sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


A Multiple Files connection manager enables a package to reference existing files and folders, or to create files 
and folders at run time. 





NOTE 


The built-in tasks and data flow components in Integration Services do not use the Multiple Files connection manager. 
However, you can use this connection manager in the Script task or Script component. For information about how to use 
connection managers in the Script task, see Connecting to Data Sources in the Script Task. For information about how to 
use connection managers in the Script component, see Connecting to Data Sources in the Script Component. 





Usage Types of the Multiple Files Connection Manager 


The FileUsageType property of the Multiple Files connection manager specifies how the connection is used. 
The Multiple Files connection manager can create files, create folders, use existing files, and use existing folders. 


The following table lists the values of FileUsageType. 


VALUE DESCRIPTION 

0 Multiple Files connection manager uses an existing file. 

1 Multiple Files connection manager creates a file. 

2 Multiple Files connection manager uses an existing folder. 
3 Multiple Files connection manager creates a folder. 


Configuration of the Multiple Files Connection Manager 


When you add a Multiple Files connection manager to a package, Integration Services creates a connection 
manager that will resolve to a Multiple Files connection at run time, sets the Multiple Files connection 
properties, and adds the Multiple Files connection to the Connections collection of the package. 


The ConnectionManagerType property of the connection manager is set to MULTIFILE. 

You can configure a Multiple Files connection manager in the following ways: 

e Specify the usage type of files and folders. 

e Specify files and folders. 

e If using multiple files or folders, specify the order in which the files and folders are accessed. 


If the Multiple Files connection manager references multiple files and folders, the paths of the files and folders 
are separated by the pipe (|) character. The ConnectionString property of the connection manager has the 
following format: 





< path>|< path> 


You can also specify multiple files or folders using wildcard characters. For example, to reference all the text files 
on the C drive, the value of the ConnectionString property can be set to C:\* txt. 


You can set properties through SSIS Designer or programmatically. 


For more information about the properties that you can set in SSIS Designer, see Add File Connection Manager 


Dialog Box UI Reference. 


For information about configuring a connection manager programmatically, see ConnectionManager and 


Adding Connections Programmatically. 


Multiple Flat Files Connection Manager 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


A Multiple Flat Files connection manager enables a package to access data in multiple flat files. For example, a 
Flat File source can use a Multiple Flat Files connection manager when the Data Flow task is inside a loop 
container, such as the For Loop container. On each loop of the container, the Flat File source loads data from the 
next file name that the Multiple Flat Files connection manager provides. 


When you add a Multiple Flat Files connection manager to a package, SQL Server Integration Services creates a 
connection manager that will resolve to a Multiple Flat Files connection at run time, sets the properties on the 
Multiple Flat Files connection manager, and adds the Multiple Flat Files connection manager to the 
Connections collection of the package. 


The ConnectionManagerType property of the connection manager is set to MULTIFLATFILE. 
You can configure the Multiple Flat Files connection manager in the following ways: 


e Specify the files, locale, and code page to use. The locale is used to interpret locale-sensitive data such as 
dates, and the code page is used to convert string data to Unicode. 


e Specify the file format. You can use a delimited, fixed width, or ragged right format. 


e Specify a header row, data row, and column delimiters. Column delimiters can be set at the file level and 
overwritten at the column level. 


e Indicate whether the first row in the files contains column names. 
e Specify a text qualifier character. Each column can be configured to recognize a text qualifier. 
e Set properties such as the name, data type, and maximum width on individual columns. 


When the Multiple Flat Files connection manager references multiple files, the paths of the files are separated by 
the pipe (|) character. The ConnectionString property of the connection manager has the following format: 


< path>|< path> 


You can also specify multiple files by using wildcard characters. For example, to reference all the text files on the 
C drive, the value of the ConnectionString property can be set to C:\*.txt. 


If a Multiple Flat Files connection manager references multiple files, all the files must have the same format. 


By default, the Multiple Flat Files connection manager sets the length of string columns to 50 characters. In the 
Multiple Flat Files Connection Manager Editor dialog box, you can evaluate sample data and automatically 
resize the length of these columns to prevent truncation of data or excess column width. Unless you resize the 
column length in a Flat File source or a transformation, the column length remains the same throughout the 
data flow. If these columns map to destination columns that are narrower, warnings appear in the user interface, 
and at run time, errors may occur due to data truncation. You can resize the columns to be compatible with the 
destination columns in the Flat File connection manager, the Flat File source, or a transformation. To modify the 
length of output columns, you set the Length property of the output column on the Input and Output 
Properties tab in the Advanced Editor dialog box. 


If you update column lengths in the Multiple Flat Files connection manager after you have added and configured 
the Flat File source that uses the connection manager, you do not have to manually resize the output columns in 


the Flat File source. When you open the Flat File Source dialog box, the Flat File source provides an option to 


synchronize the column metadata. 


Configuration of the Multiple Flat Files Connection Manager 
You can set properties through SSIS Designer or programmatically. 


For information about configuring a connection manager programmatically, see ConnectionManager and 


Adding Connections Programmatically. 


Multiple Flat Files Connection Manager Editor (General Page) 


Use the General page of the Multiple Flat Files Connection Manager Editor dialog box to select a group 
of files that have the same data format, and to specify their data format. A multiple flat files connection enables a 
package to connect to a group of text files that have the same format. 


To learn more about the Multiple Flat Files connection manager, see Multiple Flat Files Connection Manager. 


Options 

Connection manager name 

Provide a unique name for the Multiple Flat Files connection in the workflow. The name provided will be 
displayed within SSIS Designer. 


Description 
Describe the connection. As a best practice, describe the connection in terms of its purpose, to make packages 


self-documenting and easier to maintain. 


File names 

Type the path and file names to use in the Multiple Flat Files connection. You can specify multiple files by using 
wildcard characters, as in the example "C:\*.txt", or by using the vertical pipe character (|) to separate multiple 
file names. All files must have the same data format. 


Browse 
Browse the file names to use in the Multiple Flat Files connection. You can select multiple files. All files must have 
the same data format. 


Locale 
Specify the location to provide information for ordering and for date and time conversion. 


Unicode 
Indicate whether to use Unicode. Using Unicode precludes specifying a code page. 


Code page 
Specify the code page for non-Unicode text. 


Format 
Indicate whether to use delimited, fixed width, or ragged right formatting. All files must have the same data 


format. 
VALUE DESCRIPTION 
Delimited Columns are separated by delimiters, specified on the 
Columns page. 
Fixed width Columns have a fixed width, specified by dragging marker 


lines on the Columns page. 


VALUE DESCRIPTION 


Ragged right Ragged right files are files in which every column has a fixed 
width, except for the last column, which is delimited by the 
row delimiter, specified on the Columns page. 


Text qualifier 
Specify the text qualifier to use. For example, you can specify to enclose text with quotation marks. 


Header row delimiter 
Select from the list of delimiters for header rows, or enter the delimiter text. 


VALUE DESCRIPTION 

{CR}{LF} The header row is delimited by a carriage return-line feed 
combination. 

{CR} The header row is delimited by a carriage return. 

{LF} The header row is delimited by a line feed. 

Semicolon {;} The header row is delimited by a semicolon. 

Colon {:} The header row is delimited by a colon. 

Comma {,} The header row is delimited by a comma. 

Tab {t} The header row is delimited by a tab. 

Vertical bar {|} The header row is delimited by a vertical bar. 


Header rows to skip 
Specify the number of header rows to skip, if any. 


Column names in the first data row 
Indicate whether to expect or provide column names in the first data row. 


Multiple Flat Files Connection Manager Editor (Columns Page) 


Use the Columns node of the Multiple Flat Files Connection Manager Editor dialog box to specify the row 
and column information, and to preview the first selected file. 


To learn more about the Multiple Flat Files connection manager, see Multiple Flat Files Connection Manager. 


Static Options 


Connection manager name 
Provide a unique name for the Multiple Flat Files connection in the workflow. The name provided will be 
displayed within SSIS Designer. 


Description 
Describe the connection. As a best practice, describe the connection in terms of its purpose, to make packages 
self-documenting and easier to maintain. 


Flat File Format Dynamic Options 


Format = Delimited 


Row delimiter 
Select from the list of available row delimiters, or enter the delimiter text. 


VALUE DESCRIPTION 

{CR}{LF} Rows are delimited by a carriage return-line feed 
combination. 

{CR} Rows are delimited by a carriage return. 

{LF} Rows are delimited by a line feed. 

Semicolon {;} Rows are delimited by a semicolon. 

Colon {:} Rows are delimited by a colon. 

Comma {,} Rows are delimited by a comma. 

Tab {t} Rows are delimited by a tab. 

Vertical bar {|} Rows are delimited by a vertical bar. 


Column delimiter 


Select from the list of available column delimiters, or enter the delimiter text. 


VALUE DESCRIPTION 

{CR}{LF} Columns are delimited by a carriage return-line feed 
combination. 

{CR} Columns are delimited by a carriage return. 

{LF} Columns are delimited by a line feed. 

Semicolon {;} Columns are delimited by a semicolon. 

Colon {:} Columns are delimited by a colon. 

Comma {,} Columns are delimited by a comma. 

Tab {t} Columns are delimited by a tab. 

Vertical bar {|} Columns are delimited by a vertical bar. 


Reset Columns 
Remove all but the original columns by clicking Reset Columns. 


Format = Fixed Width 


Font 
Select the font in which to display the preview data. 


Source data columns 
Adjust the width of the row by sliding the vertical row marker, and adjust the width of the columns by clicking 


the ruler at the top of the preview window 


Row width 
Specify the length of the row before adding delimiters for individual columns. Or, drag the vertical line in the 
preview window to mark the end of the row. The row width value is automatically updated. 


Reset Columns 
Remove all but the original columns by clicking Reset Columns. 


Format = Ragged Right 


NOTE 


Ragged right files are those in which every column has a fixed width, except for the last column. It is delimited by the row 


delimiter. 





Font 
Select the font in which to display the preview data. 


Source data columns 
Adjust the width of the row by sliding the vertical row marker, and adjust the width of the columns by clicking 
the ruler at the top of the preview window 


Row delimiter 
Select from the list of available row delimiters, or enter the delimiter text. 


VALUE DESCRIPTION 

{CR}{LF} Rows are delimited by a carriage return-line feed 
combination. 

{CR} Rows are delimited by a carriage return. 

{LF} Rows are delimited by a line feed. 

Semicolon {;} Rows are delimited by a semicolon. 

Colon {:} Rows are delimited by a colon. 

Comma {,} Rows are delimited by a comma. 

Tab {t} Rows are delimited by a tab. 

Vertical bar {|} Rows are delimited by a vertical bar. 


Reset Columns 
Remove all but the original columns by clicking Reset Columns. 


Multiple Flat Files Connection Manager Editor (Advanced Page) 


Use the Advanced page of the Multiple Flat Files Connection ManagerEditor dialog box to set properties 
such as data type and delimiters of each column in the text files to which the flat file connection manager 


connects. 


By default, the length of string columns is 50 characters. You can evaluate sample data and automatically resize 
the length of these columns to prevent truncation of data or excess column width. You can also update other 
metadata to enable compatibility with destination columns. For example, you might change the data type of a 
column that contains only integer data to a numeric data type, such as DT_I2. 


To learn more about the Multiple Flat Files connection manager, see Multiple Flat Files Connection Manager. 


Options 

Connection manager name 

Provide a unique name for the Multiple Flat Files connection manager in the workflow. The name provided will 
be displayed within the Connection Managers area of SSIS Designer. 


Description 
Describe the connection manager. As a best practice, describe the connection manager in terms of its purpose, to 
make packages self-documenting and easier to maintain. 


Configure the properties of each column 
Select a column in the left pane to view its properties in the right pane. See the following table for a description 
of data type properties. Some of the properties listed are configurable only for some flat file formats. 


PROPERTY DESCRIPTION 


ColumnType Denotes whether the column is delimited, fixed width, or 
ragged right. This property is read-only. Ragged right files 
are files in which every column has a fixed width, except for 
the last column, which is terminated by the row delimiter. 


OutputColumnWidth Specify a value to be stored as a count of bytes; for Unicode 
files, this will display as a count of characters. In the Data 
Flow task, this value is used to set the output column width 
for the Flat File source. 


Note: In the object model, the name of this property is 
MaximumWidth. 


DataType Select from the list of available data types. For more 
information, see Integration Services Data Types. 


Text Qualified Indicate whether text data is qualified using a text qualifier 
character: 


True: Text data in the flat file is qualified. 


False: Text data in the flat file is not qualified. 


Name Provide a column name. The default is a numbered list of 
columns; however, you can choose any unique, descriptive 
name. 


DataScale Specify the scale of numeric data. Scale refers to the number 
of decimal places. For more information, see Integration 
Services Data Types. 


PROPERTY 


ColumnDelimiter 


DataPrecision 


InputColumnWidth 


New 


DESCRIPTION 


Select from the list of available column delimiters. Choose 
delimiters that are not likely to occur in the text. This value is 
ignored for fixed-width columns. 


{CR}{LF} - columns are delimited by a carriage return-line 
feed combination 


{CR} - columns are delimited by a carriage return 

{LF} - columns are delimited by a line feed 
Semicolon {;} - columns are delimited by a semicolon 
Colon {:} - columns are delimited by a colon 

Comma {,} - columns are delimited by a comma 

Tab {t} - columns are delimited by a tab 


Vertical bar {|} - columns are delimited by a vertical bar 


Specify the precision of numeric data. Precision refers to the 
number of digits. For more information, see Integration 
Services Data Types. 


Specify a value to be stored as a count of bytes; for Unicode 
files, this will display as a count of characters. This value is 
ignored for delimited columns. 


Note In the object model, the name of this property is 
ColumnWidth. 


Add a new column by clicking New. By default, the New button adds a new column at the end of the list. The 


button also has the following options, available in the dropdown list. 


VALUE 


Add Column 


Insert Before 


Insert After 


Delete 
Select a column, and then remove it by clicking Delete. 


Suggest Types 


DESCRIPTION 


Add a new column at the end of the list. 


Insert a new column before the selected column. 


Insert a new column after the selected column. 


Use the Suggest Column Types dialog box to evaluate sample data in the first selected file and to obtain 


suggestions for the data type and length of each column. For more information, see Suggest Column Types 


Dialog Box UI Reference. 


Multiple Flat Files Connection Manager Editor (Preview Page) 


Use the Preview page of the Multiple Flat Files ConnectionManager Editor dialog box to view the 


contents of the first selected source file divided into columns as you have defined them. 


To learn more about the Multiple Flat Files connection manager, see Multiple Flat Files Connection Manager. 


Options 
Connection manager name 


Provide a unique name for the Multiple Flat Files connection in the workflow. The name provided will be 
displayed within the Connection Managers area of SSIS Designer. 


Description 
Describe the connection. As a best practice, describe the connection in terms of its purpose, to make packages 
self-documenting and easier to maintain. 


Data rows to skip 
Specify how many rows to skip at the beginning of the flat file. 


Preview rows 


View sample data in the first selected flat file, divided into columns and rows by using the options selected. 


See Also 


Flat File Source 
Flat File Destination 
Integration Services (SSIS) Connections 
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Connect to an OData data source with an OData connection manager. An OData Source component uses an 
OData connection manager to connect to an OData data source and consume data from the service. For more 
info, see OData Source. 


Adding an OData Connection Manager to an SSIS Package 
You can add a new OData connection manager to an SSIS package in three ways: 
e Click the New... button in the OData Source Editor 


e Right-click the Connection Managers folder in Solution Explorer, and then click New Connection 
Manager. Select ODATA for Connection manager type. 


e Right-click in the Connection Managers pane at the bottom of the package designer, and then select 
New Connection. Select ODATA for Connection manager type. 


Connection Manager Authentication 

The OData connection manager supports five modes of authentication. 
e Windows Authentication 

e Basic Authentication (with username and password) 

e Microsoft Dynamics AX Online (with username and password) 

e Microsoft Dynamics CRM Online (with username and password) 

e Microsoft Online Services (with username and password) 

For anonymous access, select the Windows Authentication option. 


To connect to Microsoft Dynamics AX Online or Microsoft Dynamics CRM online, you can't use the Microsoft 
Online Services authentication option. You also can't use any option that's configured for multi-factor 
authentication. Currently Modern authentication is not supported. 


Specifying and Securing Credentials 


If the OData service requires basic authentication, you can specify a username and password in the OData 
Connection Manager Editor. The values you enter in the editor are persisted in the package. The password value 
is encrypted according to the package protection level. 


There are several ways to parameterize the username and password values or to store them outside the 
package. For example, you can use parameters, or set the connection manager properties directly when you run 
the package from SQL Server Management Studio. 


OData Connection Manager Properties 


The following list describes the properties of the OData connection manager. 


PROPERTY DEFAULT VALUE DESCRIPTION 


Keep Alive False Value of the “Keep-Alive” header when 
sending web request. 


Max Received Message Size A4TB The max received message size in byte 
when sending web request. 


Retry Count 5 Retry count when sending web 
request. 
Retry Sleep 100 Sleep time in millisecond for retry 


when sending web request. 


Time Out 600 Timeout in second when sending web 
request. 

Url URL to the service document. 

UserName User name to use for authentication, if 
required. 

Password Password to use for authentication, if 
required. 

ConnectionString Includes other properties of the 


connection manager. 


OData Connection Manager Editor 


Use the OData Connection Manager Editor dialog box to add a connection or edit an existing connection to 
an OData data source. 


Options 
Connection manager name 
Name of the connection manager. 


Service document location 
URL for the OData service. For example: https://services.odata.org/V3/Northwind/Northwind.svc/. 


Authentication 
Select one of the following options: 


e Windows Authentication. For anonymous access, select this option. 
e Basic Authentication 

e Microsoft Dynamics AX Online for Dynamics AX Online 

e Microsoft Dynamics CRM Online for Dynamics CRM Online 


e Microsoft Online Services for Microsoft Online Services 
If you select an option other than Windows Authentication, enter the user name and password. 


To connect to Microsoft Dynamics AX Online or Microsoft Dynamics CRM online, you can't use the Microsoft 
Online Services authentication option. You also can't use any option that's configured for multi-factor 
authentication. 


Test Connection 


Click this button to test the connection to the OData source. 


ODBC Connection Manager 
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An ODBC connection manager enables a package to connect to a variety of database management systems 
using the Open Database Connectivity specification (ODBC). 


When you add an ODBC connection to a package and set the connection manager properties, SQL Server 
Integration Services creates a connection manager and adds the connection manager to the Connections 
collection of the package. At run time the connection manager is resolved as a physical ODBC connection. 


The ConnectionManagerType property of the connection manager is set to ODBC. 
You can configure the ODBC connection manager in the following ways: 

e Provide a connection string that references a user or system data source name. 

e Specify the server to connect to. 


e Indicate whether the connection is retained at run time. 


Configuration of the ODBC Connection Manager 
You can set properties through SSIS Designer or programmatically. 
For more information about the properties that you can set in SSIS Designer, click one of the following topic: 


e ODBC Connection Manager UI Reference 


For information about configuring a connection manager programmatically, see ConnectionManager and 
Adding Connections Programmatically. 


ODBC Connection Manager UI Reference 
Use the Configure ODBC Connection Manager dialog box to add a connection to an ODBC data source. 
To learn more about the ODBC connection manager, see ODBC Connection Manager. 


Options 
Data connections 
Select an existing ODBC connection manager from the list. 


Data connection properties 
View properties and values for the selected ODBC connection manager. 


New 
Create an ODBC connection manager by using the Connection Manager dialog box. This dialog box also lets 
you create a new ODBC data source if it is required. 


Delete 
Select a connection, and then delete it by using the Delete button. 


See Also 


Integration Services (SSIS) Connections 
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An OLEDB connection manager enables a package to connect to a data source by using an OLEDB provider. For 
example, an OLEDB connection manager that connects to SQL Server can use the Microsoft OLEDB Provider for 
SQL Server. 


NOTE 


The SQL Server Native Client 11.0 OLEDB provider doesn't support the new connection string key words 
(MultiSubnetFailover=True) for multi-subnet failover clustering. For more information, see the SQL Server Release Notes. 








NOTE 


If the data source is Microsoft Office Excel 2007 or Microsoft Office Access 2007, the data source requires a different data 
provider than earlier versions of Excel or Access. For more information, see Connect to an Excel Workbook and Connect to 


an Access Database. 





Several SQL Server Integration Services tasks and data flow components use an OLEDB connection manager. 
For example, the OLEDB source and OLEDB destination use this connection manager to extract and load data. 
The Execute SQL task can use this connection manager to connect to a SQL Server database to run queries. 


You can also use the OLEDB connection manager to access OLEDB data sources in custom tasks written in 
unmanaged code that uses a language such as C++. 


When you add an OLEDB connection manager to a package, Integration Services creates a connection manager 
that resolves to an OLEDB connection at runtime, sets the connection manager properties, and adds the 
connection manager to the Connections collection on the package. 


The ConnectionManagerType property of the connection manager is set to OLEDB . 
Configure the OLEDB connection manager in the following ways: 


e Provide a specific connection string configured to meet the requirements of the selected provider. 


Depending on the provider, include the name of the data source to connect to. 


Provide security credentials as appropriate for the selected provider. 


Indicate whether the connection created from the connection manager is retained at runtime. 


Log calls and troubleshoot connections 


You can log the calls that the OLEDB connection manager makes to external data providers. You can then 
troubleshoot the connections that the OLEDB connection manager makes to external data sources. To log the 
calls that the OLEDB connection manager makes to external data providers, enable package logging, and select 
the Diagnostic event at the package level. For more information, see Troubleshooting Tools for Package 
Execution. 


Configure the OLEDB connection manager 





You can set properties through SSIS Designer, or programmatically. For more information about the properties 
that you can set in SSIS Designer, see Configure OLEDB Connection Manager. For information about configuring 
a connection manager programmatically, see the documentation for 
T:Microsoft.SqlServer.Dts.Runtime.ConnectionManager class in the Developer Guide. 


Configure OLEDB connection manager 


Use the Configure OLEDB Connection Manager dialog box to add a connection to a data source. This 
connection can be new, or a copy of an existing connection. 





NOTE 
If the data source is Microsoft Office Excel 2007, the data source requires a different connection manager than earlier 


versions of Excel. For more information, see Connect to an Excel Workbook. 


If the data source is Microsoft Office Access 2007, the data source requires a different OLEDB provider than earlier 


versions of Access. For more information, see Connect to an Access Database. 





To learn more about the OLEDB connection manager, see OLEDB Connection Manager. 


Options 
Data connections 
Select an existing OLEDB data connection from the list. 


Data connection properties 
View properties and values for the selected OLEDB data connection. 


New 
Create an OLEDB data connection by using the Connection Manager dialog box. 


Delete 
Select a data connection, and then delete it by selecting Delete. 


Managed identities for Azure resources authentication 

When running SSIS packages on Azure-SSIS integration runtime (IR) in Azure Data Factory (ADF), you can use 
Azure Active Directory (AAD) authentication with the specified system/user-assigned managed identity for your 
ADF to access Azure SQL Database server/Managed Instance. Your Azure-SSIS IR can access and copy data from 
or to your database by using this managed identity. 








NOTE 
When you use AAD authentication to access Azure SQL Database server/Managed Instance, you might encounter a 
problem related to package execution failure or unexpected behavior change. For more information, see AAD features and 


limitations. 





To use AAD authentication with the specified system/user-assigned managed identity for your ADF to access 
Azure SQL Database server, follow these steps: 


1. Provision an AAD administrator for your Azure SQL Database server in Azure portal, if you haven't 
already done so. The AAD administrator can be an AAD user or group. If you grant the group with 
specified system/user-assigned managed identity for your ADF an admin role, skip step 2 - 3. The 
administrator will have full access to your Azure SQL Database server. 


2. Create a contained database user to represent the specified system/user-assigned managed identity for 
your ADF. Connect to the database from or to which you want to copy data using SQL Server 
Management Studio (SSMS) with an AAD user that has at least ALTER ANY USER permission. Run the 
following T-SQL statement: 





CREATE USER [your managed identity name] FROM EXTERNAL PROVIDER; 


If you use the system managed identity for your ADF, then your managed identity name should be your 
ADF name. If you use a user-assigned managed identity for your ADF, then your managed identity name 
should be the specified user-assigned managed identity name. 


. Grant the specified system/user-assigned managed identity for your ADF the required permissions, as 


you normally do for SQL users. Refer to Database-level roles for appropriate roles. Run the following T- 
SQL statement. For more options, see this article. 


EXEC sp_addrolemember [role name], [your managed identity name]; 


To use AAD authentication with the specified system/user-assigned managed identity for your ADF to access 


Azure SQL Managed Instance, follow these steps: 


A. 


Provision an AAD administrator for your Azure SQL Managed Instance in Azure portal, if you haven't 
already done so. The AAD administrator can be an AAD user or group. If you grant the group with 
specified system/user-assigned managed identity for your ADF an admin role, skip step 2 - 4. The 
administrator will have full access to your Azure SQL Managed Instance. 


. Create a login assigned to the specified system/user-assigned managed identity for your ADF. On SSMS, 


connect to your Azure SQL Managed Instance using SQL Server account that is asysadmin. In master 
database, run the following T-SQL statement: 


CREATE LOGIN [your managed identity name] FROM EXTERNAL PROVIDER; 


If you use the system managed identity for your ADF, then your managed identity name should be your 
ADF name. If you use a user-assigned managed identity for your ADF, then your managed identity name 
should be the specified user-assigned managed identity name. 


. Create a contained database user representing the specified system/user-assigned managed identity for 


your ADF. Connect to the database from or to which you want to copy data using SSMS and run the 
following T-SQL statement: 


CREATE USER [your managed identity name] FROM EXTERNAL PROVIDER; 


. Grant the specified system/user-assigned managed identity for your ADF the required permissions, as 


you normally do for SQL users. Run the following T-SQL statement. For more options, see this article. 


ALTER ROLE [role name e.g., db_owner] ADD MEMBER [your managed identity name]; 


You can then configure the OLEDB provider on your OLEDB connection manager. Here are the options to do this: 


e Configure at design time. In SSIS Designer, double-click on your OLEDB connection manager to open 


the Connection Manager window. In the Provider drop-down list, select Microsoft OLEDB Driver 
for SQL Server. 





NOTE 


Other providers in the drop-down list might not support AAD authentication with the specified system/user- 
assigned managed identity for your ADF. 








e Configure at run time. When you run your package via SSMS or Execute SSIS Package activity in ADF 
pipeline, find the connection manager property ConnectionString for OLEDB connection manager. 


Update the connection property Provider to MSOLEDBSQL (that is Microsoft OLEDB Driver for SQL 
Server). 


Data Source=serverName; Initial Catalog=databaseName;Provider=MSOLEDBSQL;... 


Finally, you can configure AAD authentication with the specified system/user-assigned managed identity for 
your ADF on the OLEDB connection manager. Here are the options to do this: 


e Configure at design time. In SSIS Designer, right-click on your OLEDB connection manager, and select 
Properties. Update the property ConnectUsingManagedIdentity to True. 





NOTE 


Currently, the connection manager property ConnectUsingManagedIdentity doesn't take effect (indicating that 


AAD authentication with the specified system/user-assigned managed identity for your ADF doesn't work) when 
you run your package in SSIS Designer or on SQL Server. 








e Configure at run time. When you run your package via SSMS or Execute SSIS Package activity in ADF 
pipeline, find the OLEDB connection manager and update its property ConnectUsingManagedIdentity to 


True . 





NOTE 


On Azure-SSIS IR, all other authentication methods (for example, integrated security and password) preconfigured 
on your OLEDB connection manager are overridden when using AAD authentication with the specified 
system/user-assigned managed identity for your ADF. 








To configure AAD authentication with the specified system/user-assigned managed identity for your ADF on 
your existing packages, the preferred way is to rebuild your SSIS project with the latest SSIS Designer at least 
once. Redeploy your SSIS project to run on Azure-SSIS IR, so that the new connection manager property 
ConnectUsingManagedIdentity is automatically added to all OLEDB connection managers in your project. The 


alternative way is to directly use property overrides with the property path \Package.Connections[{the name of 
your connection manager}].Proper ties[ConnectUsingManagedldentity] assigned to True at run time. 


See also 


e OLEDB Source 
e OLEDB Destination 


e Integration Services (SSIS) Connections 
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The SAP BW connection manager is the connection manager component of the Microsoft Connector 1.1 for SAP 
BW. Thus, the SAP BW connection manager provides the connectivity to an SAP Netweaver BW version 7 system 
that the source and destination components of the Microsoft Connector 1.1 for SAP BW need. (The SAP BW 
source and destination that are part of the Microsoft Connector 1.1 for SAP BW package are the only Integration 
Services components that use the SAP BW connection manager.) 


IMPORTANT 


The documentation for the Microsoft Connector 1.1 for SAP BW assumes familiarity with the SAP Netweaver BW 
environment. For more information about SAP Netweaver BW, or for information about how to configure SAP Netweaver 


BW objects and processes, see your SAP documentation. 





When you add an SAP BW connection manager to a package, the ConnectionManagerType property of the 
connection manager is set to SAPBI. 


Configuring the SAP BW Connection Manager 


You can configure the SAP BW connection manager in the following ways: 
e Provide the client, user name, password, and language for the connection. 
e@ Choose whether to connect to a single application server or to a group of load-balanced servers. 


e Provide the host and system number for a single application server, or provide the message server, 
group, and SID for a group of load-balanced servers. 


e Enable custom logging of RFC function calls for the components of the Microsoft Connector 1.1 for SAP 
BW. (This logging is separate from the optional logging that you can enable on Integration Services 
packages.) To enable logging of RFC function calls, you specify a directory in which to store the log files 
that are created before and after each RFC function call. (This logging feature creates many log files in 
XML format. As these log files also contain all the rows of data that are transferred, these log files may 
consume a large amount of disk space.) If you do not select a log directory, logging is not enabled. 





IMPORTANT 


If the data that is transferred contains sensitive information, the log files will also contain that sensitive 


information. 








e Use the values that you have entered to test the connection. 


If you do not know all the values that are required to configure the connection manager, you might have to ask 
your SAP administrator. 


For a walkthrough that demonstrates how to configure and use the SAP BW connection manager, source, and 
destination, see the white paper, Using SQL Server 2008 Integration Services with SAP BI 7.0. This white paper 
also shows how to configure the required objects in SAP BW. 





Using the SSIS Designer to Configure the Source 


For more information about the properties of the SAP BW connection manager that you can set in SSIS 
Designer, click the following topic: 


e SAP BW Connection Manager Editor 


SAP BW Connection Manager Editor 


Use the SAP BW Connection Manager Editor to specify the properties to use to connect to an SAP 
Netweaver BW version 7 system. 


The SAP BW connection manager provides connectivity to an SAP Netweaver BW 7 system for use by the SAP 
BW source or destination. To learn more about the SAP BW connection manager of the Microsoft Connector 1.1 
for SAP BW, see SAP BW Connection Manager. 





IMPORTANT 
The documentation for the Microsoft Connector 1.1 for SAP BW assumes familiarity with the SAP Netweaver BW 
environment. For more information about SAP Netweaver BW, or for information about how to configure SAP Netweaver 


BW objects and processes, see your SAP documentation. 











To open the SAP BW Connection Manager Editor 


1. In SQL Server Data Tools (SSDT), open the Integration Services package that contains the SAP BW 


connection manager. 
2. In the Connection Managers area on the Control Flow tab, do one of the following steps: 
e Double-click the SAP BW connection manager. 
-or- 
e Right-click the SAP BW connection manager, and then select Edit. 


Options 


NOTE 


If you do not know all the values that are required to configure the connection manager, you might have to ask your SAP 


administrator. 





Client 
Specify the client number of the system. 


Language 
Specify the language that the system uses. For example, specify EN for English. 


User name 


Specify the user name that will be used to connect to the system. 


Password 
Specify the password that will be used with the user name. 


Use single application server 
Connect to a single application server. 


To connect to a group of load-balanced servers, use the Use load balancing option instead. 


Host 
If connecting to a single application server, specify the host name. 





NOTE 


This option is only available if you have selected the Use single application server option. 





System number 
If connecting to a single application server, specify the system number. 





NOTE 


This option is only available if you have selected the Use single application server option. 





Use load balancing 
Connect to a group of load-balanced servers. 


To connect to a single application server, use the Use single application server option instead. 


Message server 
If connecting to a group of load-balanced servers, specify the name of the message server. 





NOTE 


This option is only available if you have selected the Use load balancing option. 





Group 
If connecting to a group of load-balanced servers, specify the name of the server group name. 





NOTE 


This option is only available if you have selected the Use load balancing option. 





SID 
If connecting to a group of load-balanced servers, specify the System ID for the connection. 





NOTE 


This option is only available if you have selected the Use load balancing option. 





Log directory 


Enable logging for the components of the Microsoft Connector 1.1 for SAP BW. 


To enable logging, specify a directory for the log files that are created before and after each RFC function call. 
(This logging feature creates many log files in XML format. As these log files also contain all the rows of data 


that are transferred, these log files may consume a large amount of disk space.) 





IMPORTANT 


If the data that is transferred contains sensitive information, the log files will also contain that sensitive information. 





To specify the log directory, you can either enter the directory path manually, or click Browse and browse to the 


log directory. 
If you do not select a log directory, logging is not enabled. 


Browse 
Browse to select a folder for the log directory. 


Test Connection 
Test the connection using the values that you have provided. After clicking Test Connection, a message box 
appears and indicates whether the connection succeeded or failed. 


See Also 


Microsoft Connector for SAP BW Components 
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An SMTP connection manager enables a package to connect to a Simple Mail Transfer Protocol (SMTP) server. 
The Send Mail task that Microsoft SQL Server Integration Services includes uses an SMTP connection manager. 


When using Microsoft Exchange as the SMTP server, you may need to configure the SMTP connection manager 
to use Windows Authentication. Exchange servers may be configured to not allow unauthenticated SMTP 
connections. 


Configuration the SMTP Connection Manager 


When you add an SMTP connection manager to a package, Integration Services creates a connection manager 
that will resolve to an SMTP connection at run time, sets the connection manager properties, and adds the 
connection manager to the Connections collection on the package. The ConnectionManager Type property 
of the connection manager is set to SMTP. 


You can configure an SMTP connection manager in the following ways: 
e Provide a connection string. 
e@ Specify the name of an SMTP server. 


e Specify the authentication method to use. 





IMPORTANT 


The SMTP connection manager supports only anonymous authentication and Windows Authentication. It does 


not support basic authentication. 








e@ Specify whether to encrypt communication using Transport Layer Security (TLS), previously known as 
Secure Sockets Layer (SSL), when sending e-mail messages. 


You can set properties through SSIS Designer or programmatically. 


For more information about the properties that you can set in SSIS Designer, see SMTP Connection Manager 
Editor. 


For information about configuring a connection manager programmatically, see ConnectionManager and 
Adding Connections Programmatically. 


SMTP Connection Manager Editor 


Use the SMTP Connection Manager Editor dialog box to specify a Simple Mail Transfer Protocol (SMTP) 
server. 


To learn more about the SMTP connection manager, see SMTP Connection Manager. 


Options 
Name 


Provide a unique name for the connection manager. 


Description 
Describe the connection manager. As a best practice, describe the connection manager in terms of its purpose, to 
make packages self-documenting and easier to maintain. 


SMTP server 
Provide the name of the SMTP server. 


Use Windows Authentication 
Select to send mail using an SMTP server that uses Windows Authentication to authenticate access to the server. 


IMPORTANT 


The SMTP connection manager supports only anonymous authentication and Windows Authentication. It does not 
support basic authentication. 


NOTE 


When using Microsoft Exchange as the SMTP server, you may need to set Use Windows Authentication to True. 
Exchange servers may be configured to disallow unauthenticated SMTP connections. 











Enable Secure Sockets Layer (SSL) 
Select to encrypt communication using TLS/SSL when sending e-mail messages. 


SMO Connection Manager 
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An SMO connection manager enables a package to connect to a SQL Management Object (SMO) server. The 
transfer tasks that SQL Server Integration Services includes use an SMO connection manager. For example, the 
Transfer Logins task that transfers SQL Server logins uses an SMO connection manager. 


When you add an SMO connection manager to a package, Integration Services creates a connection manager 
that will resolve to an SMO connection at run time, sets the connection manager properties, and adds the 
connection manager to the Connections collection on the package. The ConnectionManager Type property 
of the connection manager is set to SMOServer. 


You can configure an SMO connection manager in the following ways: 
e Specify the name of a server on which SQL Server is installed. 


e Select the authentication mode for connecting to the server. 


Configuration of the SMO Connection Manager 


You can set properties through SSIS Designer or programmatically. 


For more information about the properties that you can set in SSIS Designer, see SMO Connection Manager 
Editor. 


For information about configuring a connection manager programmatically, see ConnectionManager and 
Adding Connections Programmatically. 


SMO Connection Manager Editor 


Use the SMO Connection Manager Editor to configure a SQL Server connection for use by the various tasks 
that transfer SQL Server objects. 


To learn more about the SMO connection manager, see SMO Connection Manager. 


Options 
Server name 


Type the name of the SQL Server instance or select the server name from the list. 


Refresh 
Refresh the list of available SQL Server instances that can be detected on the network. 


Use Windows Authentication 
Use Windows Authentication to connect to the selected SQL Server instance. 


Use SQL Server Authentication 
Use SQL Server Authentication to connect to the selected SQL Server instance. 


User name 
If you have selected SQL Server authentication, enter the SQL Server user name. 


Password 
If you have selected SQL Server authentication, enter the password. 


Test Connection 


Test the connection as configured. 


See Also 


Integration Services (SSIS) Connections 
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A SQL Server Compact connection manager enables a package to connect to a SQL Server Compact database. 
The SQL Server Compact destination that Microsoft SQL Server Integration Services includes uses this 
connection manager to load data into a table in a SQL Server Compact database. 


NOTE 


On a 64-bit computer, you must run packages that connect to SQL Server Compact data sources in 32-bit mode. The 
SQL Server Compact provider that Integration Services uses to connect to SQL Server Compact data sources is available 
only in a 32-bit version. 





Configuration the SQL Server Compact Edition Connection Manager 


When you add a SQL Server Compact connection manager to a package, Integration Services creates a 
connection manager that will resolve to a SQL Server Compact connection at run time, sets the connection 
manager properties, and adds the connection manager to the Connections collection on the package. 


The ConnectionManagerType property of the connection manager is set to SQLMOBILE. 

You can configure the SQL Server Compact connection manager in the following ways: 

e Provide a connection string that specifies the location of the SQL Server Compact database. 

e Provide a password for a password-protected database. 

@ Specify the server on which the database is stored. 

e Indicate whether the connection that is created from the connection manager is retained at run time. 
You can set properties through SSIS Designer or programmatically. 


For information about configuring a connection manager programmatically, see ConnectionManager and 
Adding Connections Programmatically. 


SQL Server Compact Edition Connection Manager Editor (Connection 
Page) 
Use the SQL Server Compact Edition Connection Manager dialog box to specify properties for connecting 


to a SQL Server Compact database. 


To learn more about the SQL Server Compact Edition connection manager, see SQL Server Compact Edition 
Connection Manager. 


Options 
Enter the database file name and path 
Enter the path and filename for the SQL Server Compact database. 


Browse 
Locate the desired SQL Server Compact database file by using the Select SQL Server Compact Edition 





database dialog box. 


Enter the database password 
Enter the password for the SQL Server Compact database. 


SQL Server Compact Edition Connection Manager Editor (All Page) 


Use the SQL Server Compact Edition Connection Manager dialog box to specify properties for connecting 
to a SQL Server Compact database. 


To learn more about the SQL Server Compact Edition connection manager, see SQL Server Compact Edition 
Connection Manager. 


Options 

AutoShrink Threshold 

Specify the amount of free space, as a percentage, that is allowed in the SQL Server Compact database before 
the autoshrink process runs. 


Default Lock Escalation 
Specify the number of database locks that the SQL Server Compact database acquires before it tries to escalate 
locks. 


Default Lock Timeout 
Specify the default interval, in milliseconds, that a transaction will wait for a lock. 


Flush Interval 
Specify the interval, in seconds, between committed transactions to flush data to disk. 


Locale Identifier 
Specify the Locale ID (LCID) of the SQL Server Compact database. 


Max Buffer Size 
Specify the maximum amount of memory, in kilobytes, that SQL Server Compact uses before flushing data to 
disk. 


Max Database Size 
Specify the maximum size, in megabytes, of the SQL Server Compact database. 


Mode 
Specify the file mode in which to open the SQL Server Compact database. The default value for this property is 
Read Write. 


The Mode option has four values, as described in the following table. 


VALUE DESCRIPTION 

Read Only Specifies read-only access to the database. 

Read Write Specifies read/write permission to the database. 

Exclusive Specifies exclusive access to the database. 

Shared Read Specifies that other users can read from the database at the 
same time. 


Persist Security Info 
Specify whether security information is returned as part of the connection string. The default value for this 


option is False. 


Temp File Directory 
Specify the location of the SQL Server Compact temporary database file. 


Data Source 
Specify the name of the SQL Server Compact database. 


Password 
Enter the password for the SQL Server Compact database. 
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A WMI connection manager enables a package to use Windows Management Instrumentation (WMI) to manage 
information in an enterprise environment. The Web Service task that Microsoft SQL Server Integration Services 
includes uses a WMI connection manager. 


When you add a WMI connection manager to a package, Integration Services creates a connection manager that 
will resolve to a WMI connection at run time, sets the connection manager properties, and adds the connection 
manager to the Connections collection on the package. The ConnectionManagerType property of the 
connection manager is set to WMI. 


Configuration of the WMI Connection Manager 

You can configure a WMI connection manager in the following ways: 

e Specify the name of a server. 

e Specify a namespace on the server. 

e Select the authentication mode for connecting to the server. 

You can set properties through SSIS Designer or programmatically. 

For information about the properties that you can set in SSIS Designer, see WMI Connection Manager Editor. 


For information about configuring a connection manager programmatically, see ConnectionManager and 
Adding Connections Programmatically. 


WMI Connection Manager Editor 


Use the WMI Connection Manager dialog box to specify a Microsoft Windows Management Instrumentation 
(WMI) connection to a server. 


To learn more about the WMI connection manager, see WMI Connection Manager. 


Options 
Name 


Provide a unique name for the connection manager. 


Description 
Describe the connection manager. As a best practice, describe the connection manager in terms of its purpose, to 
make packages self-documenting and easier to maintain. 


Server name 


Provide the name of the server to which you want to make the WMI connection. 


Namespace 
Specify the WMI namespace. 


Use Windows authentication 
Select to use Windows Authentication. If you use Windows Authentication, you do not need to provide a user 
name or password for the connection. 


User name 
If you do not use Windows Authentication, you must provide a user name for the connection. 


Password 
If you do not use Windows Authentication, you must provide the password for the connection. 


Test 
Test the connection manager settings. 


See Also 


Web Service Task 
Integration Services (SSIS) Connections 
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A package consists of a control flow and, optionally, one or more data flows. SQL Server Integration Services 
provides three different types of control flow elements: containers that provide structures in packages, tasks that 
provide functionality, and precedence constraints that connect the executables, containers, and tasks into an 
ordered control flow. 


For more information, see Precedence Constraints, Integration Services Containers, and Integration Services 
Tasks. 


The following diagram shows a control flow that has one container and six tasks. Five of the tasks are defined at 
the package level, and one task is defined at the container level. The task is inside a container. 
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The Integration Services architecture supports the nesting of containers, and a control flow can include multiple 
levels of nested containers. For example, a package could contain a container such as a Foreach Loop container, 
which in turn could contain another Foreach Loop container and so on. 


Event handlers also have control flows, which are built using the same kinds of control flow elements. 


Control Flow Implementation 


You create the control flow in a package by using the Control Flow tab in SSIS Designer. When the Control 
Flow tab is active, the Toolbox lists the tasks and containers that you can add to the control flow. 


The following diagram shows the control flow of a simple package in the control flow designer. The control flow 
shown in the diagram is made up of three package-level tasks and one package-level container that contains 
three tasks. The tasks and container are connected by using precedence constraints. 
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Creating a control flow includes the following tasks: 
e Adding containers that implement repeating workflows in a package or divide a control flow into subsets. 


e Adding tasks that support data flow, prepare data, perform workflow and business intelligence functions, 
and implement script. 


Integration Services includes a variety of tasks that you can use to create control flow that meets the 
business requirements of the package. If the package has to work with data, the control flow must include 
at least one Data Flow task. For example, a package might have to extract data, aggregate data values, 
and then write the results to a data source. For more information, see Integration Services Tasks and Add 
or Delete a Task or a Container in a Control Flow. 


e Connecting containers and tasks into an ordered control flow by using precedence constraints. 


After you add a task or container to the design surface of the Control Flow tab, SSIS Designer 
automatically adds a connector to the item. If a package includes two or more items, tasks or containers, 
you can join them into a control flow by dragging their connectors from one item to another. 


The connector between two items represents a precedence constraint. A precedence constraint defines 
the relationship between the two connected items. It specifies the order in which tasks and containers are 
executed at run time and the conditions under which tasks and containers run. For example, a precedence 
constraint can specify that a task must succeed for the next task in the control flow to run. For more 
information, see Precedence Constraints. 


e Adding connection managers. 


Many tasks require a connection to a data source, and you have to add the connection managers that the 


task requires to the package. Depending on the enumerator type it uses, the Foreach Loop container may 
also require a connection manager. You can add the connection managers as you construct the control 
flow item by item or before you start to construct the control flow. For more information, see Integration 
Services (SSIS) Connections and Create Connection Managers. 


SSIS Designer also includes many design-time features that you can use to manage the design surface and 
make the control flow self-documenting. 


Related Tasks 
e Add or Delete a Task or a Container in a Control Flow 
e Set the Properties of a Task or Container 


e Group or Ungroup Components 
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When you are working in the control flow designer, the Toolbox in SSIS Designer lists the tasks that Integration 
Services provides for building control flow in a package. For more information about the Toolbox, see SSIS 
Toolbox. 


A package can include multiple instances of the same task. Each instance of a task is uniquely identified in the 
package, and you can configure each instance differently. 


If you delete a task, the precedence constraints that connect the task to other tasks and containers in the control 
flow are also deleted. 


The following procedures describe how to add or delete a task or container in the control flow of a package. 


Add a task or a container to a control flow 


1. In SQL Server Data Tools (SSDT), open the Integration Services project that contains the package you 
want. 


2. In Solution Explorer, double-click the package to open it. 

3. Click the Control Flow tab. 

4. To open the Toolbox, click Toolbox on the View menu. 

5. Expand Control Flow Items and Maintenance Tasks. 

6. Drag tasks and containers from the Toolbox to the design surface of the Control Flow tab. 


7. Connect a task or container within the package control flow by dragging its connector to another 
component in the control flow. 


8. To save the updated package, click Save Selected Items on the File menu. 


Delete a task or a container from a control flow 


1. In SQL Server Data Tools (SSDT), open the Integration Services project that contains the package you 
want. 


2. In Solution Explorer, double-click the package to open it. Do one of the following: 


e Click the Control Flow tab, right-click the task or container that you want to remove, and then 
click Delete. 


e@ Open Package Explorer. From the Executables folder, right-click the task or container that you 
want to remove, and then click Delete. 


3. To save the updated package, click Save Selected Items on the File menu. 


Set the properties of a task or container 


You can set most properties of tasks and containers by using the Properties window. The exceptions are 
properties of task collections and properties that are too complex to set by using the Properties window. For 
example, you cannot configure the enumerator that the Foreach Loop container uses in the Properties window. 
You must use a task or container editor to set these complex properties. Most task and container editors have 
multiple nodes and each node contains related properties. The name of the node indicates the subject of the 
properties that the node contains. 


The following procedures describe how to set the properties of a task or container by using either the 
Properties windows, or the corresponding task or container editor. 


Set the properties of a task or container with the Properties window 


1. In SQL Server Data Tools (SSDT), open the Integration Services project that contains the package you 
want. 


2. In Solution Explorer, double-click the package to open it. 
3. Click the Control Flow tab. 


4. On the design surface of the Control Flow tab, right-click the task or container, and then click 
Properties. 


5. In the Properties window, update the property value. 





NOTE 


Most properties can be set by typing a value directly in the text box, or by selecting a value from a list. However, 


some properties are more complex and have a custom property editor. To set the property, click in the text box, 


and then click the build (...) button to open the custom editor. 








6. Optionally, create property expressions to dynamically update the properties of the task or container. For 
more information, see Add or Change a Property Expression. 


7. To save the updated package, click Save Selected Items on the File menu. 


Set the properties of a task or container with the task or container editor 


1. In SQL Server Data Tools (SSDT), open the Integration Services project that contains the package you 
want. 


2. In Solution Explorer, double-click the package to open it. 
3. Click the Control Flow tab. 


4. On the design surface of the Control Flow tab, right-click the task or container, and then click Edit to 
open the corresponding task or container editor. 


For information about how to configure the For Loop container, see Configure a For Loop Container. 


For information about how to configure the Foreach Loop container, see Configure a Foreach Loop 
Container. 





NOTE 


The Sequence container has no custom editor. 





5. If the task or container editor has multiple nodes, click the node that contains the property that you want 
to set. 


6. Optionally, click Expressions and, on the Expressions page, create property expressions to dynamically 


update the properties of the task or container. For more information, see Add or Change a Property 
Expression. 


7. Update the property value. 


8. To save the updated package, click Save Selected Items on the File menu. 


See Also 


Integration Services Tasks 
Integration Services Containers 
Control Flow 
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Containers are objects in SQL Server Integration Services that provide structure to packages and services to 
tasks. They support repeating control flows in packages, and they group tasks and containers into meaningful 
units of work. Containers can include other containers in addition to tasks. 


Packages use containers for the following purposes: 


e Repeat tasks for each element in a collection, such as files in a folder, schemas, or SQL Server 
Management Objects (SMO) objects. For example, a package can run Transact-SQL statements that reside 
in multiple files. 


e Repeat tasks until a specified expression evaluates to false. For example, a package can send a different 
e-mail message seven times, one time for every day of the week. 


e Group tasks and containers that must succeed or fail as a unit. For example, a package can group tasks 
that delete and add rows in a database table, and then commit or roll back all the tasks when one fails. 


Container Types 


Integration Services provides four types of containers for building packages. The following table lists the 
container types. 


CONTAINER DESCRIPTION 

Foreach Loop Container Runs a control flow repeatedly by using an enumerator. 
For Loop Container Runs a control flow repeatedly by testing a condition. 
Sequence Container Groups tasks and containers into control flows that are 


subsets of the package control flow. 


Task Host Container Provides services to a single task. 


Packages and events handlers are also types of containers. For information see Integration Services (SSIS) 
Packages and Integration Services (SSIS) Event Handlers. 


Summary of Container Properties 


All container types have a set of properties in common. If you create packages using the graphical tools that 
Integration Services provides, the Properties window lists the following properties for the Foreach Loop, For 
Loop, and Sequence containers. The task host container properties are configured as part of configuring the task 
that the task host encapsulates. You set the Task Host properties when you configure the task. 


PROPERTY DESCRIPTION 


PROPERTY 


DelayValidation 


Description 


Disable 


DisableEventHandlers 


FailPackageOnFailure 


FailParentOnFailure 


ForcedExecutionValue 


ForcedExecutionValueType 


ForceExecutionResult 


ForceExecutionValue 


DESCRIPTION 


A Boolean value that indicates whether validation of the 
container is delayed until run time. The default value for this 
property is False. 


For more information, see DelayValidation. 


The container description. The property contains a string, 
but may be blank. 


For more information, see Description. 


A Boolean value that indicates whether the container runs. 
The default value for this property is False. 


For more information, see Disable. 


A Boolean value that indicates whether the event handlers 
associated with the container run. The default value for this 
property is False. 


A Boolean value that specifies whether the package fails if an 
error occurs in the container. The default value for this 
property is False. 


For more information, see FailPackageOnFailure. 


A Boolean value that specifies whether the parent container 
fails if an error occurs in the container. The default value for 
this property is False. 


For more information, see FailParentOnFailure. 


If ForceExecutionValue is set to True, the object that 
contains the optional execution value for the container. The 
default value of this property is 0. 


For more information, see ForcedExecutionValue. 


The data type of ForcedExecutionValue. The default value 
of this property is Int32. 


A value that specifies the forced result of running the 
package or container. The values are None, Success, 
Failure, and Completion. The default value for this 
property is None. 


For more information, see ForceExecutionResult. 


A Boolean value that specifies whether the optional 
execution value of the container should be forced to contain 
a particular value. The default value of this property is False. 


For more information, see ForceExecutionValue. 


PROPERTY DESCRIPTION 


ID The container GUID, which is assigned when the package is 
created. This property is read-only. 


ID. 


IsolationLevel The isolation level of the container transaction. The values 
are Unspecified, Chaos, ReadUncommitted, 
ReadCommitted, RepeatableRead, Serializable, and 
Snapshot. The default value of this property is 
Serializable. For more information, see |solationLevel. 


LocalelD A Microsoft Win32 locale. The default value of this property 
is the locale of the operating system on the local computer. 


For more information, see LocalelD. 


LoggingMode A value that specifies the logging behavior of the container. 
The values are Disabled, Enabled, and UseParentSetting. 
The default value of this property is UseParentSetting. For 
more information, see DISLoggingMode. 


MaximumErrorCount The maximum number of errors that can occur before a 
container stops running. The default value of this property is 
A. 


For more information, see MaximumErrorCount. 


Name The name of the container. 


For more information, see Name. 


TransactionOption The transactional participation of the container. The values 
are NotSupported, Supported, Required. The default 
value of this property is Supported. For more information, 
see DTSTransactionOption. 


To learn about all the properties that are available to Foreach Loop, For Loop, Sequence, and Task Host 
containers when configure them programmatically, see the following Integration Services API topics: 


e T:Microsoft.SqlServer.Dts.Runtime.ForEachLoop 
e T:Microsoft.SqlServerDts.Runtime.ForLoop 
e T:Microsoft.SqlServer.Dts.Runtime.Sequence 


e T:Microsoft.SqlServer.Dts.Runtime.TaskHost 


Objects that Extend Container Functionality 


Containers include control flows that consist of executables and precedence constraints, and may use event 
handlers, and variables. The task host container is an exception: because the task host container encapsulates a 
single task, it does not use precedence constraints. 


Executables 


Executables refers to the container-level tasks and any containers within the container. An executable can be one 
of the tasks and containers that Integration Services provides or a custom task. For more information, see 
Integration Services Tasks. 


Precedence Constraints 


Precedence constraints link containers and tasks within the same parent container into an ordered control flow. 


For more information, see Precedence Constraints. 


Event Handlers 


Event handlers at the container level respond to events raised by the container or the objects it includes. For 
more information, see Integration Services (SSIS) Event Handlers. 


Variables 


Variables that are used in containers include the container-level system variables that Integration Services 
provides and the user-defined variables that the container uses. For more information, see Integration Services 
(SSIS) Variables. 


Break Points 


When you set a breakpoint on a container and the break condition is Break when the container recevies the 
OnVariableValueChanged event, define the variable in the container scope. 


See Also 


Control Flow 
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The Foreach Loop container defines a repeating control flow in a package. The loop implementation is similar to 
Foreach looping structure in programming languages. In a package, looping is enabled by using a Foreach 
enumerator. The Foreach Loop container repeats the control flow for each member of a specified enumerator. 


SQL Server Integration Services provides the following enumerator types: 


e Foreach ADO enumerator to enumerate rows in tables. For example, you can get the rows in an ADO 
recordset. 


The Recordset destination saves data in memory in a recordset that is stored in a package variable of 
Object data type. You typically use a Foreach Loop container with the Foreach ADO enumerator to 
process one row of the recordset at a time. The variable specified for the Foreach ADO enumerator must 
be of Object data type. For more information about the Recordset destination, see Use a Recordset 
Destination. 


e Foreach ADO.NET Schema Rowset enumerator to enumerate the schema information about a data 
source. For example, you can enumerate and get a list of the tables in the AdventureWorks2012 SQL 
Server database. 


e Foreach File enumerator to enumerate files in a folder. The enumerator can traverse subfolders. For 
example, you can read all the files that have the *.log file name extension in the Windows folder and its 
subfolders. Note that the order in which the files are retrieved cannot be specified. 


e Foreach From Variable enumerator to enumerate the enumerable object that a specified variable 
contains. The enumerable object can be an array, an ADO.NET DataTable, an Integration Services 
enumerator, and so on. For example, you can enumerate the values of an array that contains the name of 
servers. 


e Foreach Item enumerator to enumerate items that are collections. For example, you can enumerate the 
names of executables and working directories that an Execute Process task uses. 


e Foreach Nodelist enumerator to enumerate the result set of an XML Path Language (XPath) expression. 
For example, this expression enumerates and gets a list of all the authors in the classical period: 


/authors/author[@period='classical'] . 


e Foreach SMO enumerator to enumerate SQL Server Management Objects (SMO) objects. For example, 
you can enumerate and get a list of the views in a SQL Server database. 


e Foreach HDFS File Enumerator to enumerate HDFS files in the specified HDFS location. 
e Foreach Azure Blob enumerator to enumerate blobs in a blob container in Azure Storage. 
e Foreach ADLS File enumerator to enumerate files in a directory in Azure Data Lake Store. 


e Foreach Data Lake Storage Gen2 File enumerator to enumerate files in a directory in Azure Data Lake 
Store Gen2. 


The following diagram shows a Foreach Loop container that has a File System task. The Foreach loop uses the 
Foreach File enumerator, and the File System task is configured to copy a file. If the folder that the enumerator 
specifies contains four files, the loop repeats four times and copies four files. 





You can use a combination of variables and property expressions to update the property of the package object 
with the enumerator collection value. First you map the collection value to a user-defined variable, and then you 
implement a property expression on the property that uses the variable. For example, the collection value of the 
Foreach File enumerator is mapped to a variable called MyFile and the variable is then used in the property 
expression for the Subject property of a Send Mail task. When the package runs, the Subject property is updated 
with the name of a file each time that the loop repeats. For more information, see Use Property Expressions in 
Packages. 


Variables that are mapped to the enumerator collection value can also be used in expressions and scripts. 


A Foreach Loop container can include multiple tasks and containers, but it can use only one type of enumerator. 
If the Foreach Loop container includes multiple tasks, you can map the enumerator collection value to multiple 
properties of each task. 


You can set a transaction attribute on the Foreach Loop container to define a transaction for a subset of the 
package control flow. In this way, you can manage transactions at the level of the Foreach Loop instead of the 
package level. For example, if a Foreach Loop container repeats a control flow that updates dimensions and fact 
tables in a star schema, you can configure a transaction to ensure that all fact tables are updated successfully, or 
none are updated. For more information, see Integration Services Transactions. 


Enumerator Types 
Enumerators are configurable, and you must provide different information, depending on the enumerator. 


The following table summarizes the information each enumerator type requires. 
ENUMERATOR CONFIGURATION REQUIREMENTS 


Foreach ADO Specify the ADO object source variable and the enumerator 
mode. The variable must be of Object data type. 


Foreach ADO.NET Schema Rowset Specify the connection to a database and the schema to 
enumerate. 

Foreach File Specify a folder and the files to enumerate, the format of the 
file name of the retrieved files, and whether to traverse 
subfolders. 

Foreach From Variable Specify the variable that contains the objects to enumerate. 

Foreach Item Define the items in the Foreach Item collection, including 


columns and column data types. 


Foreach Nodelist Specify the source of the XML document and configure the 
XPath operation. 


Foreach SMO Specify the connection to a database and the SMO objects 
to enumerate. 


ENUMERATOR CONFIGURATION REQUIREMENTS 


Foreach HDFS File Enumerator Specify a folder and the files to enumerate, the format of the 
file name of the retrieved files, and whether to traverse 
subfolders. 

Foreach Azure Blob Specify the Azure blob container that containers blobs to be 
enumerated. 

Foreach ADLS File Specify the Azure Data Lake Store directory that contains the 


files to be enumerated. 


Foreach Data Lake Storage Gen2 File Specify the Azure Data Lake Storage Gen2 directory that 
contains the files to be enumerated, along with other 
options. 


Add enumeration to a control flow with a Foreach Loop container 


Integration Services includes the Foreach Loop container, a control flow element that makes it simple to include 
a looping construct that enumerates files and objects in the control flow of a package. For more information, see 
Foreach Loop Container. 


The Foreach Loop container provides no functionality; it provides only the structure in which you build the 
repeatable control flow, specify an enumerator type, and configure the enumerator. To provide container 
functionality, you must include at least one task in the Foreach Loop container. For more information, see 
Integration Services Tasks. 


The Foreach Loop container can include a control flow with multiple tasks and other containers. Adding tasks 
and containers to a Foreach Loop container is similar to adding them to a package, except you drag the tasks 
and containers to the Foreach Loop container instead of to the package. If the Foreach Loop container includes 
more than one task or container, you can connect them using precedence constraints just as you do ina 
package. For more information, see Precedence Constraints. 


Add and configure a Foreach Loop container 


1. Add the Foreach Loop container to the package. For more information, see Add or Delete a Task or a 
Container in a Control Flow. 


2. Add tasks and containers to the Foreach Loop container. For more information, see Add or Delete a Task 
or a Container in a Control Flow. 


3. Connect tasks and containers in the Foreach Loop container using precedence constraints. For more 
information, see Connect Tasks and Containers by Using a Default Precedence Constraint. 


4. Configure the Foreach Loop container. For more information, see Configure a Foreach Loop Container. 


Configure a Foreach Loop Container 


This procedure describes how to configure a Foreach Loop container, including property expressions at the 
enumerator and container levels. 


1. In SQL Server Data Tools (SSDT), open the Integration Services project that contains the package you 
want. 


2. Click the Control Flow tab and double-click the Foreach Loop. 


3. In the Foreach Loop Editor dialog box, click General and, optionally, modify the name and description 
of the Foreach Loop. 


. Click Collection and select an enumerator type from the Enumerator list. 
. Specify an enumerator and set enumerator options as follows: 


e Touse the Foreach File enumerator, provide the folder that contains the files to enumerate, specify 
a filter for the file name and type, and specify whether the fully qualified file name should be 
returned. Also, indicate whether to recurse through subfolders for more files. 


e To use the Foreach Item enumerator, click Columns, and, in the For Each Item Columns dialog 
box, click Add to add columns. Select a data type in the Data Type list for each column, and click 
OK. 


Type values in the columns or select values from lists. 
NOTE 


To add a new row, click anywhere outside the cell in which you typed. 


NOTE 
If a value is not compatible with the column data type, the text is highlighted. 











e To use the Foreach ADO enumerator, select an existing variable or click New variable in the ADO 
object source variable list to specify the variable that contains the name of the ADO object to 


enumerate, and select an enumeration mode option. 
If creating a new variable, set the variable properties in the Add Variable dialog box. 


e To use the Foreach ADO.NET Schema Rowset enumerator, select an existing ADO.NET connection 
or click New connection in the Connection list, and then select a schema. 


Optionally, click Set Restrictions and select schema restrictions, select the variable that contains 
the restriction value or type the restriction value, and click OK. 


e To use the Foreach From Variable enumerator, select a variable in the Variable list. 


e To use the Foreach NodeList enumerator, click DocumentSourceType and select the source type 
from the list, and then click DocumentSource. Depending on the value selected for 
DocumentSourceType, select a variable or a file connection from the list, create a new variable or 


file connection, or type the XML source in the Document Source Editor. 


Next, click EnumerationType and select an enumeration type from the list. If EnumerationType is 
Navigator, Node, or NodeText, click OuterXPathStringSourceType and select the source type, 
and then click OuterXPathString. Depending on the value set for OuterXPathStringSourceType, 
select a variable or a file connection from the list, create a new variable or file connection, or type 
the string for the outer XML Path Language (XPath) expression. 


If EnumerationType is ElementCollection, set OuterXPathStringSourceType and OuterXPathString 
as described above. Then, click InnerElementType and select an enumeration type for the inner 
elements, and then click InnerXPathStringSourceType. Depending on the value set for 
InnerXPathStringSourceType, select a variable or a file connection, create a new variable or file 
connection, or type the string for the inner XPath expression. 


e To use the Foreach SMO enumerator, select an existing ADO.NET connection or click New 
connection in the Connection list, and then either type the string to use or click Browse. If you 
click Browse, in the Select SMO Enumeration dialog box, select the object type to enumerate 


and the enumeration type, and click OK. 


6. Optionally, click the browse button (...) in the Expressions text box on the Collection page to create 
expressions that update property values. For more information, see Add or Change a Property 
Expression. 





NOTE 


The properties listed in the Property list vary by enumerator. 





7. Optionally, click Variable Mappings to map object properties to the collection value, and then do the 
following things: 


a. In the Variables list, select a variable or click <New Variable> to create a new variable. 
b. If you add a new variable, set the variable properties in the Add Variable dialog box and click OK. 


c. If you use the For Each Item enumerator, you can update the index value in the Index list. 


NOTE 


The index value indicates which column in the item to map to the variable. Only the For Each Item 


enumerator can use an index value other than 0. 





8. Optionally, click Expressions and, on the Expressions page, create property expressions for the 
properties of the Foreach Loop container. For more information, see Add or Change a Property 
Expression. 


9. Click OK. 


General Page - Foreach Loop Editor 


Use the General page of the Foreach Loop Editor dialog box to name and describe a Foreach Loop container 


that uses a specified enumerator to repeat a workflow for each member in a collection. 


To learn about the Foreach Loop container and how to configure it, see Foreach Loop Container and Configure a 
Foreach Loop Container. 


Options 

Name 

Provide a unique name for the Foreach Loop container. This name is used as the label in the task icon and in the 
logs. 





NOTE 


Object names must be unique within a package. 











Description 
Type a description of the Foreach Loop container. 


Collection Page - Foreach Loop Editor 


Use the Collection page of the Foreach Loop Editor dialog box to specify the enumerator type and configure 
the enumerator. 


To learn about the Foreach Loop container and how to configure it, see Foreach Loop Container and Configure a 


Foreach Loop Container. 


Static Options 


Enumerator 


Select the enumerator type from the list. This property has the options listed in the following table: 


VALUE 


Foreach File Enumerator 


Foreach Item Enumerator 


Foreach ADO Enumerator 


Foreach ADO.NET Schema Rowset Enumerator 


Foreach From Variable Enumerator 


Foreach Nodelist Enumerator 


Foreach SMO Enumerator 


Foreach HDFS File Enumerator 


Foreach Azure Blob Enumerator 


Foreach ADLS File Enumerator 


Foreach Data Lake Storage Gen2 File Enumerator 


Expressions 


DESCRIPTION 


Enumerate files. Selecting this value displays the dynamic 
options in the section, Foreach File Enumerator. 


Enumerate values in an item. Selecting this value displays the 
dynamic options in the section, Foreach Item 
Enumerator. 


Enumerate tables or rows in tables. Selecting this value 
displays the dynamic options in the section, Foreach ADO 
Enumerator. 


Enumerate a schema. Selecting this value displays the 
dynamic options in the section, Foreach ADO.NET 
Enumerator. 


Enumerate the value in a variable. Selecting this value 
displays the dynamic options in the section, Foreach From 
Variable Enumerator. 


Enumerate nodes in an XML document. Selecting this value 
displays the dynamic options in the section, Foreach 
Nodelist Enumerator. 


Enumerate a SMO object. Selecting this value displays the 
dynamic options in the section, Foreach SMO 
Enumerator. 


Enumerate HDFS files in the specified HDFS location. 
Selecting this value displays the dynamic options in the 
section, Foreach HDFS File Enumerator. 


Enumerate blob files in the specified blob location. Selecting 
this value displays the dynamic options in the section, 
Foreach Azure Blob Enumerator. 


Enumerate files in the specified Data Lake Store directory. 
Selecting this value displays the dynamic options in the 
section, Foreach ADLS File Enumerator. 


Enumerate files in the specified Data Lake Storage Gen2 
directory. Selecting this value displays the dynamic options 
in the section, Foreach Data Lake Storage Gen2 File 
Enumerator. 


Click or expand Expressions to view the list of existing property expressions. Click the ellipsis button (...) to add 


a property expression for an enumerator property, or edit and evaluate an existing property expression. 


Related Topics: Integration Services (SSIS) Expressions, Property Expressions Editor, Expression Builder 


Enumerator Dynamic Options 

Enumerator = Foreach File Enumerator 

You use the Foreach File enumerator to enumerate files in a folder. For example, if the Foreach Loop includes an 
Execute SQL task, you can use the Foreach File enumerator to enumerate files that contain SQL statements that 
the Execute SQL task runs. The enumerator can be configured to include subfolders. 


The content of the folders and subfolders that the Foreach File enumerator enumerates might change while the 
loop is executing because external processes or tasks in the loop add, rename, or delete files while the loop is 
executing. These changes may cause a number of unexpected situations: 


e If files are deleted, the actions of one task in the Foreach Loop may affect a different set of files than the 
files used by subsequent tasks. 


e If files are renamed and an external process automatically adds files to replace the renamed files, the 
actions of tasks in the Foreach Loop may affect the same files twice. 


e If files are added, it may be difficult to determine for which files the Foreach Loop affected. 


Folder 
Provide the path of the root folder to enumerate. 


Browse 
Browse to locate the root folder. 


Files 
Specify the files to enumerate. 





NOTE 


Use wildcard characters (*) to specify the files to include in the collection. For example, to include files with names that 


contain "abc", use the following filter: *abc*. 


When you specify a file name extension, the enumerator also returns files that have the same extension with additional 
characters appended. (This is the same behavior as that of the dir command in the operating system, which also 
compares 8.3 file names for backward compatibility.) This behavior of the enumerator could cause unexpected results. For 
example, you want to enumerate only Excel 2003 files, and you specify "*.xls". However, the enumerator also returns Excel 


2007 files because those files have the extension, ".xlsx". 


You can use an expression to specify the files to include in a collection, by expanding Expressions on the Collection 


page, selecting the FileSpec property, and then clicking the ellipsis button (...) to add the property expression. 





Fully qualified 
Select to retrieve the fully qualified path of file names. If wildcard characters are specified in the Files option, 
then the fully qualified paths that are returned match the filter. 


Name only 
Select to retrieve only the file names. If wildcard characters are specified in the Files option, then the file names 


returned match the filter. 


Name and extension 
Select to retrieve the file names and their file name extensions. If wildcard characters are specified in the Files 
option, then the name and extension of files returned match the filter. 


Traverse Subfolders 
Select to include the subfolders in the enumeration. 


Enumerator = Foreach Item Enumerator 


You use the Foreach Item enumerator to enumerate items in a collection. You define the items in the collection 





by specifying columns and column values. The columns in a row define an item. For example, an item that 
specifies the executables that an Execute Process task runs and the working directory that the task uses has two 
columns, one that lists the names of executables and one that lists the working directory. The number of rows 
determines the number of times that the loop is repeated. If the table has 10 rows, the loop repeats 10 times. 


To update the properties of the Execute Process task, you map variables to item columns by using the index of 
the column. The first column defined in the enumerator item has the index value 0, the second column 1, and so 
on. The variable values are updated with each repeat of the loop. The Executable and WorkingDirectory 
properties of the Execute Process task can then be updated by property expressions that use these variables. 


Define the items in the For Each Item collection 
Provide a value for each column in the table. 





NOTE 


A new row is automatically added to the table after you enter values in row columns. 








NOTE 


If the values provided are not compatible with the column data type, the text is colored red. 





Column data type 
Lists the data type of the active column. 


Remove 


Select an item, and then click Remove to remove it from the list. 


Columns 


Click to configure the data type of the columns in the item. 


Related Topics: For Each Item Columns Dialog Box UI Reference 


Enumerator = Foreach ADO Enumerator 

You use the Foreach ADO enumerator to enumerate rows or tables in an ADO or ADO.NET object that is stored 
in a variable. For example, if the Foreach Loop includes a Script task that writes a dataset to a variable, you can 
use the Foreach ADO enumerator to enumerate the rows in the dataset. If the variable contains an ADO.NET 
dataset, the enumerator can be configured to enumerate rows in multiple tables or to enumerate tables. 


ADO object source variable 
Select a user-defined variable in the list, or click <New variable...> to create a new variable. 








NOTE 


The variable must have the Object data type, otherwise an error occurs. 





Related Topics: Integration Services (SSIS) Variables, Add Variable 


Rows in first table 
Select to enumerate only rows in the first table. 


Rows in all tables (ADO.NET dataset only) 
Select to enumerate rows in all tables. This option is available only if the objects to enumerate are all members 
of the same ADO.NET dataset. 


All tables (ADO.NET dataset only) 
Select to enumerate tables only. 


Enumerator = Foreach ADO.NET Schema Rowset Enumerator 

You use the Foreach ADO.NET Schema Rowset enumerator to enumerate a schema for a specified data source. 
For example, if the Foreach Loop includes an Execute SQL task, you can use the Foreach ADO.NET Schema 
Rowset enumerator to enumerate schemas such as the columns in the AdventureWorks database, and the 
Execute SQL task to get the schema permissions. 


Connection 
Select an ADO.NET connection manager in the list, or click <New connection...> to create a new ADO.NET 


connection manager. 


IMPORTANT 

The ADO.NET connection manager must use a .NET provider for OLE DB. If connecting to SQL Server, the recommended 
provider to use is the SQL Server Native Client, listed in the .Net Providers for OleDb section of the Connection 
Manager dialog box. 





Related Topics: ADO Connection Manager, Configure ADO.NET Connection Manager 


Schema 
Select the schema to enumerate. 


Set Restrictions 
Set the restrictions to apply to the specified schema. 


Related Topics: Schema Restrictions Dialog Box 


Enumerator = Foreach From Variable Enumerator 

You use the Foreach From Variable enumerator to enumerate the enumerable objects in the specified variable. 
For example, if the Foreach Loop includes an Execute SQL task that runs a query and stores the result in a 
variable, you can use the Foreach From Variable enumerator to enumerate the query results. 


Variable 
Select a variable in the list, or click <New variable...> to create a new variable. 


Related Topics: Integration Services (SSIS) Variables, Add Variable 


Enumerator = Foreach NodeList Enumerator 

You use the Foreach Nodelist enumerator to enumerate the set of XML nodes that results from applying an 
XPath expression to an XML file. For example, if the Foreach Loop includes a Script task, you can use the Foreach 
NodeList enumerator to pass a value that meets the XPath expression criteria from the XML file to the Script 
task. 


The XPath expression that applies to the XML file is the outer XPath operation, stored in the OuterXPathString 
property. If the XPath enumeration type is set to ElementCollection, the Foreach NodeList enumerator can 
apply an inner XPath expression, stored in the InnerXPathString property, to a collection of element. 


To learn more about working with XML documents and data, see "Employing XML in the .NET Framework" in the 
MSDN Library. 


DocumentSourcelype 
Select the source type of the XML document. This property has the options listed in the following table: 


VALUE DESCRIPTION 


Direct input Set the source to an XML document. 


File connection Select a file that contains the XML document. 





VALUE DESCRIPTION 


Variable Set the source to a variable that contains the XML 
document. 


DocumentSource 
lf DocumentSourceType is set to Direct input, provide the XML code, or click the ellipsis (...) button to 
provide XML by using the Document Source Editor dialog box. 


If DocumentSourceType is set to File connection, select a File connection manager, or click <New 
connection...> to create a new connection manager. 


Related Topics: File Connection Manager, File Connection Manager Editor 


lf DocumentSourceType is set to Variable, select an existing variable, or click <New variable...> to create a 
new variable. 


Related Topics: Integration Services (SSIS) Variables, Add Variable. 


EnumerationType 
Select an enumeration type from the list. This property has the options listed in the following table: 


VALUE DESCRIPTION 

Navigator Enumerate using an XPathNavigator. 

Node Enumerate nodes returned by an XPath operation. 
NodeText Enumerate text nodes returned by an XPath operation. 
ElementCollection Enumerates element nodes returned by an XPath operation. 


OuterXPathStringSourcelype 
Select the source type of the XPath string. This property has the options listed in the following table: 


VALUE DESCRIPTION 

Direct input Set the source to an XML document. 

File connection Select a file that contains the XML document. 

Variable Set the source to a variable that contains the XML 
document. 


OuterXPathString 
If OuterXPathStringSourceType is set to Direct input, provide the XPath string. 


If OuterXPathStringSourceType is set to File connection, select a File connection manager, or click <New 


connection...> to create a new connection manager. 
Related Topics: File Connection Manager, File Connection Manager Editor 


lf OuterXPathStringSourceType is set to Variable, select an existing variable, or click <New variable...> to 
create a new variable. 


Related Topics: Integration Services (SSIS) Variables, Add Variable. 


InnerElementType 
If EnumerationType is set to ElementCollection, select the type of inner element in the list. 


InnerXPathStringSourceType 
Select the source type of the inner XPath string. This property has the options listed in the following table: 


VALUE DESCRIPTION 

Direct input Set the source to an XML document. 

File connection Select a file that contains the XML document. 

Variable Set the source to a variable that contains the XML 
document. 


InnerXPathString 
If InnerXPathStringSourceType is set to Direct input, provide the XPath string. 


If InnerXPathStringSourceType is set to File connection, select a File connection manager, or click <New 
connection...> to create a new connection manager. 


Related Topics: File Connection Manager, File Connection Manager Editor 


lf InnerXPathStringSourceType is set to Variable, select an existing variable, or click <New variable...> to 


create a new variable. 


Related Topics: Integration Services (SSIS) Variables, Add Variable. 


Enumerator = Foreach SMO Enumerator 

You use the Foreach SMO enumerator to enumerate SQL Server Management Object (SMO) objects. For 
example, if the Foreach Loop includes an Execute SQL task, you can use the Foreach SMO enumerator to 
enumerate the tables in the AdventureWorks database and run queries that count the number of rows in each 
table. 


Connection 
Select an existing ADO.NET connection manager, or click <New connection...> to create a new connection 


manager. 
Related Topics: ADO.NET Connection Manager, Configure ADO.NET Connection Manager 


Enumerate 
Specify the SMO object to enumerate. 


Browse 
Select the SMO enumeration. 


Related Topics: Select SMO Enumeration Dialog Box 


Enumerator = Foreach HDFS File Enumerator 
The Foreach HDFS File Enumerator enables an SSIS package to enumerate HDFS files in the specified HDFS 
location. The name of each HDFS file can be stored in a variable and used in tasks inside the Foreach Loop 


Container. 


Hadoop Connection Manager 
Specify an existing Hadoop Connection Manager or create a new one, which points to where the HDFS files are 
hosted. For more info, see Hadoop Connection Manager. 


Directory Path 
Specify the name of the HDFS directory that contains the HDFS files to be enumerated. 


File name filter 
Specify a name filter to select files with a certain name pattern. For example, MySheet*.xls* includes files such as 
MySheet001.xls and MySheetABC.xlsx. 


Retrieve file name 


Specify the file name type retrieved by SSIS. 
e Fully qualified name means the full name, which contains the directory path and file name. 
e Name only means the file name is retrieved without the path. 


Traverse subfolders 
Specify whether to loop through subfolders recursively. 


On the Variable Mappings page of the editor, select or create a variable to store the name of the enumerated 
HDFS file. 


Enumerator = Foreach Azure Blob Enumerator 
The Azure Blob Enumerator enables an SSIS package to enumerate blob files in the specified blob location. 
You can store the name of the enumerated blob file in a variable and use it in tasks inside the Foreach Loop 


Container. 


The Azure Blob Enumerator is a component of the SQL Server Integration Services (SSIS) Feature Pack for 
Azure for SQL Server 2016 (13.x). Download the Feature Pack here. 


Azure storage connection manager 
Select an existing Azure Storage Connection Manager or create a new one that refers to an Azure Storage 
Account. 


Related Topics: Azure Storage Connection Manager. 


Blob container name 


Specify the name of the blob container that contains the blob files to be enumerated. 


Blob directory 
Specify the blob directory that contains the blob files to be enumerated. The blob directory is a virtual 
hierarchical structure. 


Search recursively 
Specify whether to recursively search within sub-directories. 


Blob name filter 
Specify a name filter to enumerate files with a certain name pattern. For example, MySheet*.xls\* includes files 
such as MySheet001.xls and MySheetABC.xlsx. 


Blob time range from/to filter 
Specify a time range filter. Files modified after TimeRangeFrom and before TimeRangeTo are enumerated. 


Enumerator = Foreach ADLS File Enumerator 

The ADLS File Enumerator enables an SSIS package to enumerate files in Azure Data Lake Store. You can 
store the full path of the enumerated file (prefixed with a slash - / ) in a variable and use the file path in tasks 
inside the Foreach Loop Container. 


AzureDataLakeConnection 
Specifies an Azure Data Lake connection manager, or creates a new one that refers to an ADLS account. 


AzureDataLakeDirectory 
Specifies the ADLS directory that contains the files to be enumerated. 


FileNamePattern 


Specifies a file name filter. Only files whose names match the specified pattern are enumerated. The wildcards 
* and ? are supported. 


SearchRecursively 
Specifies whether to search recursively within the specified directory. 


Enumerator = Foreach Data Lake Storage Gen2 File Enumerator 
The Foreach Data Lake Storage Gen2 File Enumerator enables an SSIS package to enumerate files in 
Azure Data Lake Storage Gen2. 


AzureStorageConnection 
Specifies an existing Azure Storage Connection Manager or creates a new one that references a Data Lake 
Storage Gen2 service. 


FolderPath 
Specifies the path of the folder to enumerate files in. 


SearchRecursively 
Specifies whether to search recursively within the specified folder. 


Notes on Service Principal Permission Configuration 


Data Lake Storage Gen2 permission is determined by both RBAC and ACLs. Pay attention that ACLs are 
configured using the Object ID (OID) of the service principal for the app registration as detailed here. This is 
different from the Application (client) ID that is used with RBAC configuration. When a security principal is 
granted RBAC data permissions through a built-in role, or through a custom role, these permissions are 
evaluated first upon authorization of a request. If the requested operation is authorized by the security 
principal's RBAC assignments, then authorization is immediately resolved and no additional ACL checks are 
performed. Alternatively, if the security principal does not have an RBAC assignment, or the request's operation 
does not match the assigned permission, then ACL checks are performed to determine if the security principal is 
authorized to perform the requested operation. For the enumerator to work, grant at least Execute permission 
starting from the root file system, along with Read permission for the target folder. Alternatively, grant at least 
the Storage Blob Data Reader role with RBAC. See this article for details. 


Variable Mappings Page - Foreach Loop Editor 


Use the Variables Mappings page of the Foreach Loop Editor dialog box to map variables to the collection 
value. The value of the variable is updated with the collection values on each iteration of the loop. 


To learn about how to use the Foreach Loop container in an Integration Services package, see Foreach Loop 
Container. To learn about how to configure it, see Configure a Foreach Loop Container. 


The Microsoft SQL Server Integration Services tutorial, Creating a Simple ETL Package Tutorial, includes a lesson 
that teaches you to add and configure a Foreach Loop. 


Options 
Variable 


Select an existing variable, or click New variable... to create a new variable. 





NOTE 


After you map a variable, a new row is automatically added to the Variable list. 





Related Topics: Integration Services (SSIS) Variables, Add Variable 


Index 


If using the Foreach Item enumerator, specify the index of the column in the collection value to map to the 


variable. For other enumerator types, the index is read-only. 





NOTE 
The index is 0-based. 





Delete 
Select a variable, and then click Delete. 


Schema Restrictions dialog box (ADO.NET) 


Use the Schema Restrictions dialog box to set the schema restrictions to apply to the Foreach ADO.NET 
Schema Rowset enumerator. 


Options 
Restrictions 
Select the constraints to apply to the schema. 


Variable 
Use a variable to define restrictions. Select a variable in the list, or click New variable... to create a new variable. 


Related Topics: Integration Services (SSIS) Variables , Add Variable 


Text 
Provide the text to define restrictions. 


For Each Item Columns dialog box 


Use the For Each Item Columns dialog box to define the columns in the items that the Foreach Item 
enumerator enumerates. 

Options 

Column 


Lists the columns. 


Data Type 
Select the data type. 


Add 
Add a new column. 


Remove 
Select a column, and then click Remove. 


Select SMO Enumeration dialog box 


Use the Select SMO Enumeration dialog box to specify the SQL Server Management Objects (SMO) object on 
the specified instance of SQL Server to enumerate, and to select the enumeration type. 
Options 


Enumerate 


Expand the server and select the SMO object. 


Objects 
Use the Objects enumeration type. 


Prepopulate 


Use the Prepopulate option with the Objects enumeration type. 


Names 
Use the Names enumeration type. 


URNs 
Use the URNs enumeration type. 


Locations 
Use the Locations enumeration type. This option is available only for files. 


Use property expressions with Foreach Loop containers 


Packages can be configured to concurrently run multiple executables. This configuration should be used with 
caution when the package includes a Foreach Loop container that implements property expressions. 


It is often useful to implement a property expression to set the value of the ConnectionString property of the 
connection managers that the Foreach Loop enumerators use. The property expression of ConnectionString is 
set by a variable that maps to the collection value of the enumerator and is updated at each iteration of the loop. 


To avoid negative consequences of nondeterminative timing of parallel execution of tasks in the loop, the 
package should be configured to run only one executable at a time. For example, if a package can run multiple 
tasks concurrently, a Foreach Loop container that enumerates files in the folder, retrieves the file names, and 
then uses an Execute SQL task to insert the file names into a table may incur write conflicts when two instances 
of the Execute SQL task attempt to write at the same time. For more information, see Use Property Expressions 
in Packages. 


See Also 


Control Flow 
Integration Services Containers 


Loop through Excel Files and Tables with a Foreach 


Loop Container 
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Applies to: Q sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


The procedures in this topic describe how to loop through the Excel workbooks in a folder, or through the tables 
in an Excel workbook, by using the Foreach Loop container with the appropriate enumerator. 


IMPORTANT 


For detailed info about connecting to Excel files, and about limitations and known issues for loading data from or to Excel 
files, see Load data from or to Excel with SQL Server Integration Services (SSIS). 











To loop through Excel files by using the Foreach File enumerator 


1. Create a string variable that will receive the current Excel path and file name on each iteration of the loop. 
To avoid validation issues, assign a valid Excel path and file name as the initial value of the variable. (The 
sample expression shown later in this procedure uses the variable name, ExcelFile .) 


2. Optionally, create another string variable that will hold the value for the Extended Properties argument of 
the Excel connection string. This argument contains a series of values that specify the Excel version and 
determine whether the first row contains column names, and whether import mode is used. (The sample 
expression shown later in this procedure uses the variable name ExtProperties , with an initial value of " 


Excel 12.@;HDR=Yes ".) 


If you do not use a variable for the Extended Properties argument, then you must add it manually to the 
expression that contains the connection string. 


3. Add a Foreach Loop container to the Control Flow tab. For information about how to configure the 
Foreach Loop Container, see Configure a Foreach Loop Container. 


4. On the Collection page of the Foreach Loop Editor, select the Foreach File enumerator, specify the 
folder in which the Excel workbooks are located, and specify the file filter (ordinarily *.xlsx). 


5. On the Variable Mapping page, map Index 0 to a user-defined string variable that will receive the 
current Excel path and file name on each iteration of the loop. (The sample expression shown later in this 
procedure uses the variable name eExcelFile .) 


6. Close the Foreach Loop Editor. 


7. Add an Excel connection manager to the package as described in Add, Delete, or Share a Connection 
Manager in a Package. Select an existing Excel workbook file for the connection to avoid validation errors. 


8. 


10. 


11. 





IMPORTANT 

To avoid validation errors as you configure tasks and data flow components that use this Excel connection 
manager, select an existing Excel workbook in the Excel Connection Manager Editor. The connection manager 
will not use this workbook at run time after you configure an expression for the ConnectionString property as 
described in the following steps. After you create and configure the package, you can clear the value of the 
ConnectionString property in the Properties window. However, if you clear this value, the connection string 
property of the Excel connection manager is no longer valid until the Foreach Loop runs. Therefore you must set 
the DelayValidation property to True on the tasks in which the connection manager is used, or on the package, 


to avoid validation errors. 


You must also use the default value of False for the RetainSameConnection property of the Excel connection 
manager. If you change this value to True, each iteration of the loop will continue to open the first Excel 


workbook. 








Select the new Excel connection manager, click the Expressions property in the Properties window, and 


then click the ellipsis. 


. Inthe Property Expressions Editor, select the ConnectionString property, and then click the ellipsis. 


In the Expression Builder, enter the following expression: 


"Provider=Microsoft.ACE.OLEDB.12.0;Data Source=" + @[User::ExcelFile] + ";Extended Properties=\"" + 
@[User: :ExtProperties] + "\"" 


Note the use of the escape character "\" to escape the inner quotation marks required around the value of 
the Extended Properties argument. 
The Extended Properties argument is not optional. If you do not use a variable to contain its value, then 


you must add it manually to the expression, as in the following example: 


"Provider=Microsoft.ACE.OLEDB.12.0;Data Source=" + @[User::ExcelFile] + ";Extended Properties=Excel 
120 


Create tasks in the Foreach Loop container that use the Excel connection manager to perform the same 
operations on each Excel workbook that matches the specified file location and pattern. 


To loop through Excel tables by using the Foreach ADO.NET Schema 
Rowset enumerator 


1. 


Create an ADO.NET connection manager that uses the Microsoft ACE OLE DB Provider to connect to an 
Excel workbook. On the All page of the Connection Manager dialog box, make sure that you enter the 
Excel version - in this case, Excel 12.0 - as the value of the Extended Properties property. For more 
information, see Add, Delete, or Share a Connection Manager in a Package. 


. Create a string variable that will receive the name of the current table on each iteration of the loop. 


. Add a Foreach Loop container to the Control Flow tab. For information about how to configure the 


Foreach Loop container, see Configure a Foreach Loop Container. 


. On the Collection page of the Foreach Loop Editor, select the Foreach ADO.NET Schema Rowset 


enumerator. 


. As the value of Connection, select the ADO.NET connection manager that you created previously. 


. As the value of Schema, select Tables. 





NOTE 


The list of tables in an Excel workbook includes both worksheets (which have the $ suffix) and named ranges. If 
you have to filter the list for only worksheets or only named ranges, you may have to write custom code in a 


Script task for this purpose. For more information, see Working with Excel Files with the Script Task. 








7. On the Variable Mappings page, map Index 2 to the string variable created earlier to hold the name of 
the current table. 


8. Close the Foreach Loop Editor. 


9. Create tasks in the Foreach Loop container that use the Excel connection manager to perform the same 
operations on each Excel table in the specified workbook. If you use a Script Task to examine the 
enumerated table name or to work with each table, remember to add the string variable to the 
ReadOnlyVariables property of the Script task. 


See Also 


Load data from or to Excel with SQL Server Integration Services (SSIS) 
Configure a Foreach Loop Container 

Add or Change a Property Expression 

Excel Connection Manager 

Excel Source 

Excel Destination 

Working with Excel Files with the Script Task 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


The For Loop container defines a repeating control flow in a package. The loop implementation is similar to the 
For looping structure in programming languages. In each repeat of the loop, the For Loop container evaluates 
an expression and repeats its workflow until the expression evaluates to False. 


The For Loop container usesthe following elements to define the loop: 
e An optional initialization expression that assigns values to the loop counters. 


e An evaluation expression that contains the expression used to test whether the loop should stop or 
continue. 


e An optional iteration expression that increments or decrements the loop counter. 


The following diagram shows a For Loop container with a Send Mail task. If the initialization expression is 
@counter = @ , the evaluation expression is @Counter < 4, and the iteration expression is 


@Counter = @Counter + 1, the loop repeats four times and sends four e-mail messages. 


The expressions must be valid SQL Server Integration Services expressions. 


Loop 


To create the initialization and assignment expressions, you can use the assignment operator (=). This operator 
is not otherwise supported by the Integration Services expression grammar and can only be used by the 
initialization and assignment expression types in the For Loop container. Any expression that uses the 
assignment operator must have the syntax @var = <expression> , where Var is a run-time variable and 
<expression> is an expression that follows the rules of the SSIS expression syntax. The expression can include 
the variables, literals, and any operators and functions that the SSIS expression grammar supports. The 
expression must evaluate to a data type that can be cast to the data type of the variable. 


A For Loop container can have only one evaluation expression. This means that the For Loop container runs all 
its control flow elements the same number of times. Because the For Loop container can include other For Loop 
containers, you can build nested loops and implement complex looping in packages. 


You can set a transaction property on the For Loop container to define a transaction for a subset of the package 
control flow. In this way, you can manage transactions at a more granular level. For example, if a For Loop 
container repeats a control flow that updates data in a table multiple times, you can configure the For Loop and 
its control flow to use a transaction to ensure that if not all data is updated successfully, no data is updated. For 
more information, see Integration Services Transactions. 


Add iteration to a control flow with the For Loop container 


Integration Services includes the For Loop container, a control flow element that makes it simple to include 
looping that conditionally repeats a control flow in a package. For more information, see For Loop Container. 


The For Loop container evaluates a condition on each iteration of the loop, and stops when the condition 
evaluates to false. The For Loop container includes expressions for initializing the loop, specifying the evaluation 


condition that stops execution of the repeating control flow, and assigning a value to an expression that updates 
the value against which the evaluation condition is compared. You must provide an evaluation condition, but 


initialization and assignment expressions are optional. 


The For Loop container provides no functionality; it provides only the structure in which you build the 
repeatable control flow. To provide container functionality, you must include at least one task in the For Loop 
container. For more information, see Integration Services Tasks. 


The For Loop container can include a control flow with multiple tasks, and can include other containers. Adding 
tasks and containers to a For Loop container is similar to adding them to a package, except you drag the tasks 
and containers to the For Loop container instead of to the package. If the For Loop container includes more than 
one task or container, you can connect them using precedence constraints just as you do in a package. For more 


information, see Precedence Constraints. 


Add a For Loop container in a control flow 


1. Add the For Loop container to the package. For more information, see Add or Delete a Task or a Container 
in a Control Flow. 


2. Add tasks and containers to the For Loop container. For more information, see Add or Delete a Task or a 
Container in a Control Flow. 


3. Connect tasks and containers in the For Loop container using precedence constraints. For more 
information, see Connect Tasks and Containers by Using a Default Precedence Constraint. 


4. Configure the For Loop container. For more information, see Configure a For Loop Container. 


Configure the For Loop container 


This procedure describes how to configure a For Loop container by using the For Loop Editor dialog box. 
1. In SQL Server Data Tools (SSDT), double-click the For Loop container to open the For Loop Editor. 

2. Optionally, modify the name and description of the For Loop container. 

3. Optionally, type an initialization expression in the InitExpression text box. 


4. Type an evaluation expression in the EvalExpression text box. 





NOTE 


The expression must evaluate to a Boolean. When the expression evaluates to false, the loop stops running. 





5. Optionally, type an assignment expression in the AssignExpression text box. 


6. Optionally, click Expressions and, on the Expressions page, create property expressions for the 
properties of the For Loop container. For more information, see Add or Change a Property Expression. 


7. Click OK to close the For Loop Editor. 


For Loop Editor dialog box 


Use the For Loop page of the For Loop Editor dialog box to configure a loop that repeats a workflow until a 
specified condition evaluates to false. 


To learn about the For Loop container and how to use it in packages, see For Loop Container. 


Options 


InitExpression 
Optionally, provide an expression that initializes values used by the loop. 


EvalExpression 
Provide an expression to evaluate whether the loop should stop or continue. 


AssignExpression 
Optionally, provide an expression that changes a condition each time that the loop repeats. 


Name 
Provide a unique name for the For Loop container. This name is used as the label in the task icon. 





NOTE 


Object names must be unique within a package. 





Description 


Provide a description of the For Loop container. 


Use expressions with the For Loop container 


When you configure the For Loop container by specifying an evaluation condition, initialization value, or 
assignment value, you can use either literals or expressions. 


The expressions can include variables. The advantage of using variables is that they can be updated at run time, 
making the packages more flexible and easier to manage. The maximum length of an expression is 4000 
characters. 


When you specify a variable in an expression, you must preface the variable name with the at sign (@). For 
example, for a variable named Counter, enter @Counter in the expression that the For Loop container uses. If 
you include the namespace property on the variable, you must enclose the variable and namespace in brackets. 
For example, for a Counter variable in the MyNamespace namespace, type [@MyNamespace::Counter]. 


The variables that the For Loop container uses must be defined in the scope of the For Loop container or in the 
scope of any container that is higher in the package container hierarchy. For example, a For Loop container can 
use variables defined in its scope and also variables defined in package scope. For more information, see 
Integration Services (SSIS) Variables and Use Variables in Packages. 


The SSIS expression grammar provides a complete set of operators and functions for implementing complex 
expressions used for evaluation, initialization, or assignment. For more information, see Integration Services 
(SSIS) Expressions. 


See Also 


Control Flow 
Integration Services (SSIS) Expressions 


Sequence Container 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


The Sequence container defines a control flow that is a subset of the package control flow. Sequence containers 
group the package into multiple separate control flows, each containing one or more tasks and containers that 
run within the overall package control flow. 


The Sequence container can include multiple tasks in addition to other containers. Adding tasks and containers 
to a Sequence container is similar to adding them to a package, except you drag the tasks and containers to the 
Sequence container instead of to the package container. If the Sequence container includes more than one task 
or container, you can connect them using precedence constraints just as you do in a package. For more 
information, see Precedence Constraints. 


There are many benefits of using a Sequence container: 
e Disabling groups of tasks to focus package debugging on one subset of the package control flow. 


e Managing properties on multiple tasks in one location by setting properties on a Sequence container 
instead of on the individual tasks. 


For example, you can set the Disable property of the Sequence container to True to disable all the tasks 


and containers in the Sequence container. 
e Providing scope for variables that a group of related tasks and containers use. 


e Grouping many tasks so you can more easily managed them by collapsing and expanding the Sequence 
container. 


You can also create task groups, which expand and collapse using the Group box. However, the Group 
box is a design-time feature that has no properties or run-time behavior. For more information, see 


Group or Ungroup Components 


e Seta transaction attribute on the Sequence container to define a transaction for a subset of the package 


control flow. In this way, you can manage transactions at a more granular level. 


For example, if a Sequence container includes two related tasks, one task that deletes data in a table and 
another task that inserts data into a table, you can configure a transaction to ensure that the delete action 
is rolled back if the insert action fails. For more information, see Integration Services Transactions. 


Configuration of the Sequence Container 


The Sequence container has no custom user interface and you can configure it only in the Properties window 
of SQL Server Data Tools (SSDT) or programmatically. 


For information about programmatically setting these properties, see documentation for the 
T:Microsoft.SqlServer.Dts.Runtime.Sequence class in the Developer Guide. 


Related Tasks 


For information about how to set properties of the component in the SQL Server Data Tools (SSDT), see Set the 
Properties of a Task or Container. 


See Also 


Add or Delete a Task or a Container in a Control Flow 
Connect Tasks and Containers by Using a Default Precedence Constraint 


Integration Services Containers 


Task Host Container 


11/23/2021 * 2 minutes to read « Edit Online 





Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


The task host container encapsulates a single task. In SSIS Designer, the task host is not configured separately; 
instead, it is configured when you set the properties of the task it encapsulates. For more information about the 
tasks that the task host containers encapsulate, see Integration Services Tasks. 


This container extends the use of variables and event handlers to the task level. For more information, see 
Integration Services (SSIS) Event Handlers and Integration Services (SSIS) Variables. 


Configuration of the Task Host 
You can set properties in the Properties window of SQL Server Data Tools (SSDT) or programmatically. 


For information about setting these properties in SQL Server Data Tools (SSDT), see Set the Properties of a Task 
or Container. 


For information about programmatically setting these properties, see TaskHost. 


Related Tasks 


e Set the Properties of a Task or Container 


See Also 


Integration Services Containers 


Integration Services Tasks 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Tasks are control flow elements that define units of work that are performed in a package control flow. An SQL 
Server Integration Services package is made up of one or more tasks. If the package contains more than one 
task, they are connected and sequenced in the control flow by precedence constraints. 


You can also write custom tasks using a programming language that supports COM, such as Visual Basic, or a 
.NET programming language, such as C#. 


The SSIS Designer, the graphical tool in SQL Server Integration Services for working with packages, provides the 
design surface for creating package control flow, and provides custom editors for configuring tasks. You can also 
program the SQL Server Integration Services object model to create packages programmatically. 


Types of Tasks 


Integration Services includes the following types of tasks. 


Data Flow Task 
The task that runs data flows to extract data, apply column level transformations, and load data. 


Data Preparation Tasks 
These tasks do the following processes: copy files and directories; download files and data; run Web methods; 
apply operations to XML documents; and profile data for cleansing. 


Workflow Tasks 

The tasks that communicate with other processes to run packages, run programs or batch files, send and receive 
messages between packages, send e-mail messages, read Windows Management Instrumentation (WMI) data, 
and watch for WMI events. 


SQL Server Tasks 
The tasks that access, copy, insert, delete, and modify SQL Server objects and data. 


Scripting Tasks 
The tasks that extend package functionality by using scripts. 


Analysis Services Tasks 
The tasks that create, modify, delete, and process Analysis Services objects. 


Maintenance Tasks 
The tasks that perform administrative functions such as backing up and shrinking SQL Server databases, 
rebuilding and reorganizing indexes, and running SQL Server Agent jobs. 


Custom Tasks 

Additionally, you can write custom tasks using a programming language that supports COM, such as Visual 
Basic, or a .NET programming language, such as C#. If you want to access your custom task in the SSIS Designer, 
you can create and register a user interface for the task. For more information, see Developing a Custom Task. 


Configuration of Tasks 


An Integration Services package can contain a single task, such as an Execute SQL task that deletes records in a 
database table when the package runs. However, packages typically contain several tasks, and each task is set to 


run within the context of the package control flow. Event handlers, which are workflows that run in response to 


run-time events, can also have tasks. 


For more information about adding a task to a package using SSIS Designer, see Add or Delete a Task or a 
Container in a Control Flow. 


For more information about adding a task to a package programmatically, see Adding Tasks Programmatically. 


Each task can be configured individually using the custom dialog boxes for each task that SSIS Designer 
provides, or the Properties window included in SQL Server Data Tools (SSDT). A package can include multiple 
tasks of the same type-for example, six Execute SQL tasks-and each task can be configured differently. For more 
information, see Set the Properties of a Task or Container. 


Tasks Connections and Groups 


If the task contains more than one task, they are connected and sequenced in the control flow by precedence 


constraints. For more information, see Precedence Constraints. 


Tasks can be grouped together and performed as a single unit of work, or repeated in a loop. For more 
information, see Foreach Loop Container, For Loop Container, and Sequence Container. 


Related Tasks 


Add or Delete a Task or a Container in a Control Flow 


Analysis Services Execute DDL Task 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


The Analysis Services Execute DDL task runs data definition language (DDL) statements that can create, drop, or 
alter mining models and multidimensional objects such as cubes and dimensions. For example, a DDL statement 
can create a partition in the Adventure Works cube, or delete a dimension in Adventure Works DW 
Multidimensional 2012, the sample Analysis Services database included in SQL Server. 


The Analysis Services Execute DDL task uses an Analysis Services connection manager to connect to an instance 
of Analysis Services or an Analysis Services project. For more information, see Analysis Services Connection 
Manager. 


Integration Services includes a number of tasks that perform business intelligence operations, such as 
processing analytic objects and running data mining prediction queries. 


For more information about related business intelligence tasks, click one of the following topics: 
e Analysis Services Processing Task 


e Data Mining Query Task 


DDL Statements 


The DDL statements are represented as statements in Analysis Services Scripting Language (ASSL), and framed 
in an XML for Analysis (MLA) command. 


e ASSL is used to define and describe an instance of Analysis Services and the databases and database 
objects it contains. For more information, see Analysis Services Scripting Language (ASSL for XMLA). 


e XMLA is a command language that is used to send action commands, such as Create, Alter, or Process, to 
an instance of Analysis Services. For more information, see XML for Analysis (XMLA) Reference. 


If the DDL code is stored in a separate file, the Analysis Services Execute DDL task uses a File connection 
manager to specify the path of the file. For more information, see File Connection Manager. 


Because DDL statements can contain passwords and other sensitive information, a package that contains one or 
more Analysis Services Execute DDL tasks should use the package protection level EncryptAllWithUserKey or 
EncryptAllWithPassword. For more information, see Integration Services (SSIS) Packages. 


DDL Examples 


The following three DDL statements were generated by scripting objects in the Adventure Works DW 
Multidimensional 2012, the Analysis Services database included in SQL Server. 


The following DDL statement deletes the Promotion dimension. 


<Delete xmlns="https://schemas.microsoft.com/analysisservices/2003/engine"> 
<Object> 
<DatabaseID>Adventure Works DW Multidimensional 2012</DatabaseID> 
<DimensionID>Dim Promotion</DimensionID> 
</Object> 
</Delete> 


The following DDL statement processes the Adventure Works DW Multidimensional 2012 cube. 


<Batch xmlns="https://schemas.microsoft.com/analysisservices/2003/engine"> 
<Parallel> 
<Process xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema- 
instance"> 
<Object> 
<DatabaseID>Adventure Works DW Multidimensional 2012</DatabaseID> 
</Object> 
<Type>ProcessFull</Type> 
<WriteBackTableCreation>UseExisting</WriteBackTableCreation> 
</Process> 
</Parallel> 
</Batch> 


The following DDL statement creates the Forecasting mining model. 


<Create xmlns="https://schemas.microsoft.com/analysisservices/2003/engine"> 
<ParentObject> 
<DatabaseID>Adventure Works DW Multidimensional 2012</DatabaseID> 
<MiningStructureID>Forecasting</MiningStructureID> 
</ParentObject> 
<ObjectDefinition> 
<MiningModel xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
xmlns:xsi="http: //www.w3.org/2001/XMLSchema-instance"> 
<ID>Forecasting</ID> 
<Name>Forecasting</Name> 
<Algorithm>Microsoft_Time_Series</Algorithm> 
<AlgorithmParameters> 
<AlgorithmParameter> 
<Name>PERIODICITY_HINT</Name> 
<Value xsi:type="xsd:string">{12}</Value> 
</AlgorithmParameter> 
</AlgorithmParameters> 
<Columns> 
<Column> 
<ID>Amount</ID> 
<Name>Amount</Name> 
<SourceColumnID>Amount</SourceColumnID> 
<Usage>Predict</Usage> 
</Column> 
<Column> 
<ID>Model Region</ID> 
<Name>Model Region</Name> 
<SourceColumnID>Model Region</SourceColumnID> 
<Usage>Key</Usage> 
</Column> 
<Column> 
<ID>Quantity</ID> 
<Name>Quantity</Name> 
<SourceColumnID>Quantity</SourceColumnID> 
<Usage>Predict</Usage> 
</Column> 
<Column> 
<ID>Time Index</ID> 
<Name>Time Index</Name> 
<SourceColumnID>Time Index</SourceColumnID> 
<Usage>Key</Usage> 
</Column> 
</Columns> 
<Collation>Latini_General_CS_AS_KS</Collation> 
</MiningModel> 
</ObjectDefinition> 
</Create> 


The following three DDL statements were generated by scripting objects in the Adventure Works DW 
Multidimensional 2012, the Analysis Services database included in SQL Server. 


The following DDL statement deletes the Promotion dimension. 


<Delete xmlns="https://schemas.microsoft.com/analysisservices/2003/engine"> 
<Object> 
<DatabaseID>Adventure Works DW Multidimensional 2012</DatabaseID> 
<DimensionID>Dim Promotion</DimensionID> 
</Object> 
</Delete> 


The following DDL statement processes the Adventure Works DW Multidimensional 2012 cube. 


<Batch xmlns="https://schemas.microsoft.com/analysisservices/2003/engine"> 
<Parallel> 
<Process xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema- 
instance"> 
<Object> 
<DatabaseID>Adventure Works DW Multidimensional 2012</DatabaseID> 
</Object> 
<Type>ProcessFull</Type> 
<WriteBackTableCreation>UseExisting</WriteBackTableCreation> 
</Process> 
</Parallel> 
</Batch> 


The following DDL statement creates the Forecasting mining model. 


<Create xmlns="https://schemas.microsoft.com/analysisservices/2003/engine"> 
<ParentObject> 
<DatabaseID>Adventure Works DW Multidimensional 2012</DatabaseID> 
<MiningStructureID>Forecasting</MiningStructureID> 
</ParentObject> 
<ObjectDefinition> 
<MiningModel xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
xmlns:xsi="http: //www.w3.org/2001/XMLSchema-instance"> 
<ID>Forecasting</ID> 
<Name>Forecasting</Name> 
<Algorithm>Microsoft_Time_Series</Algorithm> 
<AlgorithmParameters> 
<AlgorithmParameter> 
<Name>PERIODICITY_HINT</Name> 
<Value xsi:type="xsd:string">{12}</Value> 
</AlgorithmParameter> 
</AlgorithmParameters> 
<Columns> 
<Column> 
<ID>Amount</ID> 
<Name>Amount</Name> 
<SourceColumnID>Amount</SourceColumnID> 
<Usage>Predict</Usage> 
</Column> 
<Column> 
<ID>Model Region</ID> 
<Name>Model Region</Name> 
<SourceColumnID>Model Region</SourceColumnID> 
<Usage>Key</Usage> 
</Column> 
<Column> 
<ID>Quantity</ID> 
<Name>Quantity</Name> 
<SourceColumnID>Quantity</SourceColumnID> 
<Usage>Predict</Usage> 
</Column> 
<Column> 
<ID>Time Index</ID> 
<Name>Time Index</Name> 
<SourceColumnID>Time Index</SourceColumnID> 
<Usage>Key</Usage> 
</Column> 
</Columns> 
<Collation>Latini_General_CS_AS_KS</Collation> 
</MiningModel> 
</ObjectDefinition> 
</Create> 


Configuration of the Analysis Services Execute DDL Task 

You can set properties through SSIS Designer or programmatically. 

For more information about the properties that you can set in SSIS Designer, click the following topic: 
e Expressions Page 

For more information about setting these properties in SSIS Designer, click the following topic: 


e Set the Properties of a Task or Container 


Programmatic Configuration of the Analysis Services Execute DDL 
Task 


For more information about programmatically setting these properties, click the following topic: 


e ASExecuteDDLTask 


Analysis Services Execute DDL Task Editor (General Page) 


Use the General pageof the Analysis Services Execute DDL Task Editor dialog box to name and describe 
the Analysis Services Execute DDL task. 


Options 

Name 

Provide a unique name for the Analysis Services Execute DDL task. This name is used as the label in the task 
icon. 





NOTE 


Task names must be unique within a package. 





Description 


Type a description of the Analysis Services Execute DDL task. 


Analysis Services Execute DDL Task Editor (DDL Page) 


Use the DDL page of the Analysis Services Execute DDL Task Editor dialog box to specify a connection to 
an Analysis Services project or an Analysis Services database and to provide information about the source of 
data definition language (DDL) statements. 


Static Options 


Connection 
Select an Analysis Services project or an Analysis Services connection manager in the list, or click <New 
connection...> and use the Add Analysis Services Connection Manager dialog box to create a new 


connection. 


Related Topics: Add Analysis Services Connection Manager Dialog Box UI Reference, Analysis Services 
Connection Manager 


Sourcelype 
Specify the source type of the DDL statements. This property has the options listed in the following table: 


VALUE DESCRIPTION 


Direct Input Set the source to the DDL statement stored in the 
SourceDirect text box. Selecting this value displays the 
dynamic options in the following section. 


File Connection Set the source to a file that contains the DDL statement. 
Selecting this value displays the dynamic options in the 
following section. 


Variable Set the source to a variable. Selecting this value displays the 
dynamic options in the following section. 


Dynamic Options 

SourceType = Direct Input 

Source 

Type the DDL statements or click the ellipsis (...) and then type the statements in the DDL Statements dialog 
box. 


SourceType = File Connection 

Source 

Select a File connection in the list, or click <New connection...> and use the File Connection Manager 
dialog box to create a new connection. 


Related Topics: File Connection Manager 


SourceType = Variable 

Source 

Select a variable in the list, or click <New variable...> and use the Add Variable dialog box to create a new 
variable. 


Related Topics: Integration Services (SSIS) Variables 


Analysis Services Processing Task 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


The Analysis Services Processing task processes Analysis Services objects such as tabular models, cubes, 
dimensions, and mining models. 


When processing tabular models, keep the following in mind: 
e You cannot perform impact analysis on tabular models. 


e Some processing options for tabular mode are not exposed, such as Process Defrag and Process Recalc. 
You can perform these functions by using the Execute DDL task. 


e The options Process Index and Process Update are not appropriate for tabular models and should not be 
used. 


e Batch settings are ignored for tabular models. 
e Set the target server version to SQL Server 2019 for connecting to Azure Analysis Services. 


Integration Services includes a number of tasks that perform business intelligence operations, such as running 
Data Definition Language (DDL) statements and data mining prediction queries. For more information about 
related business intelligence tasks, click one of the following topics: 


e Analysis Services Execute DDL Task 


e Data Mining Query Task 


Object Processing 


Multiple objects can be processed at the same time. When processing multiple objects, you define settings that 
apply to the processing of all the objects in the batch. 


Objects in a batch can be processed in sequence or in parallel. If the batch does not contain objects for which 
processing sequence is important, parallel processing can speed up processing. If objects in the batch are 
processed in parallel, you can configure the task to let it determine how many objects to process in parallel, or 
you can manually specify the number of objects to process at the same time. If objects are processed 
sequentially, you can set a transaction attribute on the batch either by enlisting all objects in one transaction or 
by using a separate transaction for each object in the batch. 


When you process analytic objects, you might also want to process the objects that depend on them. The 
Analysis Services Processing task includes an option to process any dependent objects in addition to the 
selected objects. 


Typically, you process dimension tables before processing fact tables. You may encounter errors if you try to 
process fact tables before processing the dimension tables. 


This task also lets you configure the handling of errors in dimension keys. For example, the task can ignore 
errors or stop after a specified number of errors occur. The task can use the default error configuration, or you 
can construct a custom error configuration. In the custom error configuration, you specify how the task handles 
errors and the error conditions. For example, you can specify that the task should stop running when the fourth 
error occurs, or specify how the task should handle Null key values. The custom error configuration can also 
include the path of an error log. 





NOTE 


The Analysis Services Processing task can process only analytic objects created by using the SQL Server tools. 





This task is frequently used in combination with a Bulk Insert task that loads data into a SQL Server table, or a 


Data Flow task that implements a data flow that loads data into a table. For example, the Data Flow task might 
have a data flow that extracts data from an online transactional database (OLTP) database and loads it into a fact 
table in a data warehouse, after which the Analysis Services Processing task is called to process the cube built on 
the data warehouse. 


The Analysis Services Processing task uses an Analysis Services connection manager to connect to an instance 
of Microsoft SQL Server Analysis Services. For more information, see Analysis Services Connection Manager. 


Error Handling 


Configuration of the Analysis Services Processing Task 

You can set properties through SSIS Designer or programmatically. 

For more information about the properties that you can set in SSIS Designer, click the following topic: 
e Expressions Page 

For more information about setting these properties in SSIS Designer, click the following topic: 


e Set the Properties of a Task or Container 


Programmatic Configuration of the Analysis Services Processing Task 
For more information about programmatically setting these properties, click the following topic: 


e DTSProcessinglask 


Analysis Services Processing Task Editor (General Page) 


Use the General page of the Analysis Services Processing Task Editor dialog box to name and describe the 
Analysis Services Processing task. 


Options 
Name 
Provide a unique name for the Analysis Services Processing task. This name is used as the label in the task icon. 





NOTE 


Task names must be unique within a package. 





Description 


Type a description of the Analysis Services Processing task. 


Analysis Services Processing Task Editor (Analysis Services Page) 


Use the Analysis Services page of the Analysis Services Processing Task Editor dialog box to specify an 
Analysis Services connection manager, select the analytic objects to process, and set processing and error 
handling options. 


When processing tabular models, keep the following in mind: 
1. You cannot perform impact analysis on tabular models. 


2. Some processing options for tabular mode are not exposed, such as Process Defrag and Process Recalc. 
You can perform these functions by using the Execute DDL task. 


3. Some processing options provided, such as process indexes, are not appropriate for tabular models and 
should not be used. 


4. Batch settings are ignored for tabular models. 


Options 
Analysis Services connection manager 


Select an existing Analysis Services connection manager in the list or click New to create a new connection 
manager. 


New 


Create a new Analysis Services connection manager. 


Related Topics: Analysis Services Connection Manager, Add Analysis Services Connection Manager Dialog Box 
UI Reference 


Object list 
PROPERTY DESCRIPTION 
Object Name Lists the specified object names. 
Type Lists the types of the specified objects. 
Process Options Select a processing option in the list. 
Related Topics: Processing a multidimensional model 
(Analysis Services) 
Settings Lists processing settings for the specified objects. 
Add 


Add an Analysis Services object to the list. 


Remove 
Select an object, and then click Delete. 


Impact Analysis 
Perform impact analysis on the selected object. 


Related Topics: Impact Analysis Dialog Box (Analysis Services - Multidimensional Data) 


Batch Settings Summary 


PROPERTY DESCRIPTION 


Processing order Specifies whether objects are processed sequentially or in a 
batch; if parallel processing is used, specifies the number of 
objects to process concurrently. 


Transaction mode Specifies the transaction mode for sequential processing. 


PROPERTY DESCRIPTION 


Dimension errors Specifies the task behavior when errors occur. 

Dimension key error log path Specifies the path of the file to which errors are logged. 

Process affected objects Indicates whether dependent or affected objects are also 
processed. 


Change Settings 
Change the processing options and the handling of errors in dimension keys. 


Related Topics: Change Settings Dialog Box (Analysis Services - Multidimensional Data) 


Azure Blob Download Task 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 
The Azure Blob Download Task enables an SSIS package to download files from Azure Blob Storage. 


To add an Azure Blob Download Task, drag-drop it to the SSIS Designer, and double-click or right-click and 
click Edit to see the following Azure Blob Download Task Editor dialog box. 


The Azure Blob Download Task is a component of the SQL Server Integration Services (SSIS) Feature Pack for 
Azure. 


The following table provides description for the fields in this dialog box. 
FIELD DESCRIPTION 


AzureStorageConnection Specify an existing Azure Storage Connection Manager or 
create a new one that refers to an Azure Storage Account, 
which points to where the blob files are hosted. 


BlobContainer Specifies the name of the blob container that contains the 
blob files to be downloaded. 


BlobDirectory Specifies the blob directory that contains the blob files to be 
downloaded. The blob directory is a virtual hierarchical 
structure. 

SearchRecursively Specifies whether to search recursively within sub-directories. 

LocalDirectory Specifies the local directory where the downloaded blob files 
are stored. 

FileName Specifies a name filter to select files with the specified name 


pattern. For example, MySheet*.x1ls\* includes files such as 
MySheet@@1.xls and MySheetABC.xlsx . 


TimeRangeFrom/TimeRangeTo Specifies a time range filter. Files modified after 
TimeRangeFrom and before TimeRangeTo are included. 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 
The Azure Blob Upload Task enables an SSIS package to upload files to Azure Blob Storage. 


To add an Azure Blob Upload Task, drag-drop it to the SSIS Designer, and double-click or right-click and click 
Edit to see the following Azure Blob Upload Task Editor dialog box. 


The Azure Blob Upload Task is a component of the SQL Server Integration Services (SSIS) Feature Pack for 
Azure. 


The following table provides descriptions for the fields in this dialog box. 
FIELD DESCRIPTION 


AzureStorageConnection Specify an existing Azure Storage Connection Manager or 
create a new one that refers to an Azure Storage Account, 
which points to where the blob files are hosted. 


BlobContainer Specifies the name of the blob container that contains the 
uploaded files as blobs. 


BlobDirectory Specifies the blob directory where the uploaded file is stored 
as a block blob. The blob directory is a virtual hierarchical 
structure. If the blob already exists, it is replaced. 


LocalDirectory Specify the local directory that contains the files to be 
uploaded. 

SearchRecursively Specify whether to search recursively within sub-directories. 

FileName Specifies a name filter to select files with the specified name 


pattern. For example, mMySheet*.x1ls\* includes files such as 
MySheet@@1.xls and MySheetABC.xlsx . 


TimeRangeFrom/TimeRangeTo Specifies a time range filter. Files modified after 
TimeRangeFrom and before TimeRangeTo are included. 


Azure Data Lake Analytics task 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


You can submit U-SQL jobs to Azure Data Lake Analytics service with the Data Lake Analytics task. This task is a 
component of the SQL Server Integration Services (SSIS) feature pack for Azure. 


For general background, see Azure Data Lake Analytics. 


Configure the task 


To add a Data Lake Analytics task to a package, drag the task from SSIS Toolbox to the designer canvas. Then 
double-click the task, or right-click the task and select Edit. The Azure Data Lake Analytics Task Editor 
dialog box opens. You can set properties through SSIS Designer, or programmatically. 


General page configuration 


Use the General page to configure the task and provide the U-SQL script that the task submits. To learn more 
about the U-SQL language, see U-SQL language reference. 


Basic configuration 


You can specify the name and description of the task. 


U-SQL configuration 


U-SQL configuration has two settings: SourceType, and dynamic options based on the SourceType value. 


SourceType specifies the source of the U-SQL script. The script is submitted to a Data Lake Analytics account 
during SSIS package execution. The options for this property are: 


VALUE DESCRIPTION 


DirectInput Specifies the U-SQL script through the inline editor. Selecting 
this value displays the dynamic option, USQLStatement. 


FileConnection Specifies a local .usq] file that contains the U-SQL script. 
Selecting this option displays the dynamic option, 
FileConnection. 


Variable Specifies an SSIS variable that contains the U-SQL script. 
Selecting this value displays the dynamic option, 
SourceVariable. 


SourceType Dynamic Options specifies the script content for the U-SQL query. 
SOURCETYPE DYNAMIC OPTIONS 


SourceType = DirectInput Type the U-SQL query to be submitted in the option box 
directly, or select the browse button (...) to type the U-SQL 
query in the Enter U-SQL Query dialog box. 


SOURCETYPE DYNAMIC OPTIONS 


SourceType = FileConnection Select an existing file connection manager, or select <New 
connection...> to create a new file connection. For related 
information, see File Connection Manager and File 
Connection Manager Editor. 


SourceType = Variable Select an existing variable, or select <New variable...> to 
create a new variable. For related information, see 
Integration Services (SSIS) Variables and Add Variable. 


Job configuration 


Job configuration specifies U-SQL job submission properties. 


e AzureDataLakeAnalyticsConnection: Specifies the Data Lake Analytics account where the U-SQL 
script is submitted. Choose the connection from a list of defined connection managers. To create a new 
connection, select <New connection >. For related information, see Azure Data Lake Analytics 
Connection Manager. 


e JobName: Specifies the name of the U-SQL job. 
e AnalyticsUnits: Specifies the analytics unit count of the U-SQL job. 


e Priority: Specifies the priority of the U-SQL job. You can set this from 0 to 1000. The lower the number 
is, the higher the priority. 


e RuntimeVersion: Specifies the Data Lake Analytics runtime version of the U-SQL job. It is set to 
"default" by default. Usually you don't need to change this property. 


e Synchronous: A Boolean value specifies if the task waits for the job execution to complete or not. If the 
value is set to true, the task is marked as succeed after the job completes. If the value is set to false, the 
task is marked as succeed after the job passes the preparation phase. 


VALUE DESCRIPTION 


True The task result is based on the U-SQL job execution 
result. Job succeeds > task succeeds. Job fails > task fails. 
Task succeeds or fails > task completes. 


False The task result is based on the U-SQL job submission 
and preparation result. Job submission succeeds and 
passes the preparation phase > task succeeds. Job 
submission fails or job fails at the preparation phase > 
task fails. Task succeeds or fails > task completes. 


e TimeOut: Specifies a time-out time, in seconds, for job execution. If the job times out, it is cancelled and 
marked as failed. This property is not available if Synchronous is set to false. 


Parameter Mapping page configuration 


Use the Parameter Mapping page of the Azure Data Lake Analytics Task Editor dialog box to map 
variables to parameters (U-SQL variables) in U-SQL script. 


e Variable Name: After you have added a parameter mapping by selecting Add, select a system or user- 
defined variable from the list. Alternatively, you can select <New variable...> to add a new variable by 
using the Add Variable dialog box. For related information, see Integration Services (SSIS) Variables. 


e Parameter Name: Provide a parameter/variable name in U-SQL script. Make sure the parameter name 
starts with the @ sign, like @Param1. 


Here is an example of how to pass parameters to U-SQL script. 


Sample U-SQL script 


@searchlog = 

EXTRACT UserId int, 
Start DateTime, 
Region string, 
Query string, 
Duration int; 
Urls string, 
ClickedUrls string 

FROM @in 


USING Extractors.Tsv(nullEscape: "#NULL#") ; 


@rs1 = 
SELECT Start, Region, Duration 
FROM @searchlog 


WHERE Region == "en-gb"; 

@rsi = 
SELECT Start, Region, Duration 
FROM @rs1 


WHERE Start <= DateTime.Parse("2012/02/19"); 


OUTPUT @rs1 
TO @out 
USING Outputters.Tsv(quoting: false, dateTimeFormat:null1); 


Note that the input and output paths are defined in @in and @out parameters. The values for @in and @out 
parameters in the U-SQL script are passed dynamically by the parameter mapping configuration. 


VARIABLE NAME PARAMETER NAME 
User: Variable @in 
User: Variable2 @out 


Expression page configuration 


You can assign all properties in the General page configuration as a property expression, to enable dynamic 
update of the property at runtime. For related information, see Use Property Expressions in Packages. 


See also 


e Azure Data Lake Analytics Connection Manager 
e Azure Data Lake Store File System Task 


e Azure Data Lake Store Connection Manager 


Azure Data Lake Store File System Task 


11/23/2021 * 2 minutes to read « Edit Online 





Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


The Azure Data Lake Store File System Task lets users perform various file system operations on Azure Data 
Lake Store (ADLS). 


The Azure Data Lake Store File System Task is a component of the SQL Server Integration Services (SSIS) 
Feature Pack for Azure. 


Configure the Azure Data Lake Store File System Task 


To add an Azure Data Lake Store File System Task to a package, drag it from SSIS Toolbox to the designer canvas. 
Then double-click the task, or right-click the task and select Edit, to open the Azure Data Lake Store File 
System Task Editor dialog box. 


The Operation property specifies the file system operation to perform. Select one of the following operations: 


e CopyToADLS: Upload files to ADLS. 
e CopyFromADLS: Download files from ADLS. 


Configure the properties for the operation 
For any operation, you have to specify an Azure Data Lake connection manager. 
Here are the properties specific to each operation: 


CopyToADLS 


e LocalDirectory: Specifies the local source directory which contains files to upload. 


e FileNamePattern: Specifies a file name filter for source files. Only files whose name matches the specified 
pattern are uploaded. Wildcards * and ? are supported. 


e SearchRecursively: Specifies whether to search recursively within the source directory for files to upload. 

e AzureDataLakeDirectory: Specifies the ADLS destination directory to upload files to. 

e FileExpiry: Specifies an expiration date and time for the files uploaded to ADLS. Leave this property blank to 
indicate that the files never expire. 

CopyFromADLS 


e AzureDataLakeDirectory: Specifies the ADLS source directory which contains the files to download. 


e SearchRecursively: Specifies whether to search recursively within the source directory for files to 
download. 


e LocalDirectory: Specifies the destination directory to store downloaded files. 


Azure HDInsight Create Cluster Task 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


The Azure HDInsight Create Cluster Task enables an SSIS package to create an Azure HDInsight cluster in 
the specified Azure subscription and resource group. 


The Azure HDInsight Create Cluster Task is a component of the SQL Server Integration Services (SSIS) 
Feature Pack for Azure. 





NOTE 
© Creating a new HDInsight cluster may take 10~20 minutes. 


e There is a cost associated with creating and running an Azure HDInsight cluster. See HDInsight Pricing for details. 





To add an Azure HDInsight Create Cluster Task, drag-drop it to the SSIS Designer, and double-click or right- 
click and click Edit to see the following Azure HDInsight Create Cluster Task Editor dialog box. 


The following table provides a description of the fields in this dialog box. 
FIELD DESCRIPTION 


AzureResourceManagerConnection Select an existing Azure Resource Manager Connection 
Manager or create a new one that will be used to create the 
HDInsight cluster. 


AzureStorageConnection Select an existing Azure Storage Connection Manager or 
create a new one that refers to an Azure Storage Account 
that will be associated with the HDInsight cluster. 


Subscriptionld Specify the ID of the subscription the HDInsight cluster will 
be created in. 


ResourceGroup Specify the Azure resource group the HDInsight cluster will 
be created in. 


Location Specify the location of the HDInsight cluster. The cluster 
must be created in the same location as the Azure Storage 
Account specified. 


ClusterName Specify a name for the HDInsight cluster to be created. 
ClusterSize Specify the number of nodes to create in the cluster. 
BlobContainer Specify the name of the default storage container to be 


associated with the HDInsight cluster. 


UserName Specify the user name to be used for connecting to the 
HDInsight cluster. 





FIELD 


DESCRIPTION 








Password Specify the password to be used for connecting to the 
HDInsight cluster. 

SshUserName Specify the user name used to remotely access the 
HDInsight cluster using SSH. 

SshPassword Specify the password used to remotely access the HDInsight 
cluster using SSH. 

FaillfExists Specify whether the task should fail if the cluster already 
exists. 

NOTE 


The locations of the HDInsight cluster and the Azure Storage Account must be the same. 








Azure HDInsight Delete Cluster Task 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


The Azure HDInsight Delete Cluster Task enables an SSIS package to delete an Azure HDinsight cluster in 
the specified Azure subscription and resource group. 


The Azure HDInsight Delete Cluster Task is a component of the SQL Server Integration Services (SSIS) 
Feature Pack for Azure. 





NOTE 
Deleting an HDInsight cluster may take 10~20 minutes. 











To add an Azure HDInsight Delete Cluster Task, drag-drop it to the SSIS Designer, and double-click or right- 
click and click Edit to see the following Azure HDInsight Delete Cluster Task Editor dialog box. 


The following table provides a description for the fields in the dialog box. 
FIELD DESCRIPTION 


AzureResourceManagerConnection Select an existing Azure Resource Manager Connection 
Manager or create a new one that will be used to delete the 
HDInsight cluster. 


Subscriptionld Specify the ID of the subscription the HDInsight cluster is in. 
ResourceGroup Specify the Azure resource group the HDiInsight cluster is in. 
ClusterName Specify the name of the cluster to be deleted. 

FaillfNotExists Specify whether the task should fail if the cluster does not 


exist. 


Azure HDInsight Hive Task 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 
Use the Azure HDInsight Hive Task to run Hive script on an Azure HDInsight cluster. 


To add an Azure HDInsight Hive Task, drag-drop it to the SSIS Designer, and double-click or right-click and 
click Edit to see the following Azure HDInsight Hive Task Editor dialog box. 


The Azure HDInsight Hive Task is a component of the SQL Server Integration Services (SSIS) Feature Pack for 
Azure. 


The following list describes fields in this dialog box. 


1. For the HDInsightConnection field, select an existing Azure HDInsight Connection Manager or create a 
new one that refers to the Azure HDInsight cluster used to execute the script. 


2. For the AzureStorageConnection field, select an existing Azure Storage Connection Manager or create 
a new one that refers to the Azure Storage Account associated with the cluster. This is only necessary if 
you want to download the script execution output and error logs. 


3. For the BlobContainer field, specify the storage container name associated with the cluster. This is only 
necessary if you want to download the script execution output and error logs. 


4. For the LocalLogFolder field, specify the folder to which the script execution output and error logs will 
be downloaded to. This is only necessary if you want to download the script execution output and error 
logs. 


5. There are two ways to specify the Hive script to execute: 


a. In-line script: Specify the Script field by typing in-line the script to execute in the Enter Script 
dialog box. 


b. Script file: Upload the script file to Azure Blob Storage and specify the BlobName field. If the 
blob is not in the default storage account or container associated with the HDInsight cluster, the 
ExternalStorageAccountName and ExternalBlobContainer fields must be specified. For an 
external blob, make sure that it is configured as publicly accessible. 


If both are specified, script file will be used and the in-line script will be ignored. 


Azure HDInsight Pig Task 


11/23/2021 * 2 minutes to read « Edit Online 





Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 
Use the Azure HDInsight Pig Task to run Pig script on an Azure HDInsight cluster. 


To add an Azure HDInsight Pig Task, drag-drop it to the SSIS Designer, and double-click or right-click and 
click Edit to see the following Azure HDInsight Pig Task Editor dialog box. 


The Azure HDInsight Pig Task is a component of the SQL Server Integration Services (SSIS) Feature Pack for 
Azure. 


The following list describes fields in this dialog box. 


1. For the HDInsightConnection field, select an existing Azure HDInsight Connection Manager or create a 
new one that refers to the Azure HDInsight cluster used to execute the script. 


2. For the AzureStorageConnection field, select an existing Azure Storage Connection Manager or create 
a new one that refers to the Azure Storage Account associated with the cluster. This is only necessary if 
you want to download the script execution output and error logs. 


3. For the BlobContainer field, specify the storage container name associated with the cluster. This is only 
necessary if you want to download the script execution output and error logs. 


4. For the LocalLogFolder field, specify the folder to which the script execution output and error logs will 
be downloaded to. This is only necessary if you want to download the script execution output and error 
logs. 


5. There are two ways to specify the Pig script to execute: 


a. In-line script: Specify the Script field by typing in-line the script to execute in the Enter Script 
dialog box. 


b. Script file: Upload the script file to Azure Blob Storage and specify the BlobName field. If the 
blob is not in the default storage account or container associated with the HDInsight cluster, the 
ExternalStorageAccountName and ExternalBlobContainer fields must be specified. For an 
external blob, make sure that it is configured as publicly accessible. 


If both are specified, script file will be used and the in-line script will be ignored. 


Azure Synapse Analytics Task 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


The Azure Synapse Analytics Task enables an SSIS package to copy tabular data to Azure Synapse Analytics 
dedicated SQL pool from file system or Azure Blob Storage. The task leverages PolyBase to improve 
performance, as described in the article Azure Synapse Analytics Loading Patterns and Strategies. The currently 
supported source data file format is delimited text in UTF8 encoding. When copying from file system, data will 
first be uploaded to Azure Blob Storage for staging, and then to dedicated SQL pool. Therefore, an Azure Blob 
Storage account is needed. 


NOTE 


Azure Storage connection manager with Data Lake Gen2 service type is not supported. 


To use Azure Data Lake Gen2 for staging or source, you can connect via Azure Storage connection manager with Blob 
Storage service type. 











The Azure Synapse Analytics Task is a component of the SQL Server Integration Services (SSIS) Feature Pack 
for Azure. 


To add an Azure Synapse Analytics Task, drag-drop it from SSIS Toolbox to the designer canvas, and double- 
click or right-click and click Edit to see the task editor dialog box. 


On the General page, configure the following properties. 
The SourceType specifies the type of source data store. Select one of the following types: 


e FileSystem: Source data resides in local file system. 


e BlobStorage: Source data resides in Azure Blob Storage. 


Following are the properties for each source type. 


FileSystem 

FIELD DESCRIPTION 

LocalDirectory Specifies the local directory that contains the data files to be 
uploaded. 

Recursively Specifies whether to recursively search sub-directories. 

FileName Specifies a name filter to select files with certain name 
pattern. E.g. MySheet*.xs|* will include files such as 
MySheet001.xs! and MySheetABC.xsIx. 

RowDelimiter Specifies the character(s) that marks the end of each row. 

ColumnDelimiter Specifies one or more characters that mark the end of each 


column. E.g. | (pipe), \t (tab), ' (single quote), " (double 
quote), and Ox5c (backslash). 


FIELD 


IsFirstRowHeader 


AzureStorageConnection 


BlobContainer 


BlobDirectory 


RetainFiles 


CompressionType 


CompressionLevel 


SqlPoolConnection 


TableName 


TableDistribution 


HashColumnName 


BlobStorage 


FIELD 


AzureStorageConnection 


BlobContainer 


BlobDirectory 


RowDelimiter 


ColumnDelimiter 


DESCRIPTION 


Specifies whether the first row in each data file contains 
column names instead of actual data. 


Specifies an Azure Storage connection manager. 


Specifies the name of blob container to which local data will 
be uploaded and relayed to Azure Synapse Analytics 
dedicated SQL pool via PolyBase. A new container will be 
created if it does not exist. 


Specifies the blob directory (virtual hierarchical structure) to 
which local data will be uploaded and relayed to Azure 
Synapse Analytics dedicated SQL pool via PolyBase. 


Specifies whether to retain the files uploaded to Azure 
Storage. 


Specifies the compression format to use upon uploading files 
to Azure Storage. Local source is not affected. 


Specifies the compression level to use for the compression 
format. 


Specifies an ADO.NET connection manager for Azure 
Synapse Analytics dedicated SQL pool. 


Specifies name of the destination table. Either choose an 
existing table name, or create a new one by choosing <New 
Table ...>. 


Specifies the distribution method for new table. Applies if a 
new table name is specified for TableName. 


Specifies the column used for hash table distribution. Applies 
if HASH is specified for TableDistribution. 


DESCRIPTION 


Specifies an Azure Storage connection manager. 


Specifies the name of blob container where source data 
resides. 


Specifies the blob directory (virtual hierarchical structure) 
where source data resides. 


Specifies the character(s) that marks the end of each row. 


Specifies one or more characters that mark the end of each 
column. E.g. | (pipe), \t (tab), ' (single quote), " (double 
quote), and Ox5c (backslash). 


FIELD 


CompressionType 


SqlPoolConnection 


TableName 


TableDistribution 


HashColumnName 


DESCRIPTION 


Specifies the compression format used for source data. 


Specifies an ADO.NET connection manager for Azure 
Synapse Analytics dedicated SQL pool. 


Specifies name of the destination table. Either choose an 
existing table name, or create a new one by choosing <New 
Table ...>. 


Specifies the distribution method for new table. Applies if a 
new table name is specified for TableName. 


Specifies the column used for hash table distribution. Applies 
if HASH is specified for TableDistribution. 


You will see a different Mappings page depending on whether you are copying to a new table or to an existing 


one. In the former case, configure which source columns are to be mapped and their corresponding names in 


the to-be-created destination table. In the latter case, configure the mapping relationships between source and 


destination columns. 


On the Columns page, configure the data type properties for each source column. 


The T-SQL page shows the T-SQL used to load data from Azure Blob Storage to dedicated SQL pool. The T-SQL 
is automatically generated from configurations on the other pages, and will be executed as part of the task 


execution. You may choose to manually edit the generated T-SQL to meet your particular needs by clicking the 


Edit button. You can revert to the automatically generated one later on by clicking the Reset button. 


Flexible File Task 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


The Flexible File Task enables users to perform file operations on various supported storage services. Currently 
supported storage services are 


e Local File System 
e Azure Blob Storage 
e Azure Data Lake Storage Gen2 


The Flexible File Task is a component of the SQL Server Integration Services (SSIS) Feature Pack for Azure. 


To add a Flexible File Task to a package, drag it from SSIS Toolbox to the designer canvas. Then double-click the 
task, or right-click the task and select Edit, to open the Flexible File Task Editor dialog box. 


The Operation property specifies the file operation to perform. Currently supported operations are: 


e Copy Operation 


e Delete Operation 
For Copy operation, following properties are available. 


e SourceConnectionType: Specifies the source connection manager type. 

e SourceConnection: Specifies the source connection manager. 

e SourceFolderPath: Specifies the source folder path. 

e SourceFileName: Specifies the source file name. If left blank, the source folder will be copied. Following 
wildcards are allowed in source file name: * (matches zero or more characters), ? (matches zero or single 
character) and * (escape character). 

e SearchRecursively: Specifies whether to recursively copy subfolders. 

e DestinationConnectionType: Specifies the destination connection manager type. 

e DestinationConnection: Specifies the destination connection manager. 

e DestinationFolderPath: Specifies the destination folder path. 


e DestinationFileName: Specifies the destination file name. If left blank, the source file names will be used. 
For Delete operation, following properties are available. 


e ConnectionType: Specifies the connection manager type. 
e Connection: Specifies the connection manager. 
e FolderPath: Specifies the folder path. 
e FileName: Specifies the file name. If left blank, the folder will be deleted. For Azure Blob Storage, delete 
folder is not supported. Following wildcards are allowed in file name: * (matches zero or more characters), 
? (matches zero or single character) and * (escape character). 


e DeleteRecursively: Specifies whether to recusively delete files. 
Notes on Service Principal Permission Configuration 


For Test Connection to work (either blob storage or Data Lake Storage Gen2), the service principal should be 
assigned at least Storage Blob Data Reader role to the storage account. This is done with RBAC. 


For blob storage, read and write permissions are granted by assigning at least Storage Blob Data Reader and 


Storage Blob Data Contributor roles, respectively. 


For Data Lake Storage Gen2, permission is determined by both RBAC and ACLs. Pay attention that ACLs are 
configured using the Object ID (OID) of the service principal for the app registration as detailed here. This is 
different from the Application (client) ID that is used with RBAC configuration. When a security principal is 
granted RBAC data permissions through a built-in role, or through a custom role, these permissions are 
evaluated first upon authorization of a request. If the requested operation is authorized by the security 
principal's RBAC assignments, then authorization is immediately resolved and no additional ACL checks are 
performed. Alternatively, if the security principal does not have an RBAC assignment, or the request's operation 
does not match the assigned permission, then ACL checks are performed to determine if the security principal is 
authorized to perform the requested operation. 


e For read permission, grant at least Execute permission starting from the source file system, along with Read 
permission for the files to copy. Alternatively, grant at least the Storage Blob Data Reader role with RBAC. 

e For write permission, grant at least Execute permission starting from the sink file system, along with Write 
permission for the sink folder. Alternatively, grant at least the Storage Blob Data Contributor role with 
RBAC. 


See this article for details. 


Back Up Database Task 
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Applies to: Q@ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


The Back Up Database task performs different types of SQL Server database backups. For more information, see 
Back Up and Restore of SQL Server Databases. 


By using the Back Up Database task, a package can back up a single database or multiple databases. If the task 


backs up only a single database, you can choose the backup component: the database, or its files and filegroups. 


Supported Recover Models and Backup Types 


The following table lists the recovery models and backup types that the Back Up Database task supports. 


DATABASE FILE OR FILE 
RECOVERY MODEL DATABASE DIFFERENTIAL TRANSACTION LOG DIFFERENTIAL 
Simple Required Optional Not supported Not supported 
Full Required Optional Required Optional 
Bulk-logged Required Optional Required Optional 


The Back Up Database task encapsulates a Transact-SQL BACKUP statement. For more information, see BACKUP 
(Transact-SQL). 


Configuration of the Back Up Database Task 


You can set properties through SSIS Designer. This task is in the Maintenance Plan Tasks section of the 
Toolbox in SSIS Designer. 


For more information about the properties that you can set in SSIS Designer, click the following topic: 
e Back Up Database Task (Maintenance Plan) 
For more information about how to set these properties in SSIS Designer, click the following topic: 


e Set the Properties of a Task or Container 


Bulk Insert Task 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


The Bulk Insert task provides an efficient way to copy large amounts of data into a SQL Server table or view. For 
example, suppose your company stores its million-row product list on a mainframe system, but the company's 
e-commerce system uses SQL Server to populate Web pages. You must update the SQL Server product table 
nightly with the master product list from the mainframe. To update the table, you save the product list in a tab- 
delimited format and use the Bulk Insert task to copy the data directly into the SQL Server table. 


To ensure high-speed data copying, transformations cannot be performed on the data while it is moving from 
the source file to the table or view. 


Usage Considerations 


Before you use the Bulk Insert task, consider the following: 


e The Bulk Insert task can transfer data only from a text file into a SQL Server table or view. To use the Bulk 
Insert task to transfer data from other database management systems (DBMSs), you must export the data 
from the source to a text file and then import the data from the text file into a SQL Server table or view. 


e The destination must be a table or view in a SQL Server database. If the destination table or view already 
contains data, the new data is appended to the existing data when the Bulk Insert task runs. If you want to 
replace the data, run an Execute SQL task that runs a DELETE or TRUNCATE statement before you run the 
Bulk Insert task. For more information, see Execute SQL Task. 


e You can use a format file in the Bulk Insert task object. If you have a format file that was created by the 
bcp utility, you can specify its path in the Bulk Insert task. The Bulk Insert task supports both XML and 
nonXML format files. For more information about format files, see Format Files for Importing or 
Exporting Data (SQL Server). 


e Only members of the sysadmin fixed server role can run a package that contains a Bulk Insert task. 


Bulk Insert Task with Transactions 


If a batch size is not set, the complete bulk copy operation is treated as one transaction. A batch size of 0 
indicates that the data is inserted in one batch. If a batch size is set, each batch represents a transaction that is 
committed when the batch finishes running. 


The behavior of the Bulk Insert task, as it relates to transactions, depends on whether the task joins the package 
transaction. If the Bulk Insert task does not join the package transaction, each error-free batch is committed as a 
unit before the next batch is tried. If the Bulk Insert task joins the package transaction, error-free batches remain 
in the transaction at the conclusion of the task. These batches are subject to the commit or rollback operation of 
the package. 


A failure in the Bulk Insert task does not automatically roll back successfully loaded batches; similarly, if the task 
succeeds, batches are not automatically committed. Commit and rollback operations occur only in response to 
package and workflow property settings. 


Source and Destination 


When you specify the location of the text source file, consider the following: 


e The server must have permission to access both the file and the destination database. 


@ The server runs the Bulk Insert task. Therefore, any format file that the task uses must be located on the 
server. 


@ The source file that the Bulk Insert task loads can be on the same server as the SQL Server database into 
which data is inserted, or on a remote server. If the file is on a remote server, you must specify the file 
name using the Universal Naming Convention (UNC) name in the path. 


Performance Optimization 
To optimize performance, consider the following: 


e If the text file is located on the same computer as the SQL Server database into which data is inserted, the 


copy operation occurs at an even faster rate because the data is not moved over the network. 


e The Bulk Insert task does not log error-causing rows. If you must capture this information, use the error 
outputs of data flow components to capture error-causing rows in an exception file. 


Custom Log Entries Available on the Bulk Insert Task 


The following table lists the custom log entries for the Bulk Insert task. For more information, see Integration 
Services (SSIS) Logging. 


LOG ENTRY DESCRIPTION 

BulkinsertTaskBegin Indicates that the bulk insert began. 
BulkInsertTaskEnd Indicates that the bulk insert finished. 
BulkInsertTaskInfos Provides descriptive information about the task. 


Bulk Insert Task Configuration 


You can configure the Bulk Insert task in the following ways: 


e Specify the OLE DB connection manager to connect to the destination SQL Server database and the table 
or view into which data is inserted. The Bulk Insert task supports only OLE DB connections for the 
destination database. 


e Specify the File or Flat File connection manager to access the source file. The Bulk Insert task uses the 
connection manager only for the location of the source file. The task ignores other options that you select 
in the connection manager editor. 


e Define the format that is used by the Bulk Insert task, either by using a format file or by defining the 
column and row delimiters of the source data. If using a format file, specify the File connection manager 
to access the format file. 


e Specify actions to perform on the destination table or view when the task inserts the data. The options 
include whether to check constraints, enable identity inserts, keep nulls, fire triggers, or lock the table. 


e Provide information about the batch of data to insert, such as the batch size, the first and last row from 
the file to insert, the number of insert errors that can occur before the task stops inserting rows, and the 
names of the columns that will be sorted. 


If the Bulk Insert task uses a Flat File connection manager to access the source file, the task does not use the 


format specified in the Flat File connection manager. Instead, the Bulk Insert task uses either the format specified 
in a format file, or the values of the RowDelimiter and ColumnDelimiter properties of the task. 


You can set properties through SSIS Designer or programmatically. 

For more information about the properties that you can set in SSIS Designer, click the following topic: 
e Expressions Page 

For more information about how to setthese properties in SSIS Designer, click the following topic: 

e Set the Properties of a Task or Container 


Programmatic Configuration of the Bulk Insert Task 


For more information about programmatically setting these properties, click the following topic: 


e BulkinsertTask 


Related Tasks 


Set the Properties of a Task or Container 


Related Content 


@ Technical article, You may get "Unable to prepare the SSIS bulk insert for data insertion" error on UAC 
enabled systems, on support.microsoft.com. 


@ Technical article, The Data Loading Performance Guide, on msdn.microsoft.com. 


e Technical article, Using SQL Server Integration Services to Bulk Load Data, on simple-talk.com. 


Bulk Insert Task Editor (Connection Page) 


Use the Connection page of the Bulk Insert Task Editor dialog box to specify the source and destination of 
the bulk insert operation and the format to use. 


To learn about working with bulk inserts, see Bulk Insert Task and Format Files for Importing or Exporting Data 
(SQL Server). 


Options 
Connection 


Select an OLE DB connection manager in the list, or click <New connection...> to create a new connection. 
Related Topics: OLE DB Connection Manager 


DestinationTable 
Type the name of the destination table or view or select a table or view in the list. 


Format 
Select the source of the format for the bulk insert. This property has the options listed in the following table. 


VALUE DESCRIPTION 


Use File Select a file containing the format specification. Selecting this 
option displays the dynamic option, FormatFile. 


Specify Specify the format. Selecting this option displays the 
dynamic options, RowDelimiter and ColumnDelimiter. 


File 
Select a File or Flat File connection manager in the list, or click <New connection...> to create a new 


connection. 


The file location is relative to the SQL Server Database Engine specified in the connection manager for this task. 
The text file must be accessible by the SQL Server Database Engine either on a local hard drive on the server, or 
via a share or mapped drive to the SQL Server. The file is not accessed by the SSIS Runtime. 


If you access the source file by using a Flat File connection manager, the Bulk Insert task does not use the format 
specified in the Flat File connection manager. Instead, the Bulk Insert task uses either the format specified in a 
format file or the values of the RowDelimiter and ColumnDelimiter properties of the task. 


Related Topics: File Connection Manager, Flat File Connection Manager 


Refresh Tables 
Refresh the list of tables and views. 


Format Dynamic Options 

Format = Use File 

FormatFile 

Type the path of the format file or click the ellipsis button (...) to locate the format file. 


Format = Specify 
RowDelimiter 
Specify the row delimiter in the source file. The default value is {CR}{LF}. 


ColumnDelimiter 


Specify the column delimiter in the source file. The default is Tab. 


Bulk Insert Task Editor (General Page) 
Use the General page of the Bulk Insert Task Editor dialog box to name and describe the Bulk Insert task. 
Options 


Name 
Provide a unique name for the Bulk Insert task. This name is used as the label in the task icon. 





NOTE 


Task names must be unique within a package. 





Description 


Type a description of the Bulk Insert task. 


Bulk Insert Task Editor (Options Page) 


Use the Options page of the Bulk Insert Task Editor dialog box to set properties for the bulk insert operation. 
The Bulk Insert task copies large amounts of data into a Microsoft SQL Server table or view. 


To learn about working with bulk inserts, see Bulk Insert Task and BULK INSERT (Transact-SQL). 


Options 
CodePage 
Specify the code page of the data in the data file. 


DataFileType 
Specify the data-type value to use in the load operation. 


BatchSize 


Specify the number of rows in a batch. The default is the entire data file. lf you set BatchSize to zero, the data is 


loaded in a single batch. 


LastRow 


Specify the last row to copy. 


FirstRow 


Specify the first row from which to start copying. 


Options 


TERM 


Check constraints 


Keep nulls 


Enable identity insert 


Table lock 


Fire triggers 


SortedData 


DEFINITION 


Select to check the table and column constraints. 


Select to retain null values during the bulk insert operation, 
instead of inserting any default values for empty columns. 


Select to insert existing values into an identity column. 


Select to lock the table during the bulk insert. 


Select to fire any insert, update, or delete triggers on the 
table. 


Specify the ORDER BY clause in the bulk insert statement. The column name that you supply must be a valid 
column in the destination table. The default is false. This means that the data is not sorted by an ORDER BY 


clause. 


MaxErrors 


Specify the maximum number of errors that can occur before the bulk insert operation is canceled. A value of 0 


indicates that an infinite number of errors are allowed. 





NOTE 


Each row that cannot be imported by the bulk load operation is counted as one error. 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


The CDC Control task is used to control the life cycle of change data capture (CDC) packages. It handles CDC 
package synchronization with the initial load package, the management of Log Sequence Number (LSN) ranges 
that are processed in a run of a CDC package. In addition, the CDC Control task deals with error scenarios and 
recovery. 


The CDC Control task maintains the state of the CDC package in an SSIS package variable and it can also persist 
it in a database table so that the state is maintained across package activations and between multiple packages 
that together perform a common CDC process (for example, one task may be responsible for the initial loading 
and the other for the trickle-feed updates). 


The CDC Control task supports two groups of operations. One group handles the synchronization of initial load 
and change processing, and the other manages the change-processing range of LSNs for a run of a CDC 
package and keeps track of what was processed successfully. 


The following operations handle the synchronization of initial load and change processing: 
OPERATION DESCRIPTION 


ResetCdcState This operation is used to reset the persistent CDC state 
associated with the current CDC context. After this operation 
is run, the current maximum LSN from the LSN-timestamp 

sys.fn_cdc_get_max_lsn_ table becomes the start of the 
range for the next processing range. This operation requires 
a connection to the source database. 


MarkinitialLoadStart This operation is used at the beginning of an initial-load 
package to record the current LSN in the source database 
before the initial-load package starts reading the source 
tables. This requires a connection to the source database to 
call sys.fn_cdc_get_max_lsn . 


If you select MarkinitialLoadStart when working on SQL 
Server CDC (that is, not Oracle) the user specified in the 
connection manager must be either db_owner or sysadmin. 


MarklnitialLoadEnd This operation is used at the end of an initial-load package 
to record the current LSN in the source database after the 
initial-load package finished reading the source tables. This 
LSN is determined by recording the current time when this 
operation occurred and then querying the cdc.1sn_time_ 
mapping table in the CDC database looking for a change 
that occurred after that time. 


If you select MarkinitialtoadEnd when working on SQL 
Server CDC (that is , not Oracle) the user specified in the 
connection manager must be either db_owner or sysadmin. 


OPERATION 


MarkCdcStart 


DESCRIPTION 


This operation is used when then the initial load is made 
from a snapshot database. In this case, the change 
processing should start immediately after the snapshot LSN. 
You can specify the name of the snapshot database to use 
and the CDC Control task queries SQL Server for the 
snapshot LSN. You also have the option to directly specify 
the snapshot LSN. 


If you select MarkCdcStart when working on SQL Server 
CDC (that is , not Oracle) the user specified in the 
connection manager must be either db_owner or sysadmin. 


The following operations are used to manage the processing range: 


Handling CDC State Persistency 


OPERATION 


GetProcessingRange 


MarkProcessedRange 


DESCRIPTION 


This operation is used before invoking the data flow that 
uses the CDC Source data flow. It establishes a range of 
LSNs that the CDC Source data flow reads when invoked. 
The range is stored in an SSIS package variable that is used 
by the CDC Source during data-flow processing. 


For more information about the states that are stored, see 
Define a State Variable. 


: This operation is executed after each CDC run (after the 
CDC data flow is completed successfully) to record the last 
LSN that was fully processed in the CDC run. The next time 
GetProcessingRange is executed, this position is the start of 
the processing range. 


The CDC Control task maintains a persistent state between activations. The information stored in the CDC state 


is used to determine and maintain the processing range for the CDC package and for detecting error conditions. 


The persistent state is stored as a string. For more information, see Define a State Variable. 


The CDC Control task supports two types of state persistency 


Error Handling 


The CDC Control task may report an error when: 


Manual State Persistency: In this case, the CDC Control task manages the state stored in a package 


variable but the package developer must read the variable from a persistent store before calling the CDC 
Control and then write it back to that persistent store after the CDC Control is last called and the CDC run 


completes. 


Automatic State Persistency: The CDC state is stored in a table in a database. The state is stored under a 


name provided in the StateName property in a table named in the Table to Use for Storing State 


property, which is located in a selected connection manager for storing the state. The default is the source 


connection manager but the common practice is for it to be the target connection manager. The CDC 


Control task updates the state value in the state table and this is committed as part of the ambient 


transaction. 


e It fails to read the persistent CDC state or when updating the persistent state fails. 


e \t fails to read the current LSN information from the source database. 
e The CDC state read is not consistent. 


In all of these cases, the CDC Control task reports an error that can be handled in the standard way SSIS handles 


control-flow errors. 


The CDC Control task may also report a warning when the Get Processing Range operation is invoked directly 
after another Get Processing Range operation without Mark Processed Range being called. This is an indication 
that the previous run failed or that another CDC package may be running using the same CDC state name. 


Configuring the CDC Control Task 


You can set properties through SSIS Designer or programmatically. 


In This Section 


e CDC Control Task Custom Properties 


Related Tasks 


Define a State Variable 


Related Content 


@ Technical article, Installing Microsoft SQL Server 2012 Change Data Capture for Oracle by Attunity, on 


social.technet.microsoft.com. 


@ Technical article, Troubleshoot Configuration Issues in Microsoft Change Data Capture for Oracle by 


Attunity, on social.technet.microsoft.com. 


@ Technical article, Troubleshoot CDC Instance Errors in Microsoft Change Data Capture for Oracle by 


Attunity, on social.technet.microsoft.com. 


CDC Control Task Editor 


Use the CDC Control Task Editor dialog box to configure the CDC Control task. The CDC Control task 
configuration includes defining a connection to the CDC database, the CDC task operation and the state 


management information. 
To learn more about the CDC Control task, see CDC Control Task. 
To open the CDC Control Task Editor 


1. In SQL Server Data Tools, open the SQL Server 2019 Integration Services (SSIS) package that has the 
CDC Control task. 


2. On the Control Flow tab, double-click the CDC Control task. 


Options 

SQL Server CDC database ADO.NET connection manager 

Select an existing connection manager from the list, or click New to create a new connection. The connection 
must be to a SQL Server database that is enabled for CDC and where the selected change table is located. 


CDC Control Operation 
Select the operation to run for this task. All operations use the state variable that is stored in an SSIS package 
variable that stores the state and passes it between the different components in the package. 


e Mark initial load start: This operation is used when executing an initial load from an active database 
without a snapshot. It is invoked at the beginning of an initial-load package to record the current LSN in 
the source database before the initial-load package starts reading the source tables. This requires a 
connection to the source database. 


If you select Mark Initial Load Start when working on SQL Server CDC (that is, not Oracle) the user 
specified in the connection manager must be either db_owner or sysadmin. 


e@ Mark initial load end: This operation is used when executing an initial load from an active database 
without a snapshot. It is invoked at the end of an initial-load package to record the current LSN in the 
source database after the initial-load package finished reading the source tables. This LSN is determined 
by recording nthe current time when this operation occurred and then querying the cdc.1sn_time_ 
mapping table in the CDC database looking for a change that occurred after that time 


If you select Mark Initial Load End when working on SQL Server CDC (that is, not Oracle) the user 


specified in the connection manager must be either db_owner or sysadmin. 


e@ Mark CDC start: This operation is used when then the initial load is made from a snapshot database or 
from a quiescence database. It is invoked at any point within the initial load package. The operation 
accepts a parameter that can be a snapshot LSN, a name of a snapshot database (from which the 
snapshot LSN will be derived automatically) or it can be left empty, in which case the current database 
LSN is used as the start LSN for the change processing package. 


This operation is used instead of the Mark Initial Load Start/End operations. 


If you select Mark CDC Start when working on SQL Server CDC (that is, not Oracle) the user specified in 


the connection manager must be either db_owner or sysadmin. 


e Get processing range: This operation is used in a change processing package before invoking the data 
flow that uses the CDC Source data flow. It establishes a range of LSNs that the CDC Source data flow 
reads when invoked. The range is stored in an SSIS package variable that is used by the CDC Source 


during data-flow processing. 
For more information about the possible CDC states that are stored, see Define a State Variable. 


e Mark processed range: This operation is used in a change processing package at the end of a CDC run 
(after the CDC data flow is completed successfully) to record the last LSN that was fully processed in the 
CDC run. The next time GetProcessingRange is executed, this position determines the start of the next 


processing range. 


e Reset CDC state: This operation is used to reset the persistent CDC state associated with the current 
CDC context. After this operation is run, the current maximum LSN from the LSN-timestamp 
sys.fn_cdc_get_max_lsn table becomes the start of the range for the next processing range. This 


operation requires a connection to the source database. 


An example of when this operation is used is when you want to process only the newly created change 
records and ignore all old change records. 


Variable containing the CDC state 

Select the SSIS package variable that stores the state information for the task operation. You should define a 
variable before you begin. If you select Automatic state persistence, the state variable is loaded and saved 
automatically. 


For more information about defining the state variable, see Define a State Variable. 


SQL Server LSN to start the CDC/Snapshot name: 
Type the current source database LSN or the name of the snapshot database from which the initial load is 
performed to determine where the CDC starts. This is available only if the CDC Control Operation is set to 


Mark CDC Start. 
For more information about these operations, see CDC Control Task 


Automatically store state in a database table 

Select this check box for the CDC Control task to automatically handle loading and storing the CDC state ina 
state table contained in the specified database. When not selected, the developer must load the CDC State when 
the package starts and save it whenever the CDC State changes. 


Connection manager for the database where the state is stored 
Select an existing ADO.NET connection manager from the list, or click New to create a new connection. This 
connection is to a SQL Server database that contains the State table. The State table contains the State 


information. 
This is available only if Automatic state persistence is selected and it is a required parameter. 


Table to use for storing state 
Type the name of the state table to be used for storing the CDC state. The table specified must have two columns 
called name and state and both columns must be of the data type varchar (256). 


You can optionally select New to get an SQL script that builds a new State table with the required columns. 
When Automatic state persistence is selected, the developer must create a state table according to the 
requirements listed above. 


This is available only if Automatic state persistence is selected and it is a required parameter. 


State name 
Type a name to associate with the persistent CDC state. The full load and CDC packages that work with the same 
CDC context will specify a common state name. This name is used for looking up the state row in the state table 


CDC Control Task Custom Properties 
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Applies to: Q sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


The following table describes the custom properties of the CDC Control task. All properties are read/write. 
PROPERTY NAME DATA TYPE DESCRIPTION 


Connection ADO.NET Connection An ADO.NET connection to the SQL 
Server CDC database for access to the 
change tables and to the CDC State if 
stored in the same database. 


The connection must be to a SQL 
Server database that is enabled for 
CDC and where the selected change 
table is located. 


TaskOperation Integer (enumeration) The selected operation for the CDC 
control task. The possible values are 
Mark Initial Load Start, Mark 
Initial Load End, Mark CDC Start, 
Get Processing Range, Mark 
Processed Range, and Reset CDC 
State. 


If you select MarkCdcStart, 
MarkInitialLoadStart, or 
MarklInitialLoadEnd when working 
on SQL Server CDC (that is, not 
Oracle) the user specified in the 
connection manager must be either 
db_owner or sysadmin. 


For more information about these 
operations, see CDC Control Task 
Editor and CDC Control Task. 


OperationParameter String Currently used with the 
MarkCdcStart operation. This 
parameter allows additional input 
required for the specific operation. For 
example, the LSN number required for 
the MarkCdcStart operation 


StateVariable String An SSIS package variable that stores 
the CDC state of the current CDC 
context. The CDC Control task reads 
and writes the state to the 
StateVariable and does not load it or 
store it to a persistent storage unless 
AutomaticStatePersistence is 
selected. See Define a State Variable. 


PROPERTY NAME 


AutomaticStatePersistence 


StateConnection 


StateName 


DATA TYPE 


Boolean 


ADO.NET Connection 


String 


DESCRIPTION 


The CDC Control task reads the CDC 
State from the CDC State package 
variable. Following an operation, the 
CDC Control task updates the value of 
the CDC State package variable. The 
AutomaticStatePersistence 
property tells the CDC Control task 
who is responsible for persisting the 
CDC State value between runs of the 
SSIS package. 


When this property is true, the CDC 
Control task automatically loads the 
value of the CDC State variable from a 
state table. When the CDC Control 
task updates the value of the CDC 
State variable it also updates its value 
in the same state table.stores, the 
state in a special table and updates the 
State Variable. The developer can 
control which SQL Server database 
contains that state table and its name. 
The structure of this state table is 
predefined. 


When false, the CDC Control task 
does not deal with persisting its value. 
When true, the CDC Control task 
stores the state in a special table and 
updates the StateVariable. 


The default value is true, indicating 
that state persistence is updated 
automatically. 


An ADO.NET connection to the 
database where the state table resides 
when using 
AutomaticStatePersistence. The 
default value is the same value for 
Connection. 


The name associated with the 
persistent state. The full load and CDC 
packages that work with the same 
CDC context specify a common CDC 
context name. This name is used for 
looking up the state row in the state 
table. 


This property is applicable only when 
AutomaticStatePersistence is set to 
true. 


PROPERTY NAME DATA TYPE 

StateTable String 

CommandTimeout integer 
See Also 


CDC Control Task 
CDC Control Task Editor 


DESCRIPTION 


Specifies the name of the table where 
the CDC context state is stored. This 
table must be accessible using the 
connection configured for this 
component. This table must include 
varchar columns called name and 
state. (The state column must have 
at least 256 characters). 


This property is applicable only when 
AutomaticStatePersistence is set to 
true. 


This value indicates the timeout (in 
seconds) to use when communicating 
with the SQL Server database. This 
value is used where the response time 
from the database is very slow and the 
default value (30 seconds) is not 
enough. 


Check Database Integrity Task 
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The Check Database Integrity task checks the allocation and structural integrity of all the objects in the specified 
database. The task can check a single database or multiple databases, and you can choose whether to also check 
the database indexes. 


The Check Database Integrity task encapsulates the DBCC CHECKDB statement. For more information, see DBCC 
CHECKDB (Transact-SQL). 


Configuration of the Check Database Integrity Task 


You can set properties through SSIS Designer. This task is in the Maintenance Plan Tasks section of the 
Toolbox in SSIS Designer. 


For more information about the properties that you can set in SSIS Designer, click the following topic: 


e@ Check Database Integrity Task (Maintenance Plan) 


For more information about how to set these properties in SSIS Designer, click the following topic: 


e Set the Properties of a Task or Container 


Data Flow Task 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


The Data Flow task encapsulates the data flow engine that moves data between sources and destinations, and 
lets the user transform, clean, and modify data as it is moved. Addition of a Data Flow task to a package control 
flow makes it possible for the package to extract, transform, and load data. 


A data flow consists of at least one data flow component, but it is typically a set of connected data flow 
components: sources that extract data; transformations that modify, route, or summarize data; and destinations 
that load data. 


At run time, the Data Flow task builds an execution plan from the data flow, and the data flow engine executes 
the plan. You can create a Data Flow task that has no data flow, but the task executes only if it includes at least 
one data flow. 


To bulk insert data from text files into a SQL Server database, you can use the Bulk Insert task instead of a Data 
Flow task and a data flow. However, the Bulk Insert task cannot transform data. For more information, see Bulk 
Insert Task. 


Multiple Flows 


A Data Flow task can include multiple data flows. If a task copies several sets of data, and if the order in which 
the data is copied is not significant, it can be more convenient to include multiple data flows in the Data Flow 
task. For example, you might create five data flows, each copying data from a flat file into a different dimension 
table in a data warehouse star schema. 


However, the data flow engine determines order of execution when there are multiple data flows within one data 
flow task. Therefore, when order is important, the package should use multiple Data Flow tasks, each task 
containing one data flow. You can then apply precedence constraints to control the execution order of the tasks. 


The following diagram shows a Data Flow task that has multiple data flows. 
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Log Entries 


Integration Services provides a set of log events that are available to all tasks. Integration Services also provides 
custom log entries to many tasks. For more information, see Integration Services (SSIS) Logging. The Data Flow 
task includes the following custom log entries: 


LOG ENTRY 


BufferSizeTuning 


OnPipelinePostEndOfRowset 


OnPipelinePostPrimeOutput 


OnPipelinePreEndOfRowset 


OnPipelinePrePrimeOutput 


OnPipelineRowsSent 


PipelineBufferLeak 


PipelineComponentTime 


PipelineExecutionPlan 


PipelineExecutionTrees 


Pipelinelnitialization 


DESCRIPTION 


Indicates that the Data Flow task changed the size of the 
buffer. The log entry describes the reasons for the size 
change and lists the temporary new buffer size. 


Denotes that a component has been given its end-of-rowset 
signal, which is set by the last call of the ProcessInput 
method. An entry is written for each component in the data 
flow that processes input. The entry includes the name of 
the component. 


Indicates that the component has completed its last call to 
the PrimeOutput method. Depending on the data flow, 
multiple log entries may be written. If the component is a 
source, this log entry means that the component has 
finished processing rows. 


Indicates that a component is about to receive its end-of- 
rowset signal, which is set by the last call of the 
ProcessInput method. An entry is written for each 
component in the data flow that processes input. The entry 
includes the name of the component. 


Indicates that the component is about to receive its call from 
the PrimeOutput method. Depending on the data flow, 
multiple log entries may be written. 


Reports the number of rows provided to a component input 
by a call to the ProcessInput method. The log entry 
includes the component name. 


Provides information about any component that kept 
buffers alive after the buffer manager goes away. If a buffer 
is still alive, buffers resources were not released and may 
cause memory leaks. The log entry provides the name of the 
component and the ID of the buffer. 


Reports the amount of time (in milliseconds) that the 
component spent in each of its five major processing steps- 
Validate, PreExecute, PostExecute, ProcessInput, and 
ProcessOutput. 


Reports the execution plan of the data flow. The execution 
plan provides information about how buffers will be sent to 
components. This information, in combination with the 
PipelineExecutionTrees log entry, describes what is 
happening within the Data Flow task. 


Reports the execution trees of the layout in the data flow. 
The scheduler of the data flow engine uses the trees to build 
the execution plan of the data flow. 


Provides initialization information about the task. This 
information includes the directories to use for temporary 
storage of BLOB data, the default buffer size, and the 
number of rows in a buffer. Depending on the configuration 
of the Data Flow task, multiple log entries may be written. 


These log entries provide a wealth of information about the execution of the Data Flow task each time you run a 
package. As you run the packages repeatedly, you can capture information that over time provides important 
historical information about the processing that the task performs, issues that might affect performance, and the 
data volume that task handles. 


For more information about how to use these log entries to monitor and improve the performance of the data 
flow, see one of the following topics: 


e Performance Counters 
e Data Flow Performance Features 


Sample Messages From a Data Flow Task 


The following table lists sample messages for log entries for a very simple package. The package uses an OLE 
DB source to extract data from a table, a Sort transformation to sort the data, and an OLE DB destination to 
writes the data to a different table. 


LOG ENTRY MESSAGES 


BufferSizeTuning Rows in buffer type @ would cause a buffer size 
greater than the configured maximum. There will be 
only 9637 rows in buffers of this type. 


Rows in buffer type 2 would cause a buffer size 
greater than the configured maximum. There will be 
only 9497 rows in buffers of this type. 


Rows in buffer type 3 would cause a buffer size 
greater than the configured maximum. There will be 
only 9497 rows in buffers of this type. 


OnPipelinePostEndOfRowset A component will be given the end of rowset signal. 
fLl8OeeSOrt aa lst es Sorte Input 


A component will be given the end of rowset signal. 
: 1291 : OLE DB Destination : 1304 : OLE DB 
Destination Input 


OnPipelinePostPrimeOutput A component has returned from its PrimeOutput call. 
PLL SO SOR 


A component has returned from its PrimeOutput call. 
s 1 3 ‘OLE DB) Source 


OnPipelinePreEndOfRowset A component has finished processing all of its 
nOWSs, + 2180s Sort i) 28d Sort Input 


A component has finished processing all of its 
rows. : 1291 : OLE DB Destination : 1304 : OLE DB 
Destination Input 


OnPipelinePrePrimeOutput PrimeOutput will be called on a component. : 1180 : 
Sort 
PrimeOutput will be called on a component. : 1 : 


OLE DB Source 


LOG ENTRY 


OnPipelineRowsSent 


PipelineComponentTime 


PipelineExecutionPlan 


MESSAGES 


Rows were provided to a data flow component as 
input. : : 1185 : OLE DB Source Output : 1180 
SOnteme Lois Sonte-Enp utes. 17-6 


Rows were provided to a data flow component as 
Inputs cuss 1308) 5 sSortsOutputes 1129108 OLE IDB 
Destination : 1304 : OLE DB Destination Input : 76 


The component "Calculate LineItemTotalCost" (3522) 
spent 356 milliseconds in ProcessInput. 


The component "Sum Quantity and LineItemTotalCost" 
(3619) spent 79 milliseconds in ProcessInput. 


The component "Calculate Average Cost" (3662) spent 
16 milliseconds in ProcessInput. 


The component "Sort by ProductID" (3717) spent 125 
milliseconds in ProcessInput. 


The component "Load Data" (3773) spent @ 
milliseconds in ProcessInput. 


The component "Extract Data" (3869) spent 688 
milliseconds in PrimeOutput filling buffers on 
output "OLE DB Source Output" (3879). 


The component "Sum Quantity and LineItemTotalCost" 
(3619) spent 141 milliseconds in PrimeOutput 
filling buffers on output "Aggregate Output 1" 
(3621). 


The component "Sort by ProductID" (3717) spent 16 
milliseconds in PrimeOutput filling buffers on 
output "Sort Output" (3719). 


SourceThread@ 


Drives: 1 


Influences: 1180 1291 


Output Work List 


CreatePrimeBuffer of type 1 for output ID 11. 


SetBufferListener: "WorkThread®" for input ID 1181 


CreatePrimeBuffer of type 3 for output ID 12. 


CallPrimeOutput on component "OLE DB Source" (1) 


End Output Work List 


End SourceThread@ 


WorkThread@ 


Drives: 1180 


Influences: 1180 1291 


Input Work list, input ID 1181 (1 EORs Expected) 


LOG ENTRY MESSAGES ri 
CallProcessInput on input ID 1181 on component 


"Sort" (1180) for view type 2 

End Input Work list for input 1181 

Output Work List 

CreatePrimeBuffer of type 4 for output ID 1182. 
SetBufferListener: "WorkThread1i" for input ID 1304 
CallPrimeOutput on component "Sort" (1180) 

End Output Work List 

End WorkThread@ 

WorkThread1 

Drives: 1291 

Influences: 1291 

Input Work list, input ID 1304 (1 EORs Expected) 


CallProcessInput on input ID 1304 on component "OLE 
DB Destination" (1291) for view type 5 


End Input Work list for input 1304 
Output Work List 
End Output Work List 


End WorkThread1 


PipelineExecutionTrees begin execution tree @ 
output "OLE DB Source Output" (11) 
input "Sort Input" (1181) 
end execution tree @ 
begin execution tree 1 
output “OLE DB Source Error Output" (12) 
end execution tree 1 
begin execution tree 2 
output “Sort Output" (1182) 
input "OLE DB Destination Input" (1304) 
output "OLE DB Destination Error Output" (1305) 


end execution tree 2 


LOG ENTRY 


Pipelinelnitialization 


MESSAGES 


No temporary BLOB data storage locations were 
provided. The buffer manager will consider the 
directories in the TEMP and TMP environment 


variables. 


The default buffer size is 10485760 bytes. 


Buffers will have 1000@ rows by default 


The data flow will not remove unused components 
because its RunInOptimizedMode property is set to 


false. 


Many log events write multiple entries, and the messages for a number of log entries contain complex data. To 


make it easier to understand and to communicate the content of complex messages you can parse the message 


text. Depending on the location of the logs, you can use Transact-SQL statements or a Script component to 


separate the complex text into columns or other formats that you find more useful. 


For example, the following table contains the message "Rows were provided to a data flow component as input. : 


:1185 : OLE DB Source Output : 1180 : Sort: 1181 : Sort Input : 76", parsed into columns. The message was 


written by the OnPipelineRowsSent event when rows were sent from the OLE DB source to the Sort 


transformation. 


COLUMN 


PathID 


PathName 


ComponentID 


ComponentName 


InputID 


InputName 


RowsSent 


DESCRIPTION 


The value from the ID property of the 
path between the OLE DB source and 
the Sort transformation. 


The value from the Name property of 
the path. 


The value of the ID property of the 
Sort transformation. 


The value from the Name property of 
the Sort transformation. 


The value from the ID property of the 
input to the Sort transformation. 


The value from the Name property of 
the input to the Sort transformation. 


The number of rows sent to the input 
of the Sort transformation. 


Configuration of the Data Flow Task 


You can set properties in the Properties window or programmatically. 


VALUE 


1185 


OLE DB Source Output 


1180 


Sort 


1181 


Sort Input 


For more information about how to set these properties in the Properties window, click the following topic: 


e Set the Properties of a Task or Container 


Programmatic Configuration of the Data Flow Task 


For more information about programmatically adding a data flow task to a package and setting data flow 


properties, click the following topic: 


e Adding the Data Flow Task Programmatically 


Related Tasks 


Set the Properties of a Task or Container 


Related Content 


Video, Balanced Data Distributer, on technet.microsoft.com. 


Data Mining Query Task 
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The Data Mining Query task runs prediction queries based on data mining models built in Analysis Services. The 
prediction query creates a prediction for new data by using mining models. For example, a prediction query can 
predict how many sailboats are likely to sell during the summer months or generate a list of prospective 
customers who are likely to buy a sailboat. 


Integration Services provides tasks that perform other business intelligence operations, such as running Data 
Definition Language (DDL) statements and processing analytic objects. 


For more information about other business intelligence tasks, click one of the following topics: 
e Analysis Services Execute DDL Task 


e Analysis Services Processing Task 


Prediction Queries 


The query is a Data Mining Extensions (DMX) statement. The DMX language is an extension of the SQL language 
that provides support for working with mining models. For more information about how to use the DMX 
language, see Data Mining Extensions (DMX) Reference. 


The task can query multiple mining models that are built on the same mining structure. A mining model is built 
using one of the data mining algorithms that Analysis Services provides. The mining structure that the Data 
Mining Query task references can include multiple mining models, built using different algorithms. For more 
information, see Mining Structures (Analysis Services - Data Mining) and Data Mining Algorithms (Analysis 
Services - Data Mining). 


The prediction query that the Data Mining Query task runs returns a result that is a single row or a data set.A 
query that returns a single row is called a singleton query: for example, the query that predicts how many 
sailboats will be sold during the summer months returns a number. For more information about prediction 
queries that return a single row, see Data Mining Query Tools. 


The query results are saved to tables. If a table with the name that the Data Mining Query task specifies already 
exists, the task can create a new table, using the same name with a number appended, or it can overwrite the 
table content. 


If the results include nesting, the result is flattened before it is saved. Flattening a result changes a nested result 
set to a table. For example, flattening a nested result with a Customer column and a nested Product column 
adds rows to the Customer column to make a table that includes product data for each customer. For example, 
a customer with three different products becomes a table with three rows, repeating the customer in each row 
and including a different product in each row. If the FLATTENED keyword is omitted, the table contains only the 
Customer column and only one row per customer. For more information, see SELECT (DMX). 


Configuration of the Data Mining Query Task 


The Data Mining Query task requires two connections. The first connection is an Analysis Services connection 
manager that connects either to an instance of Microsoft SQL Server Analysis Services or to an Analysis 
Services project that contains the mining structure and the mining model. The second connection is an OLE DB 
connection manager that connects to the SQL Server database that contains the table to which the task writes. 


For more information, see Analysis Services Connection Manager and OLE DB Connection Manager. 


You can set properties through SSIS Designer or programmatically. 


NOTE 


The Data Mining Query Editor has no Expressions page. Instead, use the Properties window to access the tools for 


creating and managing property expressions for properties of the Data Mining Query task. 





For more information about how to set these properties in SSIS Designer, click the following topic: 


e Set the Properties of a Task or Container 


Programmatic Configuration of Data Mining Query Task 
For more information about programmatically setting these properties, click one of the following topics: 


e@ DMQueryTask 


Data Mining Query Task Editor (Mining Model Tab) 


Use the Mining Model tab of the Data Mining Query Task dialog box to specify the mining structure and 
mining model to use. 


To learn about implementing data mining in packages, see Data Mining Query Task and Data Mining Solutions. 


General Options 


Name 


Provide a unique name for the Data Mining Query task. This name is used as the label in the task icon. 





NOTE 


Task names must be unique within a package. 





Description 
Type a description of the Data Mining Query task. 


Mining Model Tab Options 


Connection 
Select an Analysis Services connection manager in the list or click New to create a new connection manager. 


Related Topics: Analysis Services Connection Manager 


New 


Create a new Analysis Services connection manager. 
Related Topics: Add Analysis Services Connection Manager Dialog Box UI Reference 


Mining structure 
Select a mining structure in the list. 


Mining models 
Select a mining model built on the selected mining structure. 


Data Mining Query Task Editor (Query Tab) 


Use the Query tab of the Data Mining Query Task dialog box to create prediction queries based on a mining 


model. In this dialog box you can also bind parameters and result sets to variables. 
To learn about implementing data mining in packages, see Data Mining Query Task and Data Mining Solutions. 


General Options 


Name 
Provide a unique name for the Data Mining Query task. This name is used as the label in the task icon. 





NOTE 


Task names must be unique within a package. 





Description 


Type a description of the Data Mining Query task. 


Build Query Tab Options 
Data mining query 
Type a data mining query. 


Related Topics: Data Mining Extensions (DMX) Reference 


Build New Query 
Create the data mining query using a graphical tool. 


Related Topics: Data Mining Query 


Parameter Mapping Tab Options 


Parameter Name 
Optionally, update the parameter name. Map the parameter to a variable by selecting a variable in the Variable 
Name list. 


Variable Name 
Select a variable in the list to map it to the parameter. 


Add 
Add to a parameter to the list. 


Remove 
Select a parameter, and then click Remove. 
Result Set Tab Options 


Result Name 
Optionally, update the result set name. Map the result to a variable by selecting a variable in the Variable 
Name list. 


After you have added a result by clicking Add, provide a unique name for the result. 


Variable Name 
Select a variable in the list to map it to the result set. 


Result Type 
Indicate whether to return a single row or a full result set. 


Add 
Add a result set to the list. 


Remove 
Select a result, and then click Remove. 


Data Mining Query Task Editor (Output Tab) 


Use the Output tab of the Data Mining Query Task Editor dialog box to specify the destination of the 
prediction query. 


To learn about implementing data mining in packages, see Data Mining Query Task and Data Mining Solutions. 


General Options 


Name 


Provide a unique name for the Data Mining Query task. This name is used as the label in the task icon. 





NOTE 


Task names must be unique within a package. 





Description 
Type a description of the Data Mining Query task. 


Output Tab Options 
Connection 


Select a connection manager in the list or click New to create a new connection manager. 


New 
Create a new connection manager. Only the ADO.NET and OLE DB connection manager types can be used. 


Output table 
Specify the table to which the prediction query writes its results. 


Drop and re-create the output table 
Indicate whether the prediction query should overwrite content in the destination table by dropping and then 
re-creating the table. 


Data Mining Query 


11/23/2021 * 2 minutes to read « Edit Online 





Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


The design pane contains the data mining prediction query builder, which you can use to build data mining 
prediction queries. You can design either prediction queries based on input tables, or singleton prediction 
queries. Switch to the result view to run the query and view the results. The query view displays the Data Mining 
Extensions (DMX) query created by the prediction query builder. 


Options 
Switch view button 
Click an icon to switch between the design and query pane. By default, the design pane is open. 


To switch to the design pane, click the ©! icon. 


To switch to the query pane, click the Sat icon. 


Mining Model 
Displays the selected mining model on which you want to base predictions. 


Select Model 
Opens the Select Mining Model dialog box. 


Input Columns 
Displays the selected input columns used to generate the predictions. 


Source 

Select the source containing the field that you will use for the column from the dropdown list. You can either use 
the mining model selected in the Mining Model table, the input table(s) selected in the Select Input Table(s) 
table, a prediction function, or a custom expression. 


Columns can be dragged from the tables containing the mining model and input columns to the cell. 


Field 
Select a column from the list of columns derived from the source table. If you selected Prediction Function in 
Source, this cell contains a drop-down list of the prediction functions available for the selected mining model. 


Alias 
The name of the column returned by the server. 


Show 
Select to return the column or to only use the column in the WHERE clause. 


Group 
Use with the And/Or column to group expressions together. For example, (expr1 OR expr2) AND expr3. 


And/Or 
Use to create a logical query. For example, (expr1 OR expr2) AND expr3. 


Criteria/Argument 
Specify a condition or user expression that applies to the column. Columns can be dragged from the tables 
containing the mining model and input columns to the cell. 


See Also 


Data Mining Query Tools 
Data Mining Extensions (DMX) Statement Reference 


Data Profiling Task and Viewer 
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The Data Profiling task provides data profiling functionality inside the process of extracting, transforming, and 
loading data. By using the Data Profiling task, you can achieve the following benefits: 


e Analyze the source data more effectively 
e Understand the source data better 


e Prevent data quality problems before they are introduced into the data warehouse. 





IMPORTANT 
The Data Profiling task works only with data that is stored in SQL Server. It does not work with third-party or file-based 


data sources. 











Data Profiling Overview 


Data quality is important to every business. As enterprises build analytical and business intelligence systems on 
top of their transactional systems, the reliability of key performance indicators and of data mining predictions 
depends completely on the validity of the data on which they are based. But although the importance of valid 
data for business decision-making is increasing, the challenge of making sure of this data's validity is also 
increasing. Data is streaming into the enterprise constantly from diverse systems and sources, and a large 
numbers of users. 


Metrics for data quality can be difficult to define because they are specific to the domain or the application. One 
common approach to defining data quality is data profiling. 


A data profile is a collection of aggregate statistics about data that might include the following: 
e The number of rows in the Customer table. 
@ The number of distinct values in the State column. 


e The number of null or missing values in the Zip column. 


The distribution of values in the City column. 


e The strength of the functional dependency of the State column on the Zip column-that is, the state should 
always be the same for a given zip value. 


The statistics that a data profile provides gives you the information that you need in order to effectively 
minimize the quality issues that might occur from using the source data. 


Integration Services and Data Profiling 


In Integration Services, the data profiling process consist of the following steps: 


Step 1: Setting up the Data Profiling Task 
The Data Profiling task is a task that you use to configure the profiles that you want to compute. You then run 
the package that contains the Data Profiling task to compute the profiles. The task saves the profile output in 


XML format to a file or a package variable. 
For more information: Setup of the Data Profiling Task 


Step 2: Reviewing the Profiles that the Data Profiling Task Computes 

To view the data profiles that the Data Profiling task computes, you send the output to a file, and then you use 
the Data Profile Viewer. This viewer is a stand-alone utility that displays the profile output in both summary and 
detail format with optional drilldown capability. 


For more information: Data Profile Viewer 


Addition of Conditional Logic to the Data Profiling Workflow 


The Data Profiling task does not have built-in features that allow you to use conditional logic to connect this task 
to downstream tasks based on the profile output. However, you can easily add this logic, with a small amount of 
programming, in a Script task. For example, the Script task could perform an XPath query against the output file 
of the Data Profiling task. The query could determine whether the percentage of null values in a particular 
column exceeds a certain threshold. If the percentage exceeds the threshold, you could interrupt the package 
and resolve the problem in the source data before continuing. For more information, see Incorporate a Data 
Profiling Task in Package Workflow. 


Related Content 


Data Profiler Schema 


Setup of the Data Profiling Task 
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Before you can review a profile of the source data, the first step is to set up and run the Data Profiling task. You 
create this task inside an Integration Services package. To configure the Data Profiling task, you use the Data 
Profiling Task Editor. This editor enables you to select where to output the profiles, and which profiles to 
compute. After you set up the task, you run the package to compute the data profiles. 


Requirements and Limitations 


The Data Profiling task works only with data that is stored in SQL Server. It does not work with third-party or 
file-based data sources. 


Furthermore, to run a package that contains the Data Profiling task, you must use an account that has 
read/write permissions, including CREATE TABLE permissions, on the tempdb database. 


Data Profiling Task in a Package 


The Data Profiling task only configures the profiles and creates the output file that contains the computed 
profiles. To review this output file, you must use the Data Profile Viewer, a stand-alone viewer program. Because 
you must view the output separately, you might use the Data Profiling task in a package that contains no other 
tasks. 


However, you do not have to use the Data Profiling task as the only task in a package. If you want to perform 
data profiling in the workflow or data flow of a more complex package, you have the following options: 


@ To implement conditional logic that is based on the task's output file, in the control flow of the package, 
put a Script task after the Data Profiling task. You can then use this Script task to query the output file. 


@ To profile data in the data flow after the data has been loaded and transformed, you have to save the 
changed data temporarily to a SQL Server table. Then, you can profile the saved data. 


For more information, see Incorporate a Data Profiling Task in Package Workflow. 


Setup of the Task Output 


After the Data Profiling task is in a package, you must set up the output for the profiles that the task will 
compute. To set up the output for the profiles, you use the General page of the Data Profiling Task Editor. In 
addition to specifying the destination for the output, the General page also offers you the ability to perform a 
quick profile of the data. When you select Quick Profile, the Data Profiling task profiles a table or view by using 
some or all the default profiles with their default settings. 


For more information, see Data Profiling Task Editor (General Page) and Single Table Quick Profile Form (Data 
Profiling Task). 





IMPORTANT 


The output file might contain sensitive data about your database and the data that database contains. For suggestions 
about how to make this file more secure, see Access to Files Used by Packages. 











Selection and Configuration of the Profiles to be Computed 


After you have set up the output file, you have to select which data profiles to compute. The Data Profiling Task 


can compute eight different data profiles. Five of these profiles analyze individual columns, and the remaining 


three analyze multiple columns or relationships between columns and tables. In a single Data Profiling task, you 


can compute multiple profiles for multiple columns or combinations of columns in multiple tables or views. 


The following table describes the reports that each of these profiles computes and the data types for which the 


profile is valid. 
TO COMPUTE 


All the distinct lengths of string values 
in the selected column and the 
percentage of rows in the table that 
each length represents. 


A set of regular expressions that cover 
the specified percentage of values in a 
string column. 


Also, to find regular expressions that 
can be used in the future to validate 
new values 


The percentage of null values in the 
selected column. 


WHICH HELP IDENTIFY 


String values that are not valid- 
For example, you profile of a column 
that is supposed to use two characters 
for state codes in the United States, 
but discover values that are longer 
than two characters. 


String values that are not valid or 
not in the correct format- For 
example, a pattern profile of a Zip 
Code/Postal Code column might 
produce the regular expressions: \d{5}- 
\d{4}, \d{5}, and \d{9}. If the output 
contains other regular expressions, the 
data contains values that are either 
not valid or in an incorrect format. 


An unexpectedly high ratio of 
null values in a column-For 
example, you profile a column that is 
supposed to contain United States Zip 
Codes, but discover an unacceptably 
high percentage of missing zip codes. 


USE THIS PROFILE 


Column Length Distribution- Valid 
for a column with one of the following 
character data types: 

char 

nchar 


varchar 


nvarchar 


Column Pattern Profile-Valid for a 
column with one of the following 
character data types: 

char 

nchar 


varchar 


nvarchar 


Column Null Ratio-Valid for a 
column with one of the following data 


types: 
image 
text 
xml 


user-defined types 


variant types 


TO COMPUTE WHICH HELP IDENTIFY USE THIS PROFILE 


Statistics such as minimum, maximum, Numeric values and dates that Column Statistics Profile-Valid for a 
average, and standard deviation for are not valid-For example, you column with one of these data types. 
numeric columns, and minimum and profile a column of historical dates, but 
maximum for datetime columns. discover a maximum date that is in the Numeric data types: 

future. 


integer types (except bit 
money 

smallmoney 

decimal 

float 

real 

numeric 

Date and time data types: 
datetime 

smalldatetime 

timestamp 

date 

time 

datetime2 

datetimeoffset 

Note: For a column that has a date 
and time data type, the profile 


computes minimum and maximum 
only. 


TO COMPUTE 


All the distinct values in the selected 
column and the percentage of rows in 
the table that each value represents. 
Or, the values that represent more 
than a specified percentage in the 
table. 


WHICH HELP IDENTIFY 


An incorrect number of distinct 
values in a column-For example, 
you profile a column that contains 
states in the United States, but 


discover more than 50 distinct values. 


USE THIS PROFILE 


Column Value Distribution- Valid 
for a column with one of the following 
data types. 

Numeric data types: 
integer types (except bit 
money 

smallmoney 

decimal 

float 

real 

numeric 

Character data types: 
char 

nchar 

varchar 

nvarchar 

Date and time data types: 
datetime 
smalldatetime 
timestamp 

date 

time 

datetime2 


datetimeoffset 


TO COMPUTE WHICH HELP IDENTIFY USE THIS PROFILE 


Whether a column or set of columns is Duplicate values in a potential Candidate Key-A multiple column 
a key, or an approximate key, for the key column-For example, you profile profile that reports whether a column 
selected table. the Name and Address columns in a or set of columns is appropriate to 
Customers table, and discover serve as a key for the selected table. 
duplicate values where the name and Valid for columns with one of these 
address combinations should be data types. 
unique. 


Integer data types: 
bit 

tinyint 

smallint 

int 

bigint 

Character data types: 
char 

nchar 

varchar 

nvarchar 

Date and time data types: 
datetime 
smalldatetime 
timestamp 

date 

time 

datetime2 


datetimeoffset 


TO COMPUTE 


The extent to which the values in one 
column (the dependent column) 
depend on the values in another 
column or set of columns (the 
determinant column). 


WHICH HELP IDENTIFY 


Values that are not valid in 
dependent columns-For example, 
you profile the dependency between a 
column that contains United States Zip 
Codes and a column that contains 
states in the United States. The same 
Zip Code should always have the same 
state. However, the profile discovers 
violations of the dependency. 


USE THIS PROFILE 


Functional Dependency- Valid for 
columns with one of these data types. 


Integer data types: 
bit 

tinyint 

smallint 

int 

bigint 

Character data types: 
char 

nchar 

varchar 

nvarchar 

Date and time data types: 
datetime 
smalldatetime 
timestamp 

date 

time 

datetime2 


datetimeoffset 


TO COMPUTE WHICH HELP IDENTIFY USE THIS PROFILE 


Whether a column or set of columns is Values that are not valid-For Value Inclusion- Valid for columns 
appropriate to serve as a foreign key example, you profile the ProductID with one of these data types: 
between the selected tables. column of a Sales table. The profile 
discovers that the column contains Integer data types: 
That is, this profile reports the overlap values that are not found in the 
in the values between two columns or ProductID column of the Products bit 
sets of columns. table. 
tinyint 
smallint 
int 
bigint 


Character data types: 
char 

nchar 

varchar 

nvarchar 

Date and time data types: 
datetime 
smalldatetime 
timestamp 

date 

time 

datetime2 


datetimeoffset 


To select which profiles to compute, you use the Profile Requests page of the Data Profiling Task Editor. For 
more information, see Data Profiling Task Editor (Profile Requests Page). 


On the Profile Request page, you also specify the data source and configure the data profiles. When you 
configure the task, think about the following information: 


e Tosimplify configuration and make it easier to discover characteristics of unfamiliar data, you can use the 
wildcard, (*), in place of an individual column name. If you use this wildcard, the task will profile every 


column that has an appropriate data type, which in turn can slow down processing. 
e When the selected table or view is empty, the Data Profiling task does not compute any profiles. 


@ When all the values in the selected column are null, the Data Profiling task computes only the Column 
Null Ratio Profile. It does not compute the Column Length Distribution Profile, Column Pattern Profile, 
Column Statistics Profile, or Column Value Distribution Profile for the empty column. 


Each of the available data profiles has its own configuration options. For more information about those options, 
see the following topics: 


e Candidate Key Profile Request Options (Data Profiling Task) 

e Column Length Distribution Profile Request Options (Data Profiling Task) 
e Column Null Ratio Profile Request Options (Data Profiling Task) 

e@ Column Pattern Profile Request Options (Data Profiling Task) 

e Column Statistics Profile Request Options (Data Profiling Task) 

e Column Value Distribution Profile Request Options (Data Profiling Task) 
e Functional Dependency Profile Request Options (Data Profiling Task) 


e Value Inclusion Profile Request Options (Data Profiling Task) 


Execution of the Package that Contains the Data Profiling Task 


After you have set up the Data Profiling task, you can run the task. The task then computes the data profiles and 
outputs this information in XML format to a file or a package variable. The structure of this XML follows the 
DataProfile.xsd schema. You can open the schema in Microsoft Visual Studio or another schema editor, in an 
XML editor, or in a text editor such as Notepad. This schema for data quality information could be useful for the 


following purposes: 
@ To exchange data quality information within and across organizations. 
e To build custom tools that work with data quality information. 


The target namespace is identified in the schema as 
https://schemas.microsoft.com/sqlserver/2008/DataDebugger/. 


Next Step 


Data Profile Viewer. 


Data Profile Viewer 
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Viewing and analyzing the data profiles is the next step in the data profiling process. You can view these profiles 
after you have run the Data Profiling task inside an Integration Services package and computed the data 
profiles. For more information about how to set up and run the Data Profiling tasks, see Setup of the Data 
Profiling Task. 





IMPORTANT 


The output file might contain sensitive data about your database and the data that database contains. For suggestions on 


how to make this file more secure, see Access to Files Used by Packages. 








Data Profiles 


To view the data profiles, you configure the Data Profiling task to send its output to a file, and then you use the 
stand-alone Data Profile Viewer. To open the Data Profile Viewer, do one of the following. 


e Right-click the Data Profiling task in the SSIS Designer, and then click Edit. Click Open Profile Viewer 
on the General page of the Data Profiling Task Editor. 


e Inthe folder, <drive>\Program Files (x86) | Program Files\Microsoft SQL Server\110\DTS\Binn, run 
DataProfileViewer.exe. 


The viewer uses multiple panes to display the profiles that you requested and the computed results, with 
optional details and drilldown capability: 


Profiles pane 

The Profiles pane displays the profiles that were requested in the Data Profile task. To view the computed 
results for the profile, select the profile in the Profiles pane and the results will appear in the other panes of the 
viewer. 


Results pane 

The Results pane uses a single row to summarize the computed results of the profile. For example, if you 
request a Column Length Distribution Profile, this row includes the minimum and maximum length, and 
the row count. For most profiles, you can select this row in the Results pane to see additional detail in the 
optional Details pane. 


Details pane 

For most profile types, the Details pane displays additional information about the profile results selected in the 
Results pane. For example, if you request a Column Length Distribution Profile, the Details pane displays 
each column length that was found. The pane also displays the number and percentage of rows in which the 
column value has that column length. 


For the three profile types that are computed against more than one column (Candidate Key, Functional 
Dependency, and Value Inclusion), the Details pane displays violations of the expected relationship. For 
example, if you request a Candidate Key Profile, the Details pane displays duplicate values that violate the 
uniqueness of the candidate key. 


If the data source that is used to compute the profile is available, you can double-click a row in the Details pane 


to see the matching rows of data in the Drilldown pane. 


Drilldown pane 
You can double-click a row in the Details pane to see the matching rows of data in the Drilldown pane when 
the following conditions are true: 


e The data source that is used to compute the profile is available. 
e You have permission to view the data. 


To connect to the source database for a drilldown request, the Data Profile Viewer uses Windows Authentication 
and the credentials of the current user. The Data Profile Viewer does not use the connection information that is 
stored in the package that ran the Data Profiling task. 


IMPORTANT 
The drilldown capability that is available in the Data Profile Viewer sends live queries to the original data source. These 


queries may have a negative impact on the performance of the server. 


If you drill down from an output file that was not created recently, the drilldown queries might return a different set of 


rows than those on which the original output was calculated. 











For more information about the user interface of the Data Profile Viewer, see Data Profile Viewer F1 Help. 


Data Profile Viewer F1 Help 


Use the Data Profile Viewer to view the output of the Data Profiling task. 


For more information about how to use the Data Profile Viewer, see Data Profile Viewer. For more information 
about how to use the Data Profiling task, which creates the profile output that you analyze in the Data Profile 
Viewer, see Setup of the Data Profiling Task. 


Static Options 


Open 
Click to browse for the saved file that contains the output of the Data Profiling task. 


Profiles pane 
Expand the tree in the Profiles pane to see the profiles that are included in the output. Select a profile to view 
the results for that profile. 


Message pane 
Displays status messages. 


Drilldown pane 
Displays the rows of data that match a value in the output, if the data source that is used by the Data Profiling 
task is available. 


For example, if you are viewing the output of a Column Value Distribution profile for a US State column, the 
Detailed Value Distribution pane might contain a row for "WA". Double-click the row in the Detailed Value 
Distribution pane to see the rows of data where the value of the state column is "WA" in the drilldown pane. 


Dynamic Options 


Profile Type = Column Length Distribution Profile 


Column Length Distribution Profile - <column> pane 
Minimum Length 


Displays the minimum length of values in this column. 


Maximum Length 


Displays the maximum length of values in this column. 


Ignore Leading Spaces 
Displays whether this profile was computed with an IgnoreLeadingSpaces value of True or False. This 
property was set on the Profile Requests page of the Data Profiling Task Editor. 


Ignore Trailing Spaces 
Displays whether this profile was computed with an IgnoreTrailingS paces value of True or False. This property 
was set on the Profile Requests page of the Data Profiling Task Editor. 


Row Count 
Displays the number of rows in the table or view. 


Detailed Length Distribution pane 
Length 
Displays the column lengths found in the profiled column. 


Count 
Displays the number of rows in which the value of the profiled column has the length shown in the Length 


column. 


Percentage 
Displays the percentage of rows in which the value of the profiled column has the length shown in the Length 
column. 


Profile Type = Column Null Ratio Profile 


Column Null Ratio Profile - <column> pane 


Null Count 
Displays the number of rows in which the profiled column has a null value. 


Null Percentage 
Displays the percentage of rows in which the profiled column has a null value. 


Row Count 

Displays the number of rows in the table or view. 
Profile Type = Column Pattern Profile 

Column Pattern Profile - <column> pane 

Row Count 

Displays the number of rows in the table or view. 


Pattern Distribution pane 
Pattern 
Displays the patterns computed for the profiled column. 


Percentage 

Displays the percentage of rows whose values match the pattern displayed in the Pattern column. 
Profile Type = Column Statistics Profile 

Column Statistics Profile - <column> pane 

Minimum 


Displays the minimum value found in the profiled column. 


Maximum 


Displays the maximum value found in the profiled column. 


Mean 
Displays the mean of the values found in the profiled column. 


Standard Deviation 
Displays the standard deviation of the values found in the profiled column. 


Profile Type = Column Value Distribution Profile 


Column Value Distribution Profile - <column> pane 
Number of Distinct Values 
Displays the count of distinct values found in the profiled column. 


Row Count 
Displays the number of rows in the table or view. 


Detailed Value Distribution pane 
Value 
Displays the distinct values found in the profiled column. 


Count 
Displays the number of rows in which the profiled column has the value shown in the Value column. 


Percentage 
Displays the percentage of rows in which the profiled column has the value shown in the Value column. 


Profile Type = Candidate Key Profile 


Candidate Key Profile - <table> pane 
Key Columns 
Displays the columns that were selected for profiling as a candidate key. 


Key Strength 
Displays the strength (as a percentage) of the candidate key column or combination of columns. A key strength 
of less than 100% indicates that duplicate values exist. 


Key Violations pane 
<column1>, <column2>, etc. 
Displays the duplicate values that were found in the profiled column. 


Count 

Displays the number of rows in which the specified column has the value shown in the first column. 

Profile Type = Functional Dependency Profile 

Functional Dependency Profile pane 

Determinant Columns 

Displays the column or columns selected as the determinant column. In the example where the same United 
States Zip Code should always have the same state, the Zip Code is the determinant column. 


Dependent Columns 
Displays the column or columns selected as the dependent column. In the example where the same United 
States Zip Code should always have the same state, the state is the dependent column. 


Functional Dependency Strength 

Displays the strength (as a percentage) of the functional dependency between columns. A key strength of less 
than 100% indicates that there are cases where the determinant value does not determine the dependent value. 
In the example where the same United States Zip Code should always have the same state, this probably 
indicates some state values are not valid. 


Functional Dependency Violations pane 





NOTE 


A high percentage of erroneous values in the data could lead to unexpected results from a Functional Dependency profile. 
For example, 90% of the rows have a State value of "WI" for a Postal Code value of "98052." The profile reports rows that 


contain the correct state value of "WA" as violations. 





<determinant column name> 


Displays the value of the determinant column or combination of columns in this instance of a functional 





dependency violation. 


<dependent column name> 


Displays the value of the dependent column in this instance of a functional dependency violation. 


Support Count 
Displays the number of rows in which the determinant column value determines the dependent column. 


Violation Count 
Displays the number of rows in which the determinant column value does not determine the dependent column. 
(These are the rows where the dependent value is the value shown in the <dependent column name> 


column.) 


Support Percentage 
Displays the percentage of rows in which the determinant column determines the dependent column. 


Profile Type = Value Inclusion Profile 


Value Inclusion Profile pane 
Subset Side Columns 
Displays the column or combination of columns that were profiled to determine whether they are in the 


superset columns. 


Superset Side Columns 
Displays the column or combination of columns that were profiled to determine whether they include the values 
in the subset columns. 


Inclusion Strength 
Displays the strength (as a percentage) of the overlap between columns. A key strength of less than 100% 
indicates that there are cases where the subset value is not found among the superset values. 


Inclusion Violations pane 
<column1>, <column2>, etc. 


Displays the values in the subset column or columns that were not found in the superset column or columns. 


Count 


Displays the number of rows in which the specified column has the value shown in the first column. 


Data Profiling Task 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


The Data Profiling task computes various profiles that help you become familiar with a data source and identify 
problems in the data that have to be fixed. 


You can use the Data Profiling task inside an Integration Services package to profile data that is stored in SQL 
Server and to identify potential problems with data quality. 





NOTE 


This topic only describes the features and requirements of the Data Profiling task. For a walkthrough of how to use the 
Data Profiling task, see the section, Data Profiling Task and Viewer. 








Requirements and Limitations 


The Data Profiling task works only with data that is stored in SQL Server. This task does not work with third- 
party or file-based data sources. 


Furthermore, to run a package that contains the Data Profiling task, you must use an account that has 
read/write permissions, including CREATE TABLE permissions, on the tempdb database. 


Data Profiler Viewer 


After using the task to compute data profiles and save them in a file, you can use the stand-alone Data Profile 
Viewer to review the profile output. The Data Profile Viewer also supports drilldown capability to help you 
understand data quality issues tha are identified in the profile output. For more information, see Data Profile 
Viewer. 





IMPORTANT 


The output file might contain sensitive data about your database and the data that the database contains. For 


suggestions about how to make this file more secure, see Access to Files Used by Packages. 


The drilldown capability, that is available in the Data Profile Viewer, sends live queries to the original data source. 








Available Profiles 


The Data Profiling Task can compute eight different data profiles. Five of these profiles analyze individual 
columns, and the remaining three analyze multiple columns or relationships between columns and tables. 


The following five profiles analyze individual columns. 


PROFILES THAT ANALYZE INDIVIDUAL COLUMNS DESCRIPTION 


PROFILES THAT ANALYZE INDIVIDUAL COLUMNS 


Column Length Distribution Profile 


Column Null Ratio Profile 


Column Pattern Profile 


Column Statistics Profile 


Column Value Distribution Profile 


DESCRIPTION 


Reports all the distinct lengths of string values in the 
selected column and the percentage of rows in the table that 
each length represents. 


This profile helps you identify problems in your data, such as 
values that are not valid. For example, you profile a column 
of United States state codes that should be two characters 
and discover values longer than two characters. 


Reports the percentage of null values in the selected column. 


This profile helps you identify problems in your data, such as 
an unexpectedly high ratio of null values in a column. For 
example, you profile a Zip Code/Postal Code column and 
discover an unacceptably high percentage of missing codes. 


Reports a set of regular expressions that cover the specified 
percentage of values in a string column. 


This profile helps you identify problems in your data, such as 
string that are not valid. This profile can also suggest regular 
expressions that can be used in the future to validate new 
values. For example, a pattern profile of a United States Zip 
Code column might produce the regular expressions: \d{5}- 
\d{4}, \d{5}, and \d{9}. If you see other regular expressions, 
your data likely contains values that are not valid or in an 
incorrect format. 


Reports statistics, such as minimum, maximum, average, and 
standard deviation for numeric columns, and minimum and 
maximum for datetime columns. 


This profile helps you identify problems in your data, such as 
dates that are not valid. For example, you profile a column of 
historical dates and discover a maximum date that is in the 
future. 


Reports all the distinct values in the selected column and the 
percentage of rows in the table that each value represents. 
Can also report values that represent more than a specified 
percentage of rows in the table. 


This profile helps you identify problems in your data, such as 
an incorrect number of distinct values in a column. For 
example, you profile a column that is supposed to contain 
states in the United States and discover more than 50 
distinct values. 


The following three profiles analyze multiple columns or relationships between columns and tables. 


PROFILES THAT ANALYZE MULTIPLE COLUMNS 


Candidate Key Profile 


DESCRIPTION 


Reports whether a column or set of columns is a key, or an 
approximate key, for the selected table. 


This profile also helps you identify problems in your data, 
such as duplicate values in a potential key column. 


PROFILES THAT ANALYZE MULTIPLE COLUMNS 


Functional Dependency Profile 


Value Inclusion Profile 


Prerequisites for a Valid Profile 


DESCRIPTION 


Reports the extent to which the values in one column (the 
dependent column) depend on the values in another column 
or set of columns (the determinant column). 


This profile also helps you identify problems in your data, 
such as values that are not valid. For example, you profile 
the dependency between a column that contains United 
States Zip Codes and a column that contains states in the 
United States. The same Zip Code should always have the 
same state, but the profile discovers violations of this 
dependency. 


Computes the overlap in the values between two columns or 
sets of columns. This profile can determine whether a 
column or set of columns is appropriate to serve as a foreign 
key between the selected tables. 


This profile also helps you identify problems in your data, 
such as values that are not valid. For example, you profile 
the ProductID column of a Sales table and discover that the 
column contains values that are not found in the ProductID 
column of the Products table. 


A profile is not valid unless you select tables and columns that are not empty, and the columns contain data 


types that are valid for the profile. 


Valid Data Types 


Some of the available profiles are meaningful only for certain data types. For example, computing a Column 


Pattern profile for a column that contains numeric or datetime values is not meaningful. Therefore, such a 


profile is not valid. 
PROFILE 


ColumnStatisticsProfile 


ColumnNullRatioProfile 


ColumnValueDistributionProfile 


ColumnLengthDistributionProfile 


ColumnPatternProfile 


CandidateKeyProfile 


FunctionalDependencyProfile 


InclusionProfile 


VALID DATA TYPES* 


Columns of numeric type or datetime type (no mean and 
stddev for datetime column) 


All columns** 


Columns of integer type, char type, and datetime type 


Columns of char type 


Columns of char type 


Columns of integer type, char type, and datetime type 


Columns of integer type, char type, and datetime type 


Columns of integer type, char type, and datetime type 


* In the previous table of valid data types, the integer, char, datetime, and numeric types include the 


following specific data types: 


Integer types include bit, tinyint, smallint, int, and bigint. 


Character types include char, nchar, varchar, and nvarchar, but do not include varchar(max) and 
nvarchar(max). 


Date and time types include datetime, smalldatetime, and timestamp. 
Numeric types include integer types (except bit), money, smallmoney, decimal, float, real, and numeric. 


** image, text, XML, udt, and variant types are not supported for profiles other than the Column Null Ratio 
Profile. 


Valid Tables and Columns 


If the table or column is empty, the Data Profiling takes the following actions: 
e When the selected table or view is empty, the Data Profiling task does not compute any profiles. 


e@ When all the values in the selected column are null, the Data Profiling task computes only the Column 
Null Ratio profile. The task does not compute the Column Length Distribution profile, Column Pattern 
profile, Column Statistics profile, or Column Value Distribution profile. 


Features of the Data Profiling Task 
The Data Profiling task has these convenient configuration options: 


e Wildcard columns When you are configuring a profile request, the task accepts the (*) wildcard in 
place of a column name. This simplifies the configuration and makes it easier to discover the 
characteristics of unfamiliar data. When the task runs, the task profiles every column that has an 
appropriate data type. 


e@ Quick Profile You can select Quick Profile to configure the task quickly. A Quick Profile profiles a table or 
view by using all the default profiles and default settings. 


Custom Logging Messages Available on the Data Profililng Task 


The following table lists the custom log entries for the Data Profiling task. For more information, see Integration 
Services (SSIS) Logging. 


LOG ENTRY DESCRIPTION 


DataProfilingTaskTrace Provides descriptive information about the status of the 
task. Messages include the following information: 


Start Processing Requests 
Query Start 
Query End 


Finish Computing Request 


Output and Its Schema 


The Data Profiling task outputs the selected profiles into XML that is structured according to the DataProfile.xsd 
schema. You can specify whether this XML output is saved in a file or in a package variable. You can view this 
schema online at https://schemas.microsoft.com/sqlserver/2008/DataDebugger/. From the webpage, you can 
save a local copy of the schema. You can then view the local copy of the schema in Microsoft Visual Studio or 
another schema editor, in an XML editor, or in a text editor such as Notepad. 


This schema for data quality information could be useful for: 
e Exchanging data quality information within and across organizations. 
e Building custom tools that work with data quality information. 


The target namespace is identified in the schema as 
https://schemas.microsoft.com/sqlserver/2008/DataDebugger/. 


Output in the Conditional Workflow of a Package 


The data profiling components do not include built-in functionality to implement conditional logic in the 
workflow of the Integration Services package based on the output of the Data Profiling task. However, you can 
easily add this logic, with a minimal amount of programming, in a Script task. This code would perform an XPath 
query against the XML output, and then save the result in a package variable. Precedence constraints that 
connect the Script task to subsequent tasks can use an expression to determine the workflow. For example, the 
Script task detects that the percentage of null values in a column exceeds a certain threshold. When this 
condition is true, you might want to interrupt the package and resolve the problem before continuing. 


Configuration of the Data Profiling Task 
You configure the Data Profiling task by using the Data Profiling Task Editor. The editor has two pages: 


General Page 

On the General page, you specify the output file or variable. You can also select Quick Profile to configure the 
task quickly to compute profiles by using the default settings. For more information, see Single Table Quick 
Profile Form (Data Profiling Task). 


Profile Requests Page 

On the Profile Requests page, you specify the data source, and select and configure the data profiles that you 
want to compute. For more information about the various profiles that you can configure, see the following 
topics: 


e Candidate Key Profile Request Options (Data Profiling Task) 

e Column Length Distribution Profile Request Options (Data Profiling Task) 
e Column Null Ratio Profile Request Options (Data Profiling Task) 

e@ Column Pattern Profile Request Options (Data Profiling Task) 

e Column Statistics Profile Request Options (Data Profiling Task) 

e Column Value Distribution Profile Request Options (Data Profiling Task) 
e Functional Dependency Profile Request Options (Data Profiling Task) 


e Value Inclusion Profile Request Options (Data Profiling Task) 


Single Table Quick Profile Form (Data Profiling Task) 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Use the Single Table Quick Profile Form to configure the Data Profiling task quickly to profile a single table 
or view by using default settings. 


For more information about how to use the Data Profiling Task, see Setup of the Data Profiling Task. For more 
information about how to use the Data Profile Viewer To analyze the output of the Data Profiling Task, see Data 
Profile Viewer. 


Options 


Connection 
Select an existing ADO.NET connection manager that uses the .NET Data Provider for SQL Server (SqlClient) to 
connect to the SQL Server database that contains the table or view to be profiled. 


Table or View 


Select an existing table or view in the database to which the selected connection manager connects. 


Compute 
Select which profiles to compute. 


VALUE DESCRIPTION 

Column Null Ratio Profile Compute a Column Null Ratio profile by using the default 
settings for all applicable columns in the selected table or 
view. 


This profile reports the percentage of null values in the 
selected column. This profile can help you identify problems 
in your data such as an unexpectedly high ratio of null 
values in a column. For more information about the settings 
for this profile, see Column Null Ratio Profile Request 
Options (Data Profiling Task). 


Column Statistics Profile Compute a Column Statistics profile by using the default 
settings for all applicable columns in the selected table or 
view. 


This profile reports statistics such as minimum, maximum, 
average, and standard deviation for numeric columns, and 
minimum and maximum for datetime columns. This profile 
can help you identify problems in your data such as invalid 
dates. For more information about the settings for this 
profile, see Column Statistics Profile Request Options (Data 
Profiling Task). 


VALUE 


Column Value Distribution Profile 


Column Length Distribution Profile 


Column Pattern Profile 


Candidate Key Profile 


for up to N Column keys 


DESCRIPTION 


Compute a Column Value Distribution profile by using the 
default settings for all applicable columns in the selected 
table or view. 


This profile reports all the distinct values in the selected 
column and the percentage of rows in the table that each 
value represents. This profile can also report values that 
represent more than a specified percentage of rows in the 
table. This profile can help you identify problems in your 
data such as an incorrect number of distinct values in a 
column. For more information about this profile, see Column 
Value Distribution Profile Request Options (Data Profiling 
Task). 


Compute a Column Length Distribution profile by using the 
default settings for all applicable columns in the selected 
table or view. 


This profile reports all the distinct lengths of string values in 
the selected column and the percentage of rows in the table 
that each length represents. This profile can help you identify 
problems in your data, such as values that are not valid. For 
more information about the settings for this profile, see 
Column Length Distribution Profile Request Options (Data 
Profiling Task). 


Compute a Column Pattern profile by using the default 
settings for all applicable columns in the selected table or 
view. 


This profile reports a set of regular expressions that cover 
the values in a string column. This profile can help you 
identify problems in your data, such as strings that are not 
valid. This profile can also suggest regular expressions that 
can be used in the future to validate new values. For more 
information about the settings for this profile, see Column 
Pattern Profile Request Options (Data Profiling Task). 


Compute a Candidate Key profile for column combinations 
that include up to the number of columns that is specified in 
for up to N Column keys. 


This profile reports whether a column or set of columns is 
appropriate to serve as a key for the selected table. This 
profile can also help you identify problems in your data, such 
as duplicate values in a potential key column. For more 
information about the settings for this profile, see Candidate 
Key Profile Request Options (Data Profiling Task). 


Select the maximum number of columns to test in possible 
combinations as a key for the table or view. The default value 
is 1. The maximum value is 1000. For example, selecting 3 
tests one-column, two-column, and three-column key 
combinations. 


VALUE DESCRIPTION 


Functional Dependency Profile Compute a Functional Dependency profile for determinant 
column combinations that include up to the number of 
columns that is specified in for up to N Columns as the 
determiner. 


This profile reports the extent to which the values in one 
column (the dependent column) depend on the values in 
another column or set of columns (the determinant column). 
This profile can also help you identify problems in your data, 
such as values that are not valid. For more information 
about the settings for this profile, see Functional 
Dependency Profile Request Options (Data Profiling Task). 


for up to N Columns as the determiner Select the maximum number of columns to test in possible 
combinations as the determinant columns. The default value 
is 1. The maximum value is 1000. For example, selecting 2 
tests combinations in which either single columns or two- 
column combinations are the determinant columns for 
another (dependent) column. 





NOTE 


The Value Inclusion Profile type is not available from the Single Table Quick Profile Form. 





See Also 


Data Profiling Task Editor (General Page) 
Data Profiling Task Editor (Profile Requests Page) 


Data Profiling Task Editor (Profile Requests Page) 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Use the Profile Requests Page of the Data Profiling Task Editor to select and configure the profiles that 
you want to compute. In a single Data Profiling task, you can compute multiple profiles for multiple columns or 
combinations of columns in multiple tables or views. 


For more information about how to use the Data Profiling Task, see Setup of the Data Profiling Task. For more 
information about how to use the Data Profile Viewer to analyze the output of the Data Profiling Task, see Data 
Profile Viewer. 


To open the Profile Requests page of the Data Profiling Task Editor 
1. In SQL Server Data Tools (SSDT), open the Integration Services package that has the Data Profiling task. 
2. On the Control Flow tab, double-click the Data Profiling task. 


3. In the Data Profiling Task Editor, click Profile Requests. 


Using the Requests Pane 


The requests pane is the pane that appears at the top of the page. This pane lists all the profiles that have been 
configured for the current Data Profiling task. If no profiles have been configured, the requests pane is empty. To 
add a new profile, click in an empty area under the Profile Type column and select a profile type from the list. 
To configure a profile, select the profile in the requests pane, and then set the profile's properties in the Request 
Properties pane. 

Requests Pane Options 

The request pane has the following options: 

View 


Select whether to view all the profiles that have been configured for the task or just one of the profiles. 


The columns in the requests pane changed based on the View that you select. For more information about each 
of those columns, see the next section, "Requests Pane Columns." 


Requests Pane Columns 


The columns that the requests pane displays depend on the View that you have selected: 
e If you select to view All Requests, the requests pane has two columns: Profile Type and Request ID. 


e If you select to view one of the five column profiles, the request pane has four columns: Profile Type, 
Table or View, Column, and Request ID. 


e If you select to view a Candidate Key profile, the request pane has four columns: Profile Type, Table or 
View, KeyColumns, and Request ID. 


e If you select to view a Functional Dependency profile, the request pane has five columns: Profile Type, 
Table or View, Determinant Columns, Dependent Column, and Request ID. 


e If you select to view a Value Inclusion Profile, the request pane has six columns: Profile Type, Subset 
Side Table or View, Superset Side Table or View, Subset Side Columns, Superset Side 
Columns, and Request ID. 


The following sections describe each of those columns. 


Columns Common to All Views 
Profile Type 
Select a data profile from the following options: 


VALUE 


Candidate Key Profile Request 


Column Length Distribution Profile Request 


Column Null Ratio Profile Request 


Column Pattern Profile Request 


Column Statistics Profile Request 


DESCRIPTION 


Compute a Candidate Key Profile. 


This profile This profile reports whether a column or set of 
columns is a key, or an approximate key, for the selected 
table. This profile can also help you identify problems in your 
data, such as duplicate values in a potential key column. 


Compute a Column Length Distribution Profile. 


The Column Length Distribution Profile reports all the 
distinct lengths of string values in the selected column and 
the percentage of rows in the table that each length 
represents. This profile can help you identify problems in 
your data, such as values that are not valid. For example, 
you profile a column of two-character United States state 
codes and discover values longer than two characters. 


Compute a Column Null Ratio Profile. 


The Column Null Ratio Profile reports the percentage of null 
values in the selected column. This profile can help you 
identify problems in your data such as an unexpectedly high 
ratio of null values in a column. For example, you profile a 
Zip Code/Postal Code column and discover an unacceptably 
high percentage of missing codes. 


Compute a Column Pattern Profile. 


The Column Pattern Profile reports a set of regular 
expressions that cover the specified percentage of values in a 
string column. This profile can help you identify problems in 
your data, such as strings that are not valid strings. This 
profile can also suggest regular expressions that can be used 
in the future to validate new values. For example, a pattern 
profile of a Zip Code/Postal Code column might produce the 
regular expressions: \d{5}-\d{4}, \d{5}, and \d{9}. If you see 
other regular expressions, your data likely contains values 
that are not valid or in an incorrect format. 


Select this option to compute a Column Statistics Profile 
using the default settings for all applicable columns in the 
selected table or view. 


The Column Statistics Profile reports statistics such as 
minimum, maximum, average, and standard deviation for 
numeric columns, and minimum and maximum for 
datetime columns. This profile can help you identify 
problems in your data, such as dates that are not valid. For 
example, you profile a column of historical dates and 
discover a maximum date that is in the future. 


VALUE 


Column Value Distribution Profile Request 


Functional Dependency Profile Request 


Value Inclusion Profile Request 


RequestID 


DESCRIPTION 


Compute a Column Value Distribution Profile. 


The Column Value Distribution Profile reports all the distinct 
values in the selected column and the percentage of rows in 
the table that each value represents. This profile can also 
report values that represent more than a specified 
percentage in the table. This profile can help you identify 
problems in your data such as an incorrect number of 
distinct values in a column. For example, you profile a 
column that contains states in the United States and 
discover more than 50 distinct values. 


Compute a Functional Dependency Profile. 


The Functional Dependency Profile reports the extent to 
which the values in one column (the dependent column) 
depend on the values in another column or set of columns 
(the determinant column). This profile can also help you 
identify problems in your data, such as values that are not 
valid. For example, you profile the dependency between a 
column of United States Zip Codes and a column of states in 
the United States. The same Zip Code should always have 
the same state, but the profile discovers violations of this 
dependency. 


Compute a Value Inclusion Profile. 


The Value Inclusion Profile computes the overlap in the 
values between two columns or sets of columns. This profile 
can also determine whether a column or set of columns is 
appropriate to serve as a foreign key between the selected 
tables. This profile can also help you identify problems in 
your data such as values that are not valid. For example, you 
profile the ProductID column of a Sales table and discover 
that the column contains values that are not found in the 
ProductID column of the Products table. 


Displays the identifier for the request. Typically, you do not have to change the autogenerated value. 


Columns Common to All Individual Profiles 


Connection Manager 


Displays the ADO.NET connection manager that connects to the source database. 


Request ID 


Displays an identifier for the request. Typically, you do not have to change the autogenerated value. 


Columns Common to the Five Individual Column Profiles 


Table or View 


Displays the table or view that contains the selected column. 


Column 


Displays the column selected for profiling. 


Columns Specific to the Candidate Key Profile 


Table or View 


Displays the table or view that contains the selected columns. 


Key Columns 


Displays the columns selected for profiling. 


Columns Specific to the Functional Dependency Profile 
Table or View 
Displays the table or view that contains the selected columns. 


Determinant Columns 

Displays the columns selected for profiling as the determinant column or columns. In the example where the 
United States Zip Code determines the state in the United States, the determinant column is the Zip Code 
column. 


Dependent column 
Displays the columns selected for profiling as the dependent column. In the example where the United States Zip 
Code determines the state in the United States, the dependent column is the state column. 


Columns Specific to the Value Inclusion Profile 
Subset Side Table or View 
Displays the table or view that contains the column or columns selected as the subset side columns. 


Superset Side Table or View 
Displays the table or view that contains the column or columns selected as the superset side columns. 


Subset Side Columns 

Displays the column or columns selected for profiling as the subset side columns. In the example where you 
want to verify that the values in a US state column are found in a reference table of two-character US state 
codes, the subset column is the state column in the source table. 


Superset Side Columns 

Displays the column or columns selected for profiling as the superset side columns. In the example where you 
want to verify that the values in a US state column are found in a reference table of two-character US state 
codes, the superset column is the column of state codes in the reference table. 


Using the Request Properties Pane 


The Request Properties pane appears underneath the requests pane. This pane displays the options for the 
profile that you have selected in the requests pane. 


NOTE 


After you select a Profile Type, you must select the Request ID field to see the properties for the profile request in the 


Request Properties pane. 





These options vary based on the selected profile. For information about the options for individual profile types, 
see the following topics: 


e Candidate Key Profile Request Options (Data Profiling Task) 

e Column Null Ratio Profile Request Options (Data Profiling Task) 

e Column Statistics Profile Request Options (Data Profiling Task) 

e Column Value Distribution Profile Request Options (Data Profiling Task) 
e Column Length Distribution Profile Request Options (Data Profiling Task) 
e Column Pattern Profile Request Options (Data Profiling Task) 


e Functional Dependency Profile Request Options (Data Profiling Task) 


e Value Inclusion Profile Request Options (Data Profiling Task) 


See Also 


Data Profiling Task Editor (General Page) 
Single Table Quick Profile Form (Data Profiling Task) 





Candidate Key Profile Request Options (Data 


Profiling Task) 
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Applies to: Q sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Use the Request Properties pane of the Profile Requests page to set the options for the Candidate Key 
Profile Request that is selected in the requests pane. A Candidate Key profile reports whether a column or set 
of columns is a key, or an approximate key, for the selected table. This profile can also help you identify 
problems in your data such as duplicate values in a potential key column. 





NOTE 


The options described in this topic appear on the Profile Requests page of the Data Profiling Task Editor. For more 
information about this page of the editor, see Data Profiling Task Editor (Profile Requests Page). 











For more information about how to use the Data Profiling Task, see Setup of the Data Profiling Task. For more 
information about how to use the Data Profile Viewer to analyze the output of the Data Profiling Task, see Data 
Profile Viewer. 


Understanding the Selection of Columns for the KeyColumns 
Property 


Each Candidate Key Profile Request computes the key strength of a single key candidate that consists of a 
single column or of multiple columns: 


e When you select only one column in KeyColumns, the task computes the key strength of that one 
column. 


e When you select multiple columns in KeyColumns, the task computes the key strength of the composite 
key that consists of all the selected columns. 


e When you select the wildcard character, (*), in KeyColumns, the task computers the key strength of each 
column in the table or view. 


For example, consider a sample table that contains columns A, B, and C. You make the following selections for 
KeyColumns: 


e You select (*) and column C in KeyColumns. The task computes the key strength of column C, and then 
of composite key candidates (A, C) and (B, C). 


e You select (*) and (*) in KeyColumns. The task computes the key strength of individual columns A, B, and 
C, and then of composite key candidates (A, B), (A, C) and (B, C). 


NOTE 


If you select (*), this option might result in a large number of computations and decrease the performance of the task. 
However, if the task finds a subset that satisfies the threshold for a key, the task does not analyze additional 
combinations. For example, in the sample table described above, if the task determines that column C is a key, the task 
does not continue to analyze the composite key candidates. 





Request Properties Options 


For a Candidate Key Profile Request, the Request Properties pane displays the following groups of 
options: 


e Data, which includes the TableOrView and KeyColumns options 
e General 
e Options 


Data Options 

ConnectionManager 

Select the existing ADO.NET connection manager that uses the .NET Data Provider for SQL Server (SqlClient) to 
connect to the SQL Server database that contains the table or view to be profiled. 


TableOrView 
Select the existing table or view to be profiled. 


For more information, see the section, "TableorView Options," in this topic. 


KeyColumns 
Select the existing column or columns to be profiled. Select (*) to profile all columns. 


For more information, see the sections, "Understanding the Selection of Columns for the KeyColumns Property 
and "KeyColumns Options,” in this topic. 


TableOrView Options 
Schema 
Specify the schema to which the selected table belongs. This option is read-only. 


Table 
Displays the name of the selected table. This option is read-only. 


KeyColumns Options 
The following options are presented for each column selected for profiling in KeyColumns, or for the (*) 


option. 


For more information, see the section, "Understanding the Selection of Columns for the KeyColumns Property," 


earlier in this topic. 


IsWildcard 
Specifies whether the (*) wildcard has been selected. This option is set to True if you have selected (*) to profile 
all columns. It is False if you have selected an individual column to be profiled. This option is read-only. 


ColumnName 
Displays the name of the selected column. This option is blank if you have selected (*) to profile all columns. 
This option is read-only. 


StringCompareOptions 
Select options for comparing string values. This property has the options listed in the following table. The 
default value of this option is Default. 





NOTE 


When you use a (*) wildcard for ColumnName, CompareOptions is read-only and is set to the Default setting. 





VALUE 


Default 


BinarySort 


DictionarySort 


DESCRIPTION 


Sorts and compares data based on the column's collation in 
the source table. 


Sorts and compares data based on the bit patterns defined 
for each character. Binary sort order is case sensitive and 
accent sensitive. Binary is also the fastest sorting order. 


Sorts and compares data based on the sorting and 
comparison rules as defined in dictionaries for the associated 
language or alphabet. 


If you select DictionarySort, you can also select any combination of the options listed in the following table. By 


default, none of these additional options are selected. 


VALUE 


IgnoreCase 


IgnoreNonSpace 


IgnoreKanaType 


IgnoreWidth 


General Options 


RequestID 


DESCRIPTION 


Specifies whether the comparison distinguishes between 
uppercase and lowercase letters. If this option is set, the 
string comparison ignores case. For example, "ABC" becomes 
the same as "abc". 


Specifies whether the comparison distinguishes between 
spacing characters and diacritics. If this option is set, the 
comparison ignores diacritics. For example, "A¥" is equal to 


a. 


Specifies whether the comparison distinguishes between the 
two types of Japanese kana characters: hiragana and 
katakanaa. If this option is set, the string comparison ignores 
kana type. 


Specifies whether the comparison distinguishes between a 
single-byte character and the same character when it is 
represented as a double-byte character. If this option is set, 
the string comparison treats single-byte and double-byte 
representations of the same character as identical. 


Type a descriptive name to identify this profile request. Typically, you do not have to change the autogenerated 


value. 


Options 


ThresholdSetting 


This property has the options listed in the following table. The default value of this property is Specified. 


VALUE 


None 


Specified 


DESCRIPTION 


No threshold is specified. The key strength is reported 
regardless of its value. 


A threshold is specified in KeyStrengthThreshold. The key 
strength is reported only if it is greater than the threshold. 


VALUE DESCRIPTION 


Exact No threshold is specified. The key strength is reported only if 
the selected columns are an exact key. 


KeyStrengthThreshold 

Specify the threshold (by using a value between 0 and 1) above which the key strength should be reported. The 
default value of this property is 0.95. This option is enabled only when Specified is selected as the 
KeyStrengthThresholdSetting. 


MaxNumberOfViolations 
Specify the maximum number of candidate key violations to report in the output. The default value of this 
property is 100. This option is disabled when Exact is selected as the KeyStrengthThresholdSetting. 


See Also 


Data Profiling Task Editor (General Page) 
Single Table Quick Profile Form (Data Profiling Task) 


Column Length Distribution Profile Request Options 


(Data Profiling Task) 


11/23/2021 + 2 minutes to read * Edit Online 





Applies to: Q sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Use the Request Properties pane of the Profile Requests page to set the options for the Column Length 
Distribution Profile Request selected in the requests pane. A Column Length Distribution profile reports all 
the distinct lengths of string values in the selected column and the percentage of rows in the table that each 
length represents. This profile can help you identify problems in your data such as invalid values. For example, 
you profile a column of two-character United States state codes and discover values longer than two characters. 


NOTE 


The options described in this topic appear on the Profile Requests page of the Data Profiling Task Editor. For more 


information about this page of the editor, see Data Profiling Task Editor (Profile Requests Page). 





For more information about how to use the Data Profiling Task, see Setup of the Data Profiling Task. For more 
information about how to use the Data Profile Viewer to analyze the output of the Data Profiling Task, see Data 
Profile Viewer. 


Request Properties Options 


For aColumn Length Distribution Profile Request, the Request Properties pane displays the following 
groups of options: 


e Data, which includes the TableOrView and Column options 
e General 
e Options 


Data Options 


ConnectionManager 
Select the existing ADO.NET connection manager that uses the .NET Data Provider for SQL Server (SqlClient) to 
connect to the SQL Server database that contains the table or view to be profiled. 


TableOrView 
Select the existing table or view that contains the column to be profiled. 


For more information, see the section, "TableorView Options,” in this topic. 


Column 


Select the existing column to be profiled. Select (*) to profile all columns. 


For more information, see the section, "Column Options," in this topic. 


TableOrView Options 
Schema 
Specify the schema to which the selected table belongs. This option is read-only. 


Table 


Displays the name of the selected table. This option is read-only. 


Column Options 

IsWildCard 

Specifies whether the (*) wildcard has been selected. This option is set to True if you have selected (*) to profile 
all columns. It is False if you have selected an individual column to be profiled. This option is read-only. 


ColumnName 
Displays the name of the selected column. This option is blank if you have selected (*) to profile all columns. 
This option is read-only. 


StringCompareOptions 
This option does not apply to the Column Length Distribution Profile. 


General Options 


RequestID 
Type a descriptive name to identify this profile request. Typically, you do not have to change the autogenerated 
value. 


Options 
IgnoreLeadingSpaces 


Indicate whether to ignore leading spaces when the profile compares string values. The default value of this 
option is False. 


IgnoreTrailingS paces 
Indicate whether to ignore trailing spaces when the profile compares string values. The default value of this 
option is True. 


See Also 


Data Profiling Task Editor (General Page) 
Single Table Quick Profile Form (Data Profiling Task) 


Column Null Ratio Profile Request Options (Data 


Profiling Task) 
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Applies to: Q sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Use the Request Properties pane of the Profile Requests page to set the options for the Column Null 
Ratio Request selected in the requests pane. A Column Null Ratio profile reports the percentage of null values 
in the selected column. This profile can help you identify problems in your data such as an unexpectedly high 
ratio of null values in a column. For example, a Column Null Ratio profile can profile a ZIP Code/Postal Code 
column and discover an unacceptably high percentage of missing postal codes. 


NOTE 


The options described in this topic appear on the Profile Requests page of the Data Profiling Task Editor. For more 


information about this page of the editor, see Data Profiling Task Editor (Profile Requests Page). 





For more information about how to use the Data Profiling Task, see Setup of the Data Profiling Task. For more 
information about how to use the Data Profile Viewer to analyze the output of the Data Profiling Task, see Data 
Profile Viewer. 


Request Properties Options 

For aColumn Null Ratio Request, the Request Properties pane displays the following groups of options: 
e Data, which includes the TableOrView and Column options 

e General 


Data Options 


ConnectionManager 
Select the existing ADO.NET connection manager that uses the.NET Data Provider for SQL Server (SqIClient) to 
connect to the SQL Server database that contains the table or view to be profiled. 


TableOrView 
Select the existing table or view that contains the column to be profiled. 


For more information, see the section, "TableorView Options,” in this topic. 


Column 
Select the existing column to be profiled. Select (*) to profile all columns. 
For more information, see the section, "Column Options," in this topic. 


TableOrView Options 
Schema 
Specifies the schema to which the selected table belongs. This option is read-only. 


Table 
Displays the name of the selected table. This option is read-only. 


Column Options 


IsWildCard 


Specifies whether the (*) wildcard has been selected. This option is set to True if you have selected (*) to profile 
all columns. It is False if you have selected an individual column to be profiled. This option is read-only. 


ColumnName 
Displays the name of the selected column. This option is blank if you have selected (*) to profile all columns. 
This option is read-only. 


StringCompareOptions 
This option does not apply to the Column Null Ratio Profile. 


General Options 


RequestID 
Type a descriptive name to identify this profile request. Typically, you do not have to change the autogenerated 
value. 


See Also 


Data Profiling Task Editor (General Page) 
Single Table Quick Profile Form (Data Profiling Task) 


Column Pattern Profile Request Options (Data 


Profiling Task) 


11/23/2021 + 5 minutes to read * Edit Online 





Applies to: Q sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Use the Request Properties pane of the Profile Requests page to set the options for the Column Pattern 
Profile Request selected in the requests pane. A Column Pattern profile reports a set of regular expressions 
that cover the specified percentage of values in a string column. This profile can help you identify problems in 
your data, such as invalid strings, and can suggest regular expressions that can be used in the future to validate 
new values. For example, a pattern profile of a column of United States Zip Codes might produce the regular 
expressions \d{5}-\d{4}, \d{5}, and \d{9}. If you see other regular expressions, your data likely contains values 
that are invalid or in an incorrect format. 


NOTE 


The options described in this topic appear on the Profile Requests page of the Data Profiling Task Editor. For more 


information about this page of the editor, see Data Profiling Task Editor (Profile Requests Page). 





For more information about how to use the Data Profiling Task, see Setup of the Data Profiling Task. For more 
information about how to use the Data Profile Viewer to analyze the output of the Data Profiling Task, see Data 
Profile Viewer. 


Understanding the Use of Delimiters and Symbols 


Before computing the patterns for aColumn Pattern Profile Request, the Data Profiling Task tokenizes the 
data. That is, the task separates the string values into smaller units known as tokens. The task separates strings 
into tokens based on the delimiters and symbols that you specify for the Delimiters and Symbols properties: 


e Delimiters By default, the list of delimiters contains the following characters: space, horizontal tab (\t), 
new line (\n), and carriage return (\r). You can specify additional delimiters, but you cannot remove the 
default delimiters. 


e Symbols By default, the list of Symbols contains the following characters: ,.;:-"'~=&/@!?()<>[]{}|#*4% 
as well as the tick mark. For example, if the symbols are" ()- ", the value "(425) 123-4567" is tokenized 
as ["(", "425", ")", "123", "-", "4567", ")"]. 


A character cannot be both a delimiter and a symbol. 


All delimiters are normalized to a single space as part of the tokenizing process, while symbols are retained. 


Understanding the Use of the Tag Table 


You can optionally group related tokens with a single tag by storing tags and the related terms in a special table 
that you create in a SQL Server database. The tag table must have two string columns, one named "Tag" and the 
other named "Term". These columns can be of type char, nchar, varchar, or nvarchar, but not text or ntext. 
You can combine multiple tags and the corresponding terms in a single table. A Column Pattern Profile Request 
can use only one tag table. You can use a separate ADO.NET connection manager to connect to the tag table. 
Therefore, the tag table can be located in a different database or on a different server than the source data. 


For example, you could group the values "East", "West", "North", and "South" that might appear in street 
addresses by using the single tag, "Direction". The following table is an example of such a tag table. 


TAG TERM 
Direction East 
Direction West 
Direction North 
Direction South 


You could use another tag to group the different words that express the notion of a "street" in street addresses: 


TAG TERM 
Street Street 
Street Avenue 
Street Place 
Street Way 


Based on this combination of tags, the resulting pattern for a street address might resemble the following 
pattern: 


\d+\ LookupTag=Direction \d+\p{L}+\ LookupTag=Street 





NOTE 


Using a tag table decreases the performance of the Data Profiling task. Do not use more than 10 tags or more than 100 


terms per tag. 











The same term can belong to more than one tag. 


Request Properties Options 


For aColumn Pattern Profile Request, the Request Properties pane displays the following groups of 


options: 

e Data, which includes the TableOrView and Column options 
e General 

e Options 


Data Options 


ConnectionManager 
Select the existing ADO.NET connection manager that uses the .NET Data Provider for SQL Server (SqlClient) to 
connect to the SQL Server database that contains the table or view to be profiled. 


TableOrView 
Select the existing table or view that contains the column to be profiled. 


For more information, see the section, "TableorView Options," in this topic. 


Column 


Select the existing column to be profiled. Select (*) to profile all columns. 


For more information, see the section, "Column Options,” in this topic. 


TableOrView Options 
Schema 
Specifies the schema to which the selected table belongs. This option is read-only. 


Table 
Displays the name of the selected table. This option is read-only. 


Column Options 
IsWildCard 
Specifies whether the (*) wildcard has been selected. This option is set to True if you have selected (*) to profile 


all columns. It is False if you have selected an individual column to be profiled. This option is read-only. 


ColumnName 
Displays the name of the selected column. This option is blank if you have selected (*) to profile all columns. 
This option is read-only. 


StringCompareOptions 
This option does not apply to the Column Pattern Profile. 


General Options 


RequestID 
Type a descriptive name to identify this profile request. Typically, you do not have to change the autogenerated 
value. 


Options 
MaxNumberOfPatterns 


Specify the maximum number of patterns that you want the profile to compute. The default value of this option 
is 10. The maximum value is 100. 


PercentageDataCoverageDesired 
Specify the percentage of the data that you want the computed patterns to cover. The default value of this option 
is 95 (percent). 


CaseSensitive 
Indicate whether the patterns should be case-sensitive. The default value of this option is False. 


Delimiters 

List the characters that should be treated as the equivalent of spaces between words when tokenizing text. By 
default, the list of Delimiters contains the following characters: the space, horizontal tab (\t), new line (\n), and 
carriage return (\r). You can specify additional delimiters, but you cannot remove the default delimiters. 


For more information, see "Understanding the Use of Delimiters and Symbols" earlier in this topic. 


Symbols 
List the symbols that should be retained as part of patterns. Examples might include "/" for dates, ":" for times, 
and "@" for e-mail addresses. By default, the list of Symbols contains the following characters: 


pegic 's=8/@!2()<>[1{} |#*2% . 
For more information, see "Understanding the Use of Delimiters and Symbols" earlier in this topic. 


TagTableConnectionManager 
Select the existing ADO.NET connection manager that uses the .NET Data Provider for SQL Server (SqlClient) to 


connect to the SQL Server database that contains the tag table. 
For more information, see "Understanding the Use of the Tag Table" earlier in this topic. 


TagTableName 
Select the existing tag table, which must have two string columns named Tag and Term. 


For more information, see "Understanding the Use of the Tag Table" earlier in this topic. 


See Also 


Data Profiling Task Editor (General Page) 
Single Table Quick Profile Form (Data Profiling Task) 


Column Statistics Profile Request Options (Data 


Profiling Task) 
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Applies to: Q sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Use the Request Properties pane of the Profile Requests page to set the options for the Column Statistics 
Profile Request selected in the requests pane. A Column Statistics profile reports statistics such as minimum, 
maximum, average, and standard deviation for numeric columns, and minimum and maximum for datetime 
columns. This profile can help you identify problems in your data such as invalid dates. For example, you profile 
a column of historical dates and discover a maximum date that is in the future. 


NOTE 


The options described in this topic appear on the Profile Requests page of the Data Profiling Task Editor. For more 


information about this page of the editor, see Data Profiling Task Editor (Profile Requests Page). 





For more information about how to use the Data Profiling Task, see Setup of the Data Profiling Task. For more 
information about how to use the Data Profile Viewer to analyze the output of the Data Profiling Task, see Data 
Profile Viewer. 


Request Properties Options 


For aColumn Statistics Profile Request, the Request Properties pane displays the following groups of 
options: 


e Data, which includes the TableOrView and Column options 
e General 


Data Options 


ConnectionManager 
Select the existing ADO.NET connection manager that uses the .NET Data Provider for SQL Server (SqlClient) to 
connect to the SQL Server database that contains the table or view to be profiled. 


TableOrView 
Select the existing table or view that contains the column to be profiled. 


For more information, see the section, "TableorView Options,” in this topic. 


Column 


Select the existing column to be profiled. Select (*) to profile all columns. 


For more information, see the section, "Column Options," in this topic. 


TableOrView Options 
Schema 
Specifies the schema to which the selected table belongs. This option is read-only. 


Table 
Displays the name of the selected table. This option is read-only. 


Column Options 


IsWildCard 
Specifies whether the (*) wildcard has been selected. This option is set to True if you have selected (*) to profile 
all columns. It is False if you have selected an individual column to be profiled. This option is read-only. 


ColumnName 
Displays the name of the selected column. This option is blank if you have selected (*) to profile all columns. 
This option is read-only. 


StringCompareOptions 
This option does not apply to the Column Statistics Profile. 


General Options 


RequestID 
Type a descriptive name to identify this profile request. Typically, you do not have to change the autogenerated 


value. 


See Also 


Data Profiling Task Editor (General Page) 
Single Table Quick Profile Form (Data Profiling Task) 


Column Value Distribution Profile Request Options 


(Data Profiling Task) 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Use the Request Properties pane of the Profile Requests page to set the options for the Column Value 
Distribution Profile Request selected in the requests pane. A Column Value Distribution profile reports all 
the distinct values in the selected column and the percentage of rows in the table that each value represents. The 
profile can also report values that represent more than a specified percentage of rows in the table. This profile 
can help you identify problems in your data such as an incorrect number of distinct values in a column. For 
example, you profile a United States state column and discover more than 50 distinct values. 





NOTE 


The options described in this topic appear on the Profile Requests page of the Data Profiling Task Editor. For more 
information about this page of the editor, see Data Profiling Task Editor (Profile Requests Page). 











For more information about how to use the Data Profiling Task, see Setup of the Data Profiling Task. For more 
information about how to use the Data Profile Viewer to analyze the output of the Data Profiling Task, see Data 
Profile Viewer. 


Request Properties Options 


For aColumn Value Distribution Profile Request, the Request Properties pane displays the following 
groups of options: 


e Data, which includes the TableOrView and Column options 
e General 
e Options 


Data Options 


ConnectionManager 
Select the existing ADO.NET connection manager that uses the .NET Data Provider for SQL Server (SqlClient) to 
connect to the SQL Server database that contains the table or view to be profiled. 


TableOrView 
Select the existing table or view that contains the column to be profiled. 


For more information, see the section, "TableorView Options," in this topic. 


Column 


Select the existing column to be profiled. Select (*) to profile all columns. 


For more information, see the section, "Column Options," in this topic. 


TableOrView Options 
Schema 
Specifies the schema to which the selected table belongs. This option is read-only. 


Table 
Displays the name of the selected table. This option is read-only. 


Column Options 

IsWildCard 

Specifies whether the (*) wildcard has been selected. This option is set to True if you have selected (*) to profile 
all columns. It is False if you have selected an individual column to be profiled. This option is read-only. 


ColumnName 
Displays the name of the selected column. This option is blank if you have selected (*) to profile all columns. 
This option is read-only. 


StringCompareOptions 
Select options for comparing string values. This property has the options listed in the following table. The 
default value of this option is Default. 


NOTE 


If the (*) wildcard is used for ColumnName, CompareOptions is read-only and is set to the Default setting. 





VALUE DESCRIPTION 


Default Sorts and compares data based on the column's collation in 
the source table. 


BinarySort Sorts and compares data based on the bit patterns defined 
for each character. Binary sort order is case sensitive and 
accent sensitive. Binary is also the fastest sorting order. 


DictionarySort Sorts and compares data based on the sorting and 
comparison rules as defined in dictionaries for the associated 
language or alphabet. 


If you select DictionarySort, you can also select any combination of the options listed in the following table. By 
default, none of these additional options are selected. 


VALUE DESCRIPTION 


IgnoreCase Specifies whether the comparison distinguishes between 
uppercase and lowercase letters. If this option is set, the 
string comparison ignores case. For example, "ABC" becomes 
the same as "abc". 


IgnoreNonSpace Specifies whether the comparison distinguishes between 
spacing characters and diacritics. If this option is set, the 
comparison ignores diacritics. For example, "A¥" is equal to 


a. 


IgnoreKanaType Specifies whether the comparison distinguishes between the 
two types of Japanese kana characters: hiragana and 
katakanaa. If this option is set, the string comparison ignores 
kana type. 


VALUE DESCRIPTION 


IgnoreWidth Specifies whether the comparison distinguishes between a 
single-byte character and the same character when it is 
represented as a double-byte character. If this option is set, 
the string comparison treats single-byte and double-byte 
representations of the same character as identical. 


General Options 


RequestID 
Type a descriptive name to identify this profile request. Typically, you do not have to change the autogenerated 
value. 


Options 
ValueDistributionOption 


Specify whether to compute the distribution for all column values. The default value of this option is 
FrequentValues. 


VALUE DESCRIPTION 
AllValues The distribution is computed for all column values. 
FrequentValues The distribution is computed only for values whose 


frequency exceeds the minimum value specified in 
FrequentValueThreshold. Values that do not meet the 
FrequentValueThreshold are excluded from the output 
report. 


FrequentValueThreshold 

Specify the threshold (by using a value between 0 and 1) above which the column value should be reported. 
This option is disabled when you select AllValues as the ValueDistributionOption. The default value of this 
option is 0.001. 


See Also 


Data Profiling Task Editor (General Page) 
Single Table Quick Profile Form (Data Profiling Task) 


Functional Dependency Profile Request Options 


(DEI naroilinemes4 
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Applies to: Q sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Use the Request Properties pane of the Profile Requests page to set the options for the Functional 
Dependency Profile Request selected in the requests pane. A Functional Dependency profile reports the 
extent to which the values in one column (the dependent column) depend on the values in another column or 
set of columns (the determinant column). This profile can also help you identify problems in your data such as 
invalid values. For example, you profile the dependency between a Zip Code/Postal Code column and a United 
States state column. In this profile, the same Zip Code should always have the same state, but the profile 
discovers violations of the dependency. 


NOTE 


The options described in this topic appear on the Profile Requests page of the Data Profiling Task Editor. For more 


information about this page of the editor, see Data Profiling Task Editor (Profile Requests Page). 





For more information about how to use the Data Profiling Task, see Setup of the Data Profiling Task. For more 
information about how to use the Data Profile Viewer to analyze the output of the Data Profiling Task, see Data 
Profile Viewer. 


Understanding the Selection of Determinant and Dependent Columns 


A Functional Dependency Profile Request computes the degree to which the determinant side column or 
set of columns (specified in the DeterminantColumns property) determines the value of the dependent side 
column (specified in the DependentColumn property). For example, a United States state column should be 
functionally dependent on a United States Zip Code column. That is, if the Zip Code (determinant column) is 
98052, the state (dependent column) should always be Washington. 


For the determinant side, you can specify a column or a set of columns in the DeterminantColumns property. 
For example, consider a sample table that contains columns A, B, and C. You make the following selections for 
the DeterminantColumns property: 


e When you select the (*) wildcard, the Data Profiling task tests each column as the determinant side of the 
dependency. 


e@ When you select the (*) wildcard and another column or columns, the Data Profiling task tests each 
combination of columns as the determinant side of the dependency. For example, consider a sample table 
that contains columns A, B, and C. If you specify (*) and column C as the value of the 
DeterminantColumns property, the Data Profiling task tests the combinations (A, C) and (B, C) as the 
determinant side of the dependency. 


For the dependent side, you can specify a single column or the (*) wildcard in the DependentColumn 
property. When you select (*), the Data Profiling task tests the determinant side column or set of columns 
against each column. 





NOTE 

If you select (*), this option might result in a large number of computations and decrease the performance of the task. 
However, if the task finds a subset that satisfies the threshold for a functional dependency, the task does not analyze 
additional combinations. For example, in the sample table described above, if the task determines that column C is a 


determinant column, the task does not continue to analyze the composite candidates. 











Request Properties Options 


For a Functional Dependency Profile Request, the Request Properties pane displays the following groups 
of options: 


e Data, which includes the DeterminantColumns and DependentColumn options 
e General 
e Options 


Data Options 
ConnectionManager 


Select the existing ADO.NET connection manager that uses the .NET Data Provider for SQL Server (SqlClient) to 
connect to the SQL Server database that contains the table or view to be profiled. 


TableOrView 
Select the existing table or view to be profiled. 


DeterminantColumns 
Select the determinant column or set of columns. That is, select the column or set of columns whose values 


determine the value of the dependent column. 


For more information, see the sections, "Understanding the Selection of Determinant and Dependent Columns" 


and "DeterminantColumns and DependentColumn Options," in this topic. 


DependentColumn 
Select the dependent column. That is, select the column whose value is determined by the value of the 


determinant side column or set of columns. 


For more information, see the sections, "Understanding the Selection of Determinant and Dependent Columns" 
and "DeterminantColumns and DependentColumn Options," in this topic. 


DeterminantColumns and DependentColumn Options 
The following options are presented for each column selected for profiling in DeterminantColumns and in 
DependentColumn. 


For more information, see the section, "Understanding the Selection of Determinant and Dependent Columns," 


earlier in this topic. 


IsWildCard 
Specifies whether the (*) wildcard has been selected. This option is set to True if you have selected (*) to profile 
all columns. It is False if you have selected an individual column to be profiled. This option is read-only. 


ColumnName 
Displays the name of the selected column. This option is blank if you have selected (*) to profile all columns. 
This option is read-only. 


StringCompareOptions 
Select options for comparing string values. This property has the options listed in the following table. The 
default value of this option is Default. 





NOTE 


When you use the (*) wildcard for ColumnName, CompareOptions is read-only and is set to the Default setting. 





VALUE DESCRIPTION 


Default Sorts and compares data based on the column's collation in 
the source table. 


BinarySort Sorts and compares data based on the bit patterns defined 
for each character. Binary sort order is case sensitive and 
accent sensitive. Binary is also the fastest sorting order. 


DictionarySort Sorts and compares data based on the sorting and 
comparison rules as defined in dictionaries for the associated 
language or alphabet. 


If you select DictionarySort, you can also select any combination of the options listed in the following table. By 
default, none of these additional options are selected. 


VALUE DESCRIPTION 


IgnoreCase Specifies whether the comparison distinguishes between 
uppercase and lowercase letters. If this option is set, the 
string comparison ignores case. For example, "ABC" becomes 
the same as "abc". 


IgnoreNonSpace Specifies whether the comparison distinguishes between 
spacing characters and diacritics. If this option is set, the 
comparison ignores diacritics. For example, "A¥" is equal to 


a. 


IgnoreKanalype Specifies whether the comparison distinguishes between the 
two types of Japanese kana characters: hiragana and 
katakanaa. If this option is set, the string comparison ignores 
kana type. 


IgnoreWidth Specifies whether the comparison distinguishes between a 
single-byte character and the same character when it is 
represented as a double-byte character. If this option is set, 
the string comparison treats single-byte and double-byte 
representations of the same character as identical. 


General Options 


RequestID 
Type a descriptive name to identify this profile request. Typically, you do not have to change the autogenerated 
value. 


Options 
ThresholdSetting 
Specify the threshold setting. The default value of this property is Specified. 


VALUE DESCRIPTION 


None Does not specify a threshold. The functional dependency 
strength is reported regardless of its value. 


Specified Use the threshold that is specified in 
FDStrengthThreshold. The functional dependency 
strength is reported only if it is greater than the threshold. 


Exact Does not specify a threshold. The functional dependency 
strength is reported only if the functional dependency 
between the selected columns is exact. 


FDStrengthThreshold 

Specify the threshold (by using a value between 0 and 1) above which the functional dependency strength 
should be reported. The default value of this property is 0.95. This option is enabled only when Specified is 
selected as the ThresholdSetting. 


MaxNumberOfViolations 
Specify the maximum number of functional dependency violations to report in the output. The default value of 
this property is 100. This option is disabled when Exact is selected as the ThresholdSetting. 


See Also 


Data Profiling Task Editor (General Page) 
Single Table Quick Profile Form (Data Profiling Task) 


Value Inclusion Profile Request Options (Data 


Profiling Task) 


11/23/2021 + 7 minutes to read * Edit Online 





Applies to: Q sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Use the Request Properties pane of the Profile Requests page to set the options for the Value Inclusion 
Profile Request selected in the requests pane. A Value Inclusion profile computes the overlap in the values 
between two columns or sets of columns. Thus, it can also determine whether a column or set of columns is 
appropriate to serve as a foreign key between the selected tables. This profile can also help you identify 
problems in your data such as invalid values. For example, you use a value inclusion profile to profile the 
ProductID column of a Sales table. The profile discovers that the column contains values that are not found in 
the ProductID column of the Products table. 


NOTE 


The options described in this topic appear on the Profile Requests page of the Data Profiling Task Editor. For more 


information about this page of the editor, see Data Profiling Task Editor (Profile Requests Page). 





For more information about how to use the Data Profiling Task, see Setup of the Data Profiling Task. For more 
information about how to use the Data Profile Viewer to analyze the output of the Data Profiling Task, see Data 
Profile Viewer. 


Understanding the Selection of Columns for the InclusionColumns 
Property 


A Value Inclusion Profile Request computes whether all the values in a subset are present in the superset. 
The superset is often a lookup or reference table. For example, the state column in a table of addresses is the 
subset table. Every two-character state code in this column should also be found in the table of United States 
Postal Service state codes, which is the superset table. 


When you use the (*) wildcard as the value of the subset column or the superset column, the Data Profiling task 


compares each column on that side against the column specified on the other side. 





NOTE 


If you select (*), this option might result in a large number of computations and decrease the performance of the task. 





Understanding the Threshold Settings 


You can use two different threshold settings to refine the output of a Value Inclusion Profile Request. 


When you specify a value other than None for InclusionThresholdSetting, the profile reports the inclusion 
strength of the subset in the superset only under one of the following conditions: 


e When the inclusion strength exceeds the threshold specified in InclusionStrengthThreshold. 
e@ When the inclusion strength has a value of 1.0 and the InclusionStrengthThreshold is set to Exact. 


You can refine the output more by filtering out combinations where the superset column is not an appropriate 


key for the superset table because of non-unique values. When you specify a value other than None for 
SupersetColumnsKeyThresholdSetting, the profile reports the inclusion strength of the subset in the 


superset only under one of the following conditions: 


e When the suitability of the superset columns as a key in the superset table exceeds the threshold 
specified in SupersetColumnsKeyThreshold 


e When the inclusion strength has a value or 1.0 and the SupersetColumnsKeyThreshold is set to Exact. 


Request Properties Options 


For a Value Inclusion Profile Request, the Request Properties pane displays the following groups of 

options: 

e Data, which includes the SubsetTableOrView, SupersetTableOrView, and InclusionColumns 
options 

e General 


e Options 


Data Options 


ConnectionManager 
Select the existing ADO.NET connection manager that uses the .NET Data Provider for SQL Server (SqlClient) to 
connect to the SQL Server database that contains the table or view to be profiled. 


SubsetTableOrView 
Select the existing table or view to be profiled. 


For more information, see the section, "SubsetTableOrView and SupersetTableOrView Options," in this topic. 


SupersetlableOrView 
Select the existing table or view to be profiled. 


For more information, see the section, "SubsetTableOrView and SupersetTableOrView Options,” in this topic. 


InclusionColumns 
Select the columns or sets of columns from the subset and superset tables. 


For more information, see the sections, "Understanding the Selection of Columns for the InclusionColumns 


Property” and "InclusionColumns Options," in this topic. 


SubsetTableOrView and SupersetTableOrView Options 
Schema 
Specifies the schema to which the selected table belongs. This option is read-only. 


TableOrView 
Displays the name of the selected table. This option is read-only. 


InclusionColumns Options 


The following options are presented for each set of columns selected for profiling in InclusionColumns. 


For more information, see the section, "Understanding the Selection of Columns for the InclusionColumns 


Property," earlier in this topic. 


IsWildcard 
Specifies whether the (*) wildcard has been selected. This option is set to True if you have selected (*) to profile 


all columns. It is False if you have selected an individual column to be profiled. This option is read-only. 


ColumnName 


Displays the name of the selected column. This option is blank if you have selected (*) to profile all columns. 
This option is read-only. 


StringCompareOptions 
Select options for comparing string values. This property has the options listed in the following table. The 


default value of this option is Default. 





NOTE 


When you use the (*) wildcard for ColumnName, CompareOptions is read-only and is set to the Default setting. 





VALUE DESCRIPTION 


Default Sorts and compares data based on the column's collation in 
the source table. 


BinarySort Sorts and compares data based on the bit patterns defined 
for each character. Binary sort order is case sensitive and 
accent sensitive. Binary is also the fastest sorting order. 


DictionarySort Sorts and compares data based on the sorting and 
comparison rules as defined in dictionaries for the associated 
language or alphabet. 


If you select DictionarySort, you can also select any combination of the options listed in the following table. By 
default, none of these additional options are selected. 


VALUE DESCRIPTION 


IgnoreCase Specifies whether the comparison distinguishes between 
uppercase and lowercase letters. If this option is set, the 
string comparison ignores case. For example, "ABC" becomes 
the same as "abc". 


IgnoreNonSpace Specifies whether the comparison distinguishes between 
spacing characters and diacritics. If this option is set, the 
comparison ignores diacritics. For example, "A¥" is equal to 


a 


IgnoreKanaType Specifies whether the comparison distinguishes between the 
two types of Japanese kana characters: hiragana and 
katakanaa. If this option is set, the string comparison ignores 
kana type. 


IgnoreWidth Specifies whether the comparison distinguishes between a 
single-byte character and the same character when it is 
represented as a double-byte character. If this option is set, 
the string comparison treats single-byte and double-byte 
representations of the same character as identical. 


General Options 


RequestID 
Type a descriptive name to identify this profile request. Typically, you do not have to change the autogenerated 
value. 


Options 


InclusionThresholdSetting 
Select the threshold setting to refine the output of the profile. The default value of this property is Specified. 
For more information, see the section, "Understanding the Threshold Settings," earlier in this topic. 


VALUE DESCRIPTION 


None Does not specify a threshold. The key strength is reported 
regardless of its value. 


Specified Use the threshold that is specified in 
InclusionStrengthThreshold. The inclusion strength is 
reported only if it is greater than the threshold. 


Exact Does not specify a threshold. The inclusion strength is 
reported only if the subset values are completedly included 
in the upserset values. 


InclusionStrengthThreshold 

Specify the threshold (by using a value between 0 and 1) above which the inclusion strength should be 
reported. The default value of this property is 0.95. This option is enabled only when Specified is selected as 
the InclusionThresholdSetting. 


For more information, see the section, "Understanding the Threshold Settings," earlier in this topic. 


SupersetColumnsKeyThresholdSetting 
Specify the superset threshold. The default value of this property is Specified. For more information, see the 
section, "Understanding the Threshold Settings," earlier in this topic. 


VALUE DESCRIPTION 

None Does not specify a threshold. The inclusion strength is 
reported regardless of the key strength of the superset 
column. 

Specified Use the threshold that is specified in 


SupersetColumnsKeyThreshold. The inclusion strength is 
reported only if the key strength of the superset column is 
greater than the threshold. 


Exact Does not specify a threshold. The inclusion strength is 
reported only if the supserset columns are an exact key in 
the superset table. 


SupersetColumnsKeyThreshold 

Specify the threshold (by using a value between 0 and 1) above which the inclusion strength should be 
reported. The default value of this property is 0.95. This option is enabled only when Specified is selected as 
the SupersetColumnsKeyThresholdSetting. 


For more information, see the section, "Understanding the Threshold Settings," earlier in this topic. 


MaxNumberOfViolations 
Specify the maximum number of inclusion violations to report in the output. The default value of this property is 
100. This option is disabled when Exact is selected as the InclusionThresholdSetting. 


See Also 


Data Profiling Task Editor (General Page) 


Single Table Quick Profile Form (Data Profiling Task) 


Data Profiling Task Editor (General Page) 


11/23/2021 * 2 minutes to read « Edit Online 





Applies to: Q@ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 
Use the General page of the Data Profiling Task Editor to configure the following options: 

e Specify the destination for the profile output. 

e Use the default settings to simplify the task of profiling a single table or view. 


For more information about how to use the Data Profiling task, see Setup of the Data Profiling Task. For more 
information about how to use the Data Profile Viewer to analyze the output of the Data Profiling task, see Data 
Profile Viewer. 


To open the General page of the Data Profiling Task Editor 
1. In SQL Server Data Tools (SSDT), open the Integration Services package that has the Data Profiling task. 
2. On the Control Flow tab, double-click the Data Profiling task. 


3. In the Data Profiling Task Editor, click General. 


Data Profiling Options 


Timeout 
Specify the number of seconds after which the Data Profiling task should timeout and stop running. The default 
value is 0, which indicates no timeout. 


Destination Options 





IMPORTANT 


The output file might contain sensitive data about your database and the data that database contains. For suggestions 
about how to make this file more secure, see Access to Files Used by Packages. 











DestinationType 
Specify whether to save the data profile output to a file or a variable: 


VALUE DESCRIPTION 


FileConnection Save the profile output to a file in the location that is 
specified in a File connection manager. 


Note: You specify which File connection manager to use in 
the Destination option. 


Variable Save the profile output to a package variable. 


Note: You specify which package variable to use in the 
Destination option. 


Destination 


Specify which File connection manager or package variable contains the data profile output: 


e If the DestinationType option is set to FileConnection, the Destination option displays the available 
File connection managers. Select one of these connection managers, or select <New File connection> to 
create a new File connection manager. 


e If the DestinationType option is set to Variable, the Destination option displays the available package 
variables in the Destination list. Select one of these variables, or select <New Variable> to create a new 
variable. 


OverwriteDestination 

Specify whether to overwrite the output file if it already exists. The default value is False. The value of this 
property is used only when the DestinationType option is set to FileConnection. When the DestinationType 
option is set to Variable, the task always overwrites the previous value of the variable. 


IMPORTANT 


If you try to run the Data Profiling task more than once without changing the output file name or changing the value of 
the OverwriteDestination property to True, the task fails with the message that the output file already exists. 











Other Options 


Quick Profile 
Display the Single Table Quick Profile Form. This form simplifies the task of profiling a single table or view 
by using default settings. For more information, see Single Table Quick Profile Form (Data Profiling Task). 


Open Profile Viewer 

Opens the Data Profile Viewer. The stand-alone Data Profile Viewer displays data profile output from the Data 
Profiling task. You can view the data profile output after you have run the Data Profiling task inside the 
Integration Services package and computed the data profiles. 





NOTE 


You can also open the Data Profile Viewer by running the DataProfileViewer.exe in the folder, <drive>:\Program Files (x86) 
| Program Files\Microsoft SQL Server\110\DTS\Binn. 











See Also 


Single Table Quick Profile Form (Data Profiling Task) 
Data Profiling Task Editor (Profile Requests Page) 


Incorporate a Data Profiling Task in Package 


Workflow 


11/23/2021 + 12 minutes to read « Edit Online 





Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Data profiling and cleanup are not candidates for an automated process in their early stages. In SQL Server 
Integration Services, the output of the Data Profiling task usually requires visual analysis and human judgment 
to determine whether reported violations are meaningful or excessive. Even after recognizing data quality 
problems, there still has to be a carefully thought-out plan that addresses the best approach for cleanup. 


However, after criteria for data quality have been established, you might want to automate a periodic analysis 
and cleanup of the data source. Consider these scenarios: 


e Checking data quality before an incremental load. Use the Data Profiling task to compute the 
Column Null Ratio Profile of new data intended for the CustomerName column in a Customers table. If 
the percentage of null values is greater than 20%, send an e-mail message that contains the profile 
output to the operator and end the package. Otherwise, continue the incremental load. 


e Automating cleanup when the specified conditions are met. Use the Data Profiling task to 
compute the Value Inclusion Profile of the State column against a lookup table of states, and of the ZIP 
Code/Postal Code column against a lookup table of zip codes. If the inclusion strength of the state values 
is less than 80%, but the inclusion strength of the ZIP Code/Postal Code values is greater than 99%, this 
indicates two things. First, the state data is bad. Second, the ZIP Code/Postal Code data is good. Launch a 
Data Flow task that cleans up the state data by performing a lookup of the correct state value from the 
current Zip Code/Postal Code value. 


After you have a workflow into which you can incorporate the Data Flow task, you have to understand the steps 
that are required to add this task. The next section describes the general process of incorporating the Data Flow 
task. The final two sections describe how to connect the Data Flow task either directly to a data source or to 
transformed data from the Data Flow. 


Defining a General Workflow for the Data Flow Task 


The following procedure outlines the general approach for using the output of the Data Profiling task in the 
workflow of a package. 


To use the output of the Data Profiling task programmatically in a package 


1. Add and configure the Data Profiling task in a package. 
2. Configure package variables to hold the values that you want to retrieve from the profile results. 


3. Add and configure a Script task. Connect the Script task to the Data Profiling task. In the Script task, write 
code that reads the desired values from the output file of the Data Profiling task and populates the 
package variables. 


4. In the precedence constraints that connect the Script task to downstream branches in the workflow, write 
expressions that use the values of the variables to direct the workflow. 


When incorporating the Data Profiling task into the workflow of a package, keep these two features of the task 
in mind: 


e Task output. The Data Profiling task writes its output to a file or a package variable in XML format 


according to the DataProfile.xsd schema. Therefore, you have to query the XML output if you want to use 
the profile results in the conditional workflow of a package. You can easily use the Xpath query language 
to query this XML output. To study the structure of this XML output, you can open a sample output file or 
the schema itself. To open the output file or schema, you can use Microsoft Visual Studio, another XML 
editor, or a text editor, such as Notepad. 


NOTE 


Some of the profile results that are displayed in the Data Profile Viewer are calculated values that are not directly 
found in the output. For example, the output of the Column Null Ratio Profile contains the total number of rows 
and the number of rows that contain null values. You have to query these two values, and then calculate the 


percentage of rows that contain null values, to obtain the column null ratio. 








e Task input. The Data Profiling task reads its input from SQL Server tables. Therefore, you have to save 
data that is in memory to staging tables if you want to profile data that has already been loaded and 
transformed in the data flow. 


The following sections apply this general workflow to profiling data that comes directly from an external data 
source or that comes transformed from the Data Flow task. These sections also show how to handle the input 
and output requirements of the Data Flow task. 


Connecting the Data Profiling Task Directly to an External Data Source 


The Data Profiling task can profile data that comes directly from a data source. To illustrate this capability, the 
following example uses the Data Profiling task to compute a Column Null Ratio Profile on the columns of the 
Person.Address table in the AdventureWorks2012 database. Then, this example uses a Script task to retrieve the 
results from the output file and populate package variables that can be used to direct workflow. 





NOTE 


The AddressLine2 column was selected for this simple example because this column contains a high percentage of null 
values. 








This example consists of the following steps: 


@ Configuring the connection managers that connect to the external data source and to the output file that 
will contain the profile results. 


e Configuring the package variables that will hold the values needed by the Data Profiling task. 
e Configuring the Data Profiling task to compute the Column Null Ratio Profile. 
e Configuring the Script task to work the XML output from the Data Profiling task. 


e Configuring the precedence constraints that will control which downstream branches in the workflow are 
run based on the results of the Data Profiling task. 


Configure the Connection Managers 


For this example, there are two connection managers: 
e An ADO.NET connection manager that connects to the AdventureWorks2012 database. 


e A File connection manager that creates the output file that will hold the results of the Data Profiling task. 


To configure the connection managers 


1. In SQL Server Data Tools (SSDT), create a new Integration Services package. 





2. Add an ADO.NET connection manager to the package. Configure this connection manager to use the NET 
Data Provider for SQL Server (SqlClient) and to connect to an available instance of the 
AdventureWorks2012 database. 


By default, the connection manager has the following name: <server name>.AdventureWorks1. 


3. Add a File connection manager to the package. Configure this connection manager to create the output 
file for the Data Profiling task. 


This example uses the file name, DataProfile1.xml. By default, the connection manager has the same 
name as the file. 


Configure the Package Variables 


This example uses two package variables: 
e The ProfileConnectionName variable passes the name of the File connection manager to the Script task. 


e The AddressLine2NullRatio variable passes the calculated null ratio for this column out of the Script task 
to the package. 


To configure the package variables that will hold profile results 


e Inthe Variables window, add and configure the following two package variables: 


o Enter the name, ProfileConnectionName, for one of the variables and set the type of this 
variable to String. 


o Enter the name, AddressLine2NullRatio, for the other variable and set the type of this variable 
to Double. 


Configure the Data Profiling Task 


The Data Profiling task has to be configured in the following way: 
e To use the data that the ADO.NET connection manager supplies as input. 
e To perform a Column Null Ratio profile on the input data. 


e Tosave the profile results to the file that is associated with the File connection manager. 


To configure the Data Profiling task 


1. To the Control Flow, add a Data Profiling task. 
2. Open the Data Profiling Task Editor to configure the task. 


3. On the General page of the editor, for Destination, select the name of the File connection manager that 
you have previously configured. 


4. On the Profile Requests page of the editor, create a new Column Null Ratio Profile. 


5. In the Request properties pane, for ConnectionManager, select the ADO.NET connection manager 
that you have previously configured. Then, for TableOrView, select Person.Address. 


6. Close the Data Profiling Task Editor. 


Configure the Script Task 


The Script task has to be configured to retrieve the results from the output file and populate the package 


variables that were previously configured. 


To configure the Script task 


1. To the Control Flow, add a Script task. 


2. Connect the Script task to the Data Profiling task. 


. Open the Script Task Editor to configure the task. 


. On the Script page, select your preferred programming language. Then, make the two package variables 
available to the script: 


a. For ReadOnlyVariables, select ProfileConnectionName. 
b. For ReadWriteVariables, select AddressLine2NullRatio. 
. Select Edit Script to open the script development environment. 
. Add a reference to the System.Xml namespace. 


. Enter the sample code that corresponds to your programming language: 


Imports System 
Imports Microsoft.SqlServer.Dts.Runtime 
Imports System. Xml 


Public Class ScriptMain 


Private FILENAME As String = "C:\ TEMP\DataProfile1. xml" 
Private PROFILE_NAMESPACE_URI As String = "https://schemas.microsoft.com/DataDebugger/" 
Private NULLCOUNT_XPATH As String = _ 
"/default:DataProfile/default :DataProfileOutput/default:Profiles" & _ 
"/default :ColumnNullRatioProfile[ default :Column[@Name='AddressLine2' ]]/default:NullCount/text()" 
Private TABLE_XPATH As String = _ 
"/default:DataProfile/default :DataProfileOutput/default:Profiles" & _ 
"/default:ColumnNullRatioProfile[ default :Column[@Name='AddressLine2' ]]/default: Table" 


Public Sub Main() 


Dim profileConnectionName As String 
Dim profilePath As String 

Dim profileOutput As New XmlDocument 
Dim profileNSM As XmlNamespaceManager 
Dim nullCountNode As XmlNode 

Dim nullCount As Integer 

Dim tableNode As Xm1Node 

Dim rowCount As Integer 

Dim nullRatio As Double 


" Open output file. 

profileConnectionName = Dts.Variables("ProfileConnectionName") .Value.ToString() 
profilePath = Dts.Connections(profileConnectionName) .ConnectionString 
profileOutput.Load(profilePath) 

profileNSM = New XmlNamespaceManager (profileOutput.NameTable) 
profileNSM.AddNamespace("default", PROFILE_NAMESPACE_URT) 

" Get null count for column. 

nullCountNode = profileOutput.SelectSingleNode(NULLCOUNT_XPATH, profileNsM) 
nullCount = CType(nullCountNode.Value, Integer) 

" Get row count for table. 

tableNode = profileOutput.SelectSingleNode(TABLE_XPATH, profileNSM) 
rowCount = CType(tableNode.Attributes("RowCount").Value, Integer) 

" Compute and return null ratio. 

nullRatio = nullCount / rowCount 
Dts.Variables("AddressLine2NullRatio").Value = nullRatio 


Dts.TaskResult = Dts.Results.Success 
End Sub 


End Class 


«| | 


using System; 
using Microsoft.SqlServer.Dts.Runtime; 
using System. Xml; 


public class ScriptMain 


{ 


private string FILENAME = "C:\\ TEMP\\DataProfile1.xm1"; 

private string PROFILE_NAMESPACE_URI = "https://schemas.microsoft.com/DataDebugger/"; 

private string NULLCOUNT_XPATH = "/default:DataProfile/default :DataProfileOutput/default:Profiles" 
+ "/default:ColumnNullRatioProfile[ default :Column[@Name='AddressLine2' ]]/default:NullCount/text()"; 

private string TABLE_XPATH = "/default:DataProfile/default:DataProfileOutput/default:Profiles" + 
"/default:ColumnNullRatioProfile[ default :Column[@Name='AddressLine2' ]]/default: Table"; 


public void Main() 
{ 


string profileConnectionName; 

string profilePath; 

Xm1Document profileOutput = new Xm1Document(); 
Xm1NamespaceManager profileNSM; 

Xm1Node nullCountNode; 

int nullCount; 

Xm1Node tableNode; 

int rowCount; 

double nullRatio; 


// Open output file. 

profileConnectionName = Dts.Variables["ProfileConnectionName"].Value.ToString(); 
profilePath = Dts.Connections[profileConnectionName].ConnectionString; 
profileOutput.Load(profilePath) ; 

profileNSM = new XmlNamespaceManager (profileOutput.NameTable) ; 
profileNSM.AddNamespace("default", PROFILE_NAMESPACE_URT) ; 


// Get null count for column. 
nullCountNode = profileOutput.SelectSingleNode(NULLCOUNT_XPATH, profileNsM) ; 
nullcount = (int)nullCountNode. Value; 


// Get row count for table. 
tableNode = profileOutput.SelectSingleNode(TABLE_XPATH, profileNSsM) ; 
rowCount = (int)tableNode.Attributes["RowCount"].Value; 


// Compute and return null ratio. 
nullRatio = nullCount / rowCount; 


Dts.Variables["AddressLine2NullRatio"].Value = nullRatio; 


Dts.TaskResult = Dts.Results.Success; 





NOTE 
The sample code shown in this procedure demonstrates how to load the output of the Data Profiling task from a 
file. To load the output of the Data Profiling task from a package variable instead, see the alternative sample code 


that follows this procedure. 








8. Close the script development environment, and then close the Script Task Editor. 


Alternative Code-Reading the Profile Output from a Variable 
The previous procedure shows how to load the output of the Data Profiling task from a file. However, an 
alternative method would be to load this output from a package variable. To load the output from a variable, you 


have to make the following changes to the sample code: 
e@ Call the LoadXml method of the XmIDocument class instead of the Load method. 


e Inthe Script Task Editor, add the name of the package variable that contains the profile output to the 
task's ReadOnlyVariables list. 


e Pass the string value of the variable to the LoadXML method, as shown in the following code example. 
(This example uses "ProfileOutput" as the name of the package variable that contains the profile output.) 


Dim outputString As String 
outputString = Dts.Variables("ProfileOutput").Value.ToString() 


profileOutput .LoadXml(outputString) 


string outputString; 
outputString = Dts.Variables["ProfileOutput"].Value.ToString(); 


profileOutput.LoadXml(outputString) ; 


Configure the Precedence Constraints 


The precedence constraints have to be configured to control which downstream branches in the workflow are 
run based on the results of the Data Profiling task. 


To configure the precedence constraints 
e In the precedence constraints that connect the Script task to downstream branches in the workflow, write 
expressions that use the values of the variables to direct the workflow. 


For example, you might set the Evaluation operation of the precedence constraint to Expression and 
Constraint. Then, you might use @AddressLine2NullRatio < .9@ as the value of the expression. This 
causes the workflow to follow the selected path when the previous tasks succeed, and when the 
percentage of null values in the selected column is less than 90%. 


Connecting the Data Profiling Task to Transformed Data from the Data 
Flow 


Instead of profiling data directly from a data source, you can profile data that has already been loaded and 
transformed in the data flow. However, the Data Profiling task works only against persisted data, not against in- 


memory data. Therefore, you must first use a destination component to save the transformed data to a staging 
table. 


NOTE 


When you configure the Data Profiling task, you have to select existing tables and columns. Therefore, you must create 
the staging table at design time before you can configure the task. In other words, this scenario does not allow you to 
use a temporary table that is created at run time. 








After saving the data to a staging table, you can do the following actions: 
e Use the Data Profiling task to profile the data. 
e Usea Script task to read the results as described earlier in this topic. 


e Use those results to direct the subsequent workflow of the package. 


The following procedure provides the general approach for using the Data Profiling task to profile data that has 


been transformed by the data flow. Many of these steps are similar to the ones described earlier for profiling 


data that comes directly from an external data source. You might want to review those earlier steps for more 


information about how to configure the various components. 


To use the Data Profiling task in the data flow 


1. 


In SQL Server Data Tools (SSDT), create a package. 


. In the Data Flow, add, configure, and connect the appropriate sources and transformations. 


In the Data Flow, add, configure, and connect a destination component that saves the transformed data to 


a staging table. 


In the Control Flow, add and configure a Data Profiling task that computes the desired profiles against the 
transformed data in the staging table. Connect the Data Profiling task to the Data Flow task. 


. Configure package variables to hold the values that you want to retrieve from the profile results. 


. Add and configure a Script task. Connect the Script task to the Data Profiling task. In the Script task, write 


code that reads the desired values from the output of the Data Profiling task and populates the package 


variables. 


. In the precedence constraints that connect the Script task to downstream branches in the workflow, write 


expressions that use the values of the variables to direct the workflow. 


See Also 


Setup of the Data Profiling Task 


Data Profile Viewer 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


The Execute Package task extends the enterprise capabilities of Integration Services by letting packages run 
other packages as part of a workflow. 


You can use the Execute Package task for the following purposes: 


e Breaking down complex package workflow. This task lets you break down workflow into multiple 
packages, which are easier to read, test, and maintain. For example, if you are loading data into a star 
schema, you can build a separate package to populate each dimension and the fact table. 


e Reusing parts of packages. Other packages can reuse parts of a package workflow. For example, you can 
build a data extraction module that can be called from different packages. Each package that calls the 
extraction module can perform different data scrubbing, filtering, or aggregation operations. 


e Grouping work units. Units of work can be encapsulated into separate packages and joined as 
transactional components to the workflow of a parent package. For example, the parent package runs the 
accessory packages, and based on the success or failure of the accessory packages, the parent package 
either commits or rolls back the transaction. 


e Controlling package security. Package authors require access to only a part of a multipackage solution. By 
separating a package into multiple packages, you can provide a greater level of security, because you can 
grant an author access to only the relevant packages. 


A package that runs other packages is generally referred to as the parent package, and the packages that a 
parent workflow runs are called child packages. 


Integration Services includes tasks that perform workflow operations, such as executing executables and batch 
files. For more information, see Execute Process Task. 


Running Packages 


The Execute Package task can run child packages that are contained in the same project that contains the parent 
package. You select a child package from the project by setting the ReferenceType property to Project 
Reference, and then setting the PackageNameFromProjectReference property. 





NOTE 


The ReferenceType option is ready-only and set to External Reference if the project that contains the package has not 
been converted to the project deployment model. Deploy Integration Services (SSIS) Projects and Packages. 








The Execute Package task can also run packages stored in the SQL Server msdb database and packages stored in 
the file system. The task uses an OLE DB connection manager to connect to SQL Server or a File connection 
manager to access the file system. For more information, see OLE DB Connection Manager and Flat File 
Connection Manager. 


The Execute Package task can also run a database maintenance plan, which lets you manage both SSIS packages 
and database maintenance plans in the same Integration Services solution. A database maintenance plan is 
similar to an SSIS package, but a plan can include only database maintenance tasks, and it is always stored in the 


msdb database. 


If you choose a package stored in the file system, you must provide the name and location of the package. The 
package can reside anywhere in the file system; it does not have to be in the same folder as the parent package. 


The child package can be run in the process of the parent package, or it can be run in its own process. Running 
the child package in its own process requires more memory, but it provides more flexibility. For example, if the 
child process fails, the parent process can continue to run. 


Alternatively, sometimes you want the parent and child packages to fail together as one unit, or you might not 
want to incur the additional overhead of another process. For example, if a child process fails and subsequent 
processing in the parent process of the package depends on success of the child process, the child package 
should run in the process of the parent package. 


By default, the ExecuteOutOfProcess property of the Execute Package task is set to False, and the child package 
runs in the same process as the parent package. If you set this property to True, the child package runs ina 
separate process. This may slow down the launching of the child package. In addition, if you set the property to 
True, you cannot debug the package in a tools-only install. You must install Integration Services. For more 


information, see Install Integration Services 


Extending Transactions 


The transaction that the parent package uses can extend to the child package; therefore, the work both packages 
perform can be committed or rolled back. For example, the database inserts that the parent package performs 
can be committed or rolled back, depending on the database inserts that the child package performs, and vice 


versa. For more information, see Inherited Transactions. 


Propagating Logging Details 


The child package that the Execute Package task runs may or may not be configured to use logging, but the child 
package will always forward the log details to the parent package. If the Execute Package task is configured to 
use logging, the task logs the log details from the child package. For more information, see Integration Services 
(SSIS) Logging. 


Passing Values to Child Packages 


Frequently a child package uses values passed to it by another package that calls it, ordinarily its parent package. 
Using values from a parent package is useful in scenarios such as the following: 


e Parts of a larger workflow are assigned to different packages. For example, one package downloads data 
on a nightly basis, summarizes the data, assigns summary data values to variables, and then passes the 
values to another package for additional processing of the data. 


e The parent package dynamically coordinates tasks in a child package. For example, the parent package 
determines the number of days in a current month and assigns the number to a variable, and the child 
package performs a task that number of times. 


e Achild package requires access to data that is dynamically derived by the parent package. For example, 
the parent package extracts data from a table and loads the rowset into a variable, and the child package 
performs additional operations on the data. 


You can use the following methods to pass values to a child package: 
e Package Configurations 


Integration Services provides a configuration type, the Parent Package Variable configuration, for passing 
values from parent to child packages. The configuration is built on the child package and uses a variable 


in the parent package. The configuration is mapped to a variable in the child package, or to the property 
of an object in the child package. The variable can also be used in the scripts used by the Script task or 
Script component. 


e Parameters 


You can configure the Execute Package Task to map parent package variables or parameters, or project 
parameters, to child package parameters. The project must use the project deployment model and the 
child package must be contained in the same project that contains the parent package. For more 
information, see Execute Package Task Editor. 





NOTE 


If the child package parameter is not sensitive and is mapped to a parent parameter that is sensitive, the child 


package will fail to run. 
The following mapping conditions are supported: 
Sensitive, child package parameter is mapped to a sensitive, parent parameter 


Sensitive, child package parameter is mapped to a non-sensitive, parent parameter 


Non-sensitive, child package parameter is mapped to a non-sensitive, parent parameter 








The parent package variable can be defined in the scope of the Execute Package task or in a parent container 
such as the package. If multiple variables with the same name are available, the variable defined in the scope of 
the Execute Package task is used, or the variable that is closest in scope to the task. 


For more information, see Use the Values of Variables and Parameters in a Child Package. 


Accessing Parent Package Variables 


Child packages can access parent package variables by using the Script task. When you enter the name of the 
parent package variable on the Script page in the Script Task Editor, don't include User: in the variable name. 
Otherwise, the child package doesn't locate the variable when you run the parent package. 


Configuring the Execute Package Task 


You can set properties through SSIS Designer or programmatically. 

For more information about the properties that you can set in SSIS Designer, click the following topic: 
e Expressions Page 

For more information about how to set these properties in SSIS Designer, click the following topic: 


e Set the Properties of a Task or Container 


Configuring the Execute Package Task Programmatically 
For more information about programmatically setting these properties, click the following topic: 


e N:Microsoft.SqlServer.Dts.Tasks.ExecutePackageTask 


Execute Package Task Editor 


Use the Execute Package Task Editor to configure the Execute Package Task. The Execute Package task extends the 
enterprise capabilities of Integration Services by letting packages run other packages as part of a workflow. 


What do you want to do? 


Open the Execute Package Task Editor 


Set the Options on the General Page 


Set the Options on the Package Page 


Set the Options on the Parameter Bindings Page 


Open the Execute Package Task Editor 


1. Open an Integration Services project in Visual Studio that contains an Execute Package task. 
2. Right-click the task in the SSIS Designer, and then click Edit. 


Set the Options on the General Page 


Name 
Provide a unique name for the Execute Package task. This name is used as the label in the task icon. 





NOTE 


Task names must be unique within a package. 





Description 
Type a description of the Execute Package task. 
Set the Options on the Package Page 


ReferenceType 
Select Project Reference for child packages that are in the project. Select External Reference for child 


packages that are located outside the package 


NOTE 


The ReferenceType option is ready-only and set to External Reference if the project that contains the package has not 


been converted to the project deployment model. Deploy Integration Services (SSIS) Projects and Packages. 





Password 
If the child package is password protected, provide the password for the child package, or click the ellipsis 
button (...) and create a new password for the child package. 


ExecuteOutOfProcess 

Specify whether the child package runs in the process of the parent package or in a separate process. By default, 
the ExecuteOutOfProcess property of the Execute Package task is set to False, and the child package runs in the 
same process as the parent package. If you set this property to true, the child package runs in a separate 
process. This may slow down the launching of the child package. In addition, if set the property to true, you 
cannot debug the package in a tools-only install; you must install the Integration Services product. For more 
information, see Install Integration Services. 

ReferenceType Dynamic Options 

ReferenceType = External Reference 

Location 

Select the location of the child package. This property has the options listed in the following table. 


VALUE DESCRIPTION 


SQL Server Set the location to an instance of SQL Server. 


VALUE DESCRIPTION 


File system Set the location to the file system. 


Connection 


Select the type of storage location for the child package. 


PackageNameReadOnly 
Displays the package name. 


ReferenceType = Project Reference 

PackageNameFromProjectReference 

Select a package contained in the project, to be the child package. 

Location Dynamic Options 

Location = SQL Server 

Connection 

Select an OLE DB connection manager in the list, or click <New connection...> to create a new connection 


manager. 
Related Topics: OLE DB Connection Manager 


PackageName 
Type the name of the child package, or click the ellipsis (...) and then locate the package. 


Location = File system 
Connection 
Select a File connection manager in the list, or click <New connection...> to create a new connection manager. 


Related Topics: File Connection Manager 


PackageNameReadOnly 
Displays the package name. 


Set the Options on the Parameter Bindings Page 


You can pass values from the parent package or the project, to the child package. The project must use the 
project deployment model and the child package must be contained in the same project that contains the parent 
package. 


For information about converting projects to the project deployment model, see Deploy Integration Services 
(SSIS) Projects and Packages. 


Child package parameter 
Enter or select a name for the child package parameter. 


Binding parameter or variable 
Select the parameter or variable that contains the value that you want to pass to the child package. 


Add 
Click to map a parameter or variable to a child package parameter. 


Remove 


Click to remove a mapping between a parameter or variable and a child package parameter. 


Execute Process Task 


11/23/2021 * 5 minutes to read « Edit Online 





Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


The Execute Process task runs an application or batch file as part of a SQL Server Integration Services package 
workflow. Although you can use the Execute Process task to open any standard application, such as Microsoft 
Excel or Microsoft Word, you typically use it to run business applications or batch files that work against a data 
source. For example, you can use the Execute Process task to expand a compressed text file. Then the package 
can use the text file as a data source for the data flow in the package. As another example, you can use the 
Execute Process task to run a custom Visual Basic application that generates a daily sales report. Then you can 
attach the report to a Send Mail task and forward the report to a distribution list. 


Integration Services includes other tasks that perform workflow operations such as executing packages. For 
more information, see Execute Package Task 


Custom Log Entries Available on the Execute Process Task 
The following table lists the custom log entries for the Execute Process task. For more information, see 
Integration Services (SSIS) Logging. 


LOG ENTRY DESCRIPTION 


ExecuteProcessExecutingProcess Provides information about the process that the task is 
configured to run. 


Two log entries are written. One contains information about 
the name and location of the executable that the task runs, 
and the other entry records the exit from the executable. 


ExecuteProcessVariableRouting Provides information about which variables are routed to the 
input and outputs of the executable. Log entries are written 
for stdin (the input), stdout (the output), and stderr (the 
error output). 


Configuration of the Execute Process Task 

You can set properties through SSIS Designer or programmatically. 

For more information about how to set these properties in SSIS Designer, click the following topic: 
e Set the Properties of a Task or Container 


Property Settings 
When the Execute Process task runs a custom application, the task provides input to the application through one 


or both of the following methods: 


e A variable that you specify in the StandardInputVariable property setting. For more information about 
variables, see Integration Services (SSIS) Variables and Use Variables in Packages. 


e An argument that you specify in the Arguments property setting. (For example, if the task opens a 
document in Word, the argument can name the .doc file.) 


To pass multiple arguments to a custom application in one Execute Process task, use spaces to delimit the 
arguments. An argument cannot include a space; otherwise, the task will not run. You can use an expression to 
pass a variable value as the argument. In the following example, the expression passes two variable values as 
arguments, and uses a space to delimit the arguments: 


@variable1 + " " + @variable2 
You can use an expression to set various Execute Process task properties. 


When you use the StandardInputVariable property to configure the Execute Process task to provide input, call 
the Console.ReadLine method from the application to read the input. For more information, see 
Console.ReadLine Methodthe topic, , in the Microsoft .NET Framework Class Library. 


When you use the Arguments property to configure the Execute Process task to provide input, do one of the 
following steps to obtain the arguments: 


e If you use Microsoft Visual Basic to write the application, set the My.Application.CommandLineArgs 
property. The following example sets the My.Application.CommandLineArgs property is to retrieve 
two arguments: 


Dim variable1 As String = My.Application.CommandLineArgs.Item(@) 
Dim variable2 As String = My.Application.CommandLineArgs.Item(1) 


For more information, see the topic, My.Application.CommandLineArgs Property, in the Visual Basic 
reference. 
e If you use Microsoft Visual C# to write the application, use the Main method. 


For more information, see the topic, Command-Line Arguments (C# Programming Guide), in the C# 
Programming Guide. 


The Execute Process task also includes the StandardOutputVariable and StandardErrorVariable properties 
for specifying the variables that consume the standard output and error output of the application, respectively. 


Additionally, you can configure the Execute Process task to specify a working directory, a time-out period, or a 
value to indicate that the executable ran successfully. The task can also be configured to fail if the return code of 
the executable does not match the value that indicates success, or if the executable is not found at the specified 
location. 


Programmatic Configuration of the Execute Process Task 
For more information about programmatically setting these properties, click the following topic: 


e ExecuteProcess 


Execute Process Task Editor (General Page) 


Use the General pageof the Execute Process Task Editor dialog box to name and describe the Execute 
Process task. 


Options 
Name 
Provide a unique name for the Execute Process task. This name is used as the label in the task icon. 





NOTE 


Task names must be unique within a package. 





Description 


Type a description of the Execute Process task. 


Execute Process Task Editor (Process Page) 


Use the Process page of the Execute Process Task Editor dialog box to configure the options that execute the 
process. These options include the executable to run, its location, command prompt arguments, and the 
variables that provide input and capture output. 


Options 
RequireFullFileName 
Indicate whether the task should fail if the executable is not found at the specified location. 


Executable 
Type the name of the executable to run. 


Arguments 


Provide command prompt arguments. 


WorkingDirectory 
Type the path of the folder that contains the executable, or click the browse button (...) and locate the folder. 


StandardInputVariable 
Select a variable to provide the input to the process, or click <New variable...> to create a new variable: 


Related Topics: Add Variable 


StandardOutputVariable 
Select a variable to capture the output of the process, or click <New variable...> to create a new variable. 


StandardErrorVariable 
Select a variable to capture the error output of the processor, or click <New variable...> to create a new 


variable. 


FailTasklfReturnCodelsNotSuccessValue 
Indicate whether the task fails if the process exit code is different from the value specified in SuccessValue. 


SuccessValue 
Specify the value returned by the executable to indicate success. By default this value is set to 0. 


TimeOut 
Specify the number of seconds that the process can run. A value of 0 indicates that no time-out value is used, 
and the process runs until it is completed or until an error occurs. 


TerminateProcessAfterTimeOut 
Indicate whether the process is forced to end after the time-out period specified by the TimeOut option. This 
option is available only if TimeOut is not 0. 


WindowStyle 
Specify the window style in which to run the process. 


See Also 


Integration Services Tasks 
Control Flow 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


The Execute SQL Server Agent Job task runs SQL Server Agent jobs. SQL Server Agent is a Microsoft Windows 
service that runs jobs that have been defined in an instance of SQL Server. You can create jobs that execute 
Transact-SQL statements and ActiveX scripts, perform Analysis Services and Replication maintenance tasks, or 
run packages. You can also configure a job to monitor Microsoft SQL Server and fire alerts. SQL Server Agent 
jobs are typically used to automate tasks that you perform repeatedly. For more information, see Implement 
Jobs. 


By using the Execute SQL Server Agent Job task, a package can perform administrative tasks related to SQL 
Server components. For example, a SQL Server Agent job can run a system stored procedure such as 
sp_enum_dtspackages to obtain a list of packages in a folder. 





NOTE 


SQL Server Agent must be running before local or multiserver administrative jobs can run automatically. 





This task encapsulates the sp_start_job system procedure and passes the name of the SQL Server Agent job to 
the procedure as an argument. For more information, see sp_start_job (Transact-SQL). 


Configuring the Execute SQL Server Agent Job Task 


You can set properties through SSIS Designer. This task is in the Maintenance Plan Tasks section of the 
Toolbox in SSIS Designer. 


For more information about the properties that you can set in SSIS Designer, click the following topic: 
e Execute SQL Server Agent Job Task (Maintenance Plan) 
For more information about how to set these properties in SSIS Designer, click the following topic: 


e Set the Properties of a Task or Container 


Execute SQL Task 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


The Execute SQL task runs SQL statements or stored procedures from a package. The task can contain either a 
single SQL statement or multiple SQL statements that run sequentially. You can use the Execute SQL task for the 
following purposes: 


@ Truncate a table or view in preparation for inserting data. 
e Create, alter, and drop database objects such as tables and views. 
e Re-create fact and dimension tables before loading data into them. 


e Run stored procedures. If the SQL statement invokes a stored procedure that returns results from a 
temporary table, use the WITH RESULT SETS option to define metadata for the result set. 


e Save the rowset returned from a query into a variable. 


The Execute SQL task can be used in combination with the Foreach Loop and For Loop containers to run 
multiple SQL statements. These containers implement repeating control flows in a package and they can run the 
Execute SQL task repeatedly. For example, using the Foreach Loop container, a package can enumerate files in a 
folder and run an Execute SQL task repeatedly to execute the SQL statement stored in each file. 


Connect to a data source 


The Execute SQL task can use different types of connection managers to connect to the data source where it 
runs the SQL statement or stored procedure. The task can use the connection types listed in the following table. 


CONNECTION TYPE CONNECTION MANAGER 

EXCEL Excel Connection Manager 

OLE DB OLE DB Connection Manager 

ODBC ODBC Connection Manager 

ADO ADO Connection Manager 

ADO.NET ADO.NET Connection Manager 

SQLMOBILE SQL Server Compact Edition Connection Manager 


Create SQL statements 


The source of the SQL statements used by this task can be a task property that contains a statement, a 
connection to a file that contains one or multiple statements, or the name of a variable that contains a statement. 
The SQL statements must be written in the dialect of the source database management system (DBMS). For 
more information, see Integration Services (SSIS) Queries. 


If the SQL statements are stored in a file, the task uses a File connection manager to connect to the file. For more 


information, see File Connection Manager. 


In SSIS Designer, you can use the Execute SQL Task Editor dialog box to type SQL statements, or use Query 
Builder, a graphical user interface for creating SQL queries. 





NOTE 
Valid SQL statements written outside the Execute SQL task may not be parsed successfully by the Execute SQL task. 


NOTE 


The Execute SQL Task uses the RecognizeAll ParseMode enumeration value. For more information, see 


ManagedBatchParser Namespace. 








Send multiple statements in a batch 


If you include multiple statements in an Execute SQL task, you can group them and run them as a batch. To 
signal the end of a batch, use the GO command. All the SQL statements between two GO commands are sent in 
a batch to the OLE DB provider to be run. The SQL command can include multiple batches separated by GO 


commands. 


There are restrictions on the kinds of SQL statements that you can group in a batch. For more information, see 
Batches of Statements. 


If the Execute SQL task runs a batch of SQL statements, the following rules apply to the batch: 
@ Only one statement can return a result set and it must be the first statement in the batch. 


e Ifthe result set uses result bindings, the queries must return the same number of columns. If the queries 
return a different number of columns, the task fails. However, even if the task fails, the queries that it runs, 
such as DELETE or INSERT queries, may succeed. 


e If the result bindings use column names, the query must return columns that have the same names as 
the result set names that are used in the task. If the columns are missing, the task fails. 


e If the task uses parameter binding, all the queries in the batch must have the same number and types of 


parameters. 


Run parameterized SQL commands 


SQL statements and stored procedures frequently use input parameters, output parameters, and return codes. 
The Execute SQL task supports the Input, Output, and ReturnValue parameter types. You use the Input type 
for input parameters, Output for output parameters, and ReturnValue for return codes. 


NOTE 


You can use parameters in an Execute SQL task only if the data provider supports them. 





Specify a result set type 


Depending on the type of SQL command, a result set may or may not be returned to the Execute SQL task. For 
example, a SELECT statement typically returns a result set, but an INSERT statement does not. The result set from 
a SELECT statement can contain zero rows, one row, or many rows. Stored procedures can also return an integer 
value, called a return code, that indicates the execution status of the procedure. In that case, the result set 


consists of a single row. 


Configure the Execute SQL task 

You can configure the Execute SQL task in the following ways: 

e Specify the type of connection manager to use to connect to a database. 
e Specify the type of result set that the SQL statement returns. 

e Specify a time-out for the SQL statements. 

e Specify the source of the SQL statement. 

e Indicate whether the task skips the prepare phase for the SQL statement. 


e If you use the ADO connection type, you must indicate whether the SQL statement is a stored procedure. 
For other connection types, this property is read-only and its value is always false. 


You can set properties programmatically or through SSIS Designer. 


General Page - Execute SQL Task Editor 


Use the General page of the Execute SQL Task Editor dialog box to configure the Execute SQL task and 
provide the SQL statement that the task runs. 


To learn more about the Transact-SQL query language, see Transact-SQL Reference (Database Engine). 


Static Options 


Name 
Provide a unique name for the Execute SQL task in the workflow. The name that is provided will be displayed 
within SSIS Designer. 


Description 
Describe the Execute SQL task. As a best practice, to make packages self-documenting and easier to maintain, 
describe the task in terms of its purpose. 


TimeOut 
Specify the maximum number of seconds the task will run before timing out. A value of 0 indicates an infinite 
time. The default is 0. 


NOTE 

Stored procedures do not time out if they emulate sleep functionality by providing time for connections to be made and 
transactions to complete that is greater than the number of seconds specified by TimeOut. However, stored procedures 
that execute queries are always subject to the time restriction specified by TimeOut. 











CodePage 
Specify the code page to use when translating Unicode values in variables. The default value is the code page of 
the local computer. 





NOTE 


When the Execute SQL task uses an ADO or ODBC connection manager, the CodePage property is not available. If your 
solution requires the use of a code page, use an OLE DB or an ADO.NET connection manager with the Execute SQL task. 











TypeConversionMode 


When you set this property to Allowed, the Execute SQL Task will attempt to convert output parameter and 
query results to the data type of the variable the results are assigned to. This applies to the Single row result 
set type. 


ResultSet 
Specify the result type expected by the SQL statement being run. Choose among Single row, Full result set, 
XML, or None. 


ConnectionType 
Choose the type of connection manager to use to connect to the data source. Available connection types include 
OLE DB, ODBC, ADO, ADO.NET and SQLMOBILE. 


Related Topics: OLE DB Connection Manager, ODBC Connection Manager, ADO Connection Manager, 
ADO.NET Connection Manager, SQL Server Compact Edition Connection Manager 


Connection 
Choose the connection from a list of defined connection managers. To create a new connection, select <New 


connection...>. 


SQLSourceType 
Select the source type of the SQL statement that the task runs. 


Depending on the connection manager type that Execute SQL task uses, you must use specific parameter 
markers in parameterized SQL statements. 


This property has the options listed in the following table. 
VALUE DESCRIPTION 


Direct input Set the source to a Transact-SQL statement. Selecting this 
value displays the dynamic option, SQLStatement. 


File connection Select a file that contains a Transact-SQL statement. Setting 
this option displays the dynamic option, FileConnection. 


Variable Set the source to a variable that defines the Transact-SQL 
statement. Selecting this value displays the dynamic option, 
SourceVariable. 


QuerylsStoredProcedure 
Indicates whether the specified SQL statement to be run is a stored procedure. This property is read/write only if 
the task uses the ADO connection manager. Otherwise the property is read-only and its value is false. 


BypassPrepare 
Indicate whether the SQL statement is prepared. true skips preparation; false prepares the SQL statement 
before running it. This option is available only with OLE DB connections that support preparation. 


Related Topics: Prepared Execution 


Browse 
Locate a file that contains a SQL statement by using the Open dialog box. Select a file to copy the contents of 
the file as a SQL statement into the SQLStatement property. 


Build Query 
Create an SQL statement using the Query Builder dialog box, a graphical tool used to create queries. This 
option is available when the SQLSourceType option is set to Direct input. 


Parse Query 


Validate the syntax of the SQL statement. 


SQLSourceType Dynamic Options 

SQLSourceType = Direct input 

SQLStatement 

Type the SQL statement to execute in the option box, or click the browse button (...) to type the SQL statement in 
the Enter SQL Query dialog box, or click Build Query to compose the statement using the Query Builder 
dialog box. 


Related Topics: Query Builder 


SQLSourceType = File connection 
FileConnection 
Select an existing File connection manager, or click <New connection...> to create a new connection manager. 


Related Topics: File Connection Manager, File Connection Manager Editor 


SQLSourceType = Variable 
SourceVariable 
Select an existing variable, or click <New variable...> to create a new variable. 


Related Topics: Integration Services (SSIS) Variables, Add Variable 


Parameter Mapping Page - Execute SQL Task Editor 


Use the Parameter Mapping page of the Execute SQL Task Editor dialog box to map variables to 
parameters in the SQL statement. 


Options 

Variable Name 

After you have added a parameter mapping by clicking Add, select a system or user-defined variable from the 
list or click <New variable...> to add a new variable by using the Add Variable dialog box. 


Related Topics: Integration Services (SSIS) Variables 


Direction 
Select the direction of the parameter. Map each variable to an input parameter, output parameter, or a return 
code. 


Data Type 
Select the data type of the parameter. The list of available data types is specific to the provider selected in the 
connection manager used by the task. 


Parameter Name 


Provide a parameter name. 


Depending on the connection manager type that the task uses, you must use numbers or parameter names. 
Some connection manager types require that the first character of the parameter name is the @ sign , specific 


names like @Param1, or column names as parameter names. 


Parameter Size 


Provide the size of parameters that have variable length, such as strings and binary fields. 
This setting ensures that the provider allocates sufficient space for variable-length parameter values. 


Add 
Click to add a parameter mapping. 


Remove 


Select a parameter mapping in the list and then click Remove. 


Result Set Page - Execute SQL Task Editor 


Use the Result Set page of the Execute SQL Task Editor dialog to map the result of the SQL statement to 
new or existing variables. The options in this dialog box are disabled if ResultSet on the General page is set to 
None. 


Options 
Result Name 


After you have added a result set mapping set by clicking Add, provide a name for the result. Depending on the 
result set type, you must use specific result names. 


If the result set type is Single row, you can use either the name of a column returned by the query or the 
number that represents the position of a column in the column list of a column returned by the query. 


If the result set type is Full result set or XML, you must use 0 as the result set name. 


Variable Name 
Map the result set to a variable by selecting a variable or click <New variable...> to add a new variable by 
using the Add Variable dialog box. 


Add 
Click to add a result set mapping. 


Remove 
Select a result set mapping in the list and then click Remove. 


Parameters in the Execute SQL Task 


SQL statements and stored procedures frequently use input parameters, output parameters, and return codes. 
In Integration Services, the Execute SQL task supports the Input, Output, and ReturnValue parameter types. 


You use the Input type for input parameters, Output for output parameters, and ReturnValue for return codes. 





NOTE 


You can use parameters in an Execute SQL task only if the data provider supports them. 





Parameters in SQL commands, including queries and stored procedures, are mapped to user-defined variables 
that are created within the scope of the Execute SQL task, a parent container, or within the scope of the package. 
The values of variables can be set at design time or populated dynamically at run time. You can also map 
parameters to system variables. For more information, see Integration Services (SSIS) Variables and System 
Variables. 


However, working with parameters and return codes in an Execute SQL task is more than just knowing what 
parameter types the task supports and how these parameters will be mapped. There are additional usage 
requirements and guidelines to successfully use parameters and return codes in the Execute SQL task. The 
remainder of this topic covers these usage requirements and guidelines: 


e Using parameters names and markers 
e Using parameters with date and time data types 
e Using parameters in WHERE clauses 


e Using parameters with stored procedures 


e Getting values of return codes 


Parameter names and markers 


Depending on the connection type that the Execute SQL task uses, the syntax of the SQL command uses 
different parameter markers. For example, the ADO.NET connection manager type requires that the SQL 
command uses a parameter marker in the format @varParameter, whereas OLE DB connection type requires 
the question mark (?) parameter marker. 


The names that you can use as parameter names in the mappings between variables and parameters also vary 
by connection manager type. For example, the ADO.NET connection manager type uses a user-defined name 
with a @ prefix, whereas the OLE DB connection manager type requires that you use the numeric value of a 0- 
based ordinal as the parameter name. 


The following table summarizes the requirements for SQL commands for the connection manager types that the 
Execute SQL task can use. 


CONNECTION TYPE PARAMETER MARKER PARAMETER NAME EXAMPLE SQL COMMAND 


ADO 2 Param1, Param2, ... SELECT FirstName, 
LastName, Title FROM 
Person.Contact WHERE 
ContactID = ? 


ADO.NET @<parameter name> @<parameter name> SELECT FirstName, 
LastName, Title FROM 
Person.Contact WHERE 
ContactID = 
@parmContactID 


ODBC ? i Peres Pee SELECT FirstName, 
LastName, Title FROM 
Person.Contact WHERE 
ContactID = ? 


EXCEL and OLE DB ? Oe S yc SELECT FirstName, 
LastName, Title FROM 
Person.Contact WHERE 
ContactID = ? 


Use parameters with ADO.NET and ADO Connection Managers 


ADO.NET and ADO connection managers have specific requirements for SQL commands that use parameters: 


e ADONET connection managers require that the SQL command use parameter names as parameter 
markers. This means that variables can be mapped directly to parameters. For example, the variable 
@varName is mapped to the parameter named @parName and provides a value to the parameter @parName 


e ADO connection managers require that the SQL command use question marks (?) as parameter markers. 


However, you can use any user-defined name, except for integer values, as parameter names. 


To provide values to parameters, variables are mapped to parameter names. Then, the Execute SQL task uses the 


ordinal value of the parameter name in the parameter list to load values from variables to parameters. 


Use parameters with EXCEL, ODBC, and OLE DB Connection Managers 

EXCEL, ODBC, and OLE DB connection managers require that the SQL command use question marks (?) as 
parameter markers and 0-based or 1-based numeric values as parameter names. If the Execute SQL task uses 
the ODBC connection manager, the parameter name that maps to the first parameter in the query is named 1; 


otherwise, the parameter is named 0. For subsequent parameters, the numeric value of the parameter name 


indicates the parameter in the SQL command that the parameter name maps to. For example, the parameter 
named 3 maps to the third parameter, which is represented by the third question mark (?) in the SQL command. 


To provide values to parameters, variables are mapped to parameter names and the Execute SQL task uses the 


ordinal value of the parameter name to load values from variables to parameters. 


Depending on the provider that the connection manager uses, some OLE DB data types may not be supported. 
For example, the Excel driver recognizes only a limited set of data types. For more information about the 
behavior of the Jet provider with the Excel driver, see Excel Source. 


Use parameters with OLE DB Connection Managers 
When the Execute SQL task uses the OLE DB connection manager, the BypassPrepare property of the task is 
available. You should set this property to true if the Execute SQL task uses SQL statements with parameters. 


When you use an OLE DB connection manager, you cannot use parameterized subqueries because the Execute 
SQL Task cannot derive parameter information through the OLE DB provider. However, you can use an 
expression to concatenate the parameter values into the query string and to set the SqlStatementSource 
property of the task. 


Use parameters with date and time data types 

Use date and time parameters with ADO.NET and ADO Connection Managers 

When reading data of the SQL Server types, time and datetimeoffset, an Execute SQL task that uses either an 
ADO.NET or ADO connection manager has the following additional requirements: 


e For time data, an ADO.NET connection manager requires this data to be stored in a parameter whose 
parameter type is Input or Output, and whose data type is string. 


e For datetimeoffset data, an ADO.NET connection manager requires this data to be stored in one of the 


following parameters: 
o A parameter whose parameter type is Input and whose data type is string. 


o A parameter whose parameter type is Output or ReturnValue, and whose data type is 
datetimeoffset, string, or datetime2. If you select a parameter whose data type is either string 
or datetime2, Integration Services converts the data to either string or datetime2. 


e AnADO connection manager requires that either time or datetimeoffset data be stored in a parameter 
whose parameter type is Input or Output, and whose data type is adVarWchar. 


For more information about SQL Server data types and how they map to Integration Services data types, see 
Data Types (Transact-SQL) and Integration Services Data Types. 


Use date and time parameters with OLE DB Connection Managers 
When using an OLE DB connection manager, an Execute SQL task has specific storage requirements for data of 
the SQL Server data types, date, time, datetime, datetime2, and datetimeoffset. You must store this data in 


one of the following parameter types: 
e Aninput parameter of the NVARCHAR data type. 


e An output parameter of with the appropriate data type, as listed in the following table. 


OUTPUT PARAMETER TYPE DATE DATA TYPE 
DBDATE date 
DBTIME2 time 


DBTIMESTAMP datetime, datetime2 


OUTPUT PARAMETER TYPE DATE DATA TYPE 


DBTIMESTAMPOFFSET datetimeoffset 


If the data is not stored in the appropriate input or output parameter, the package fails. 


Use date and time parameters with ODBC Connection Managers 


When using an ODBC connection manager, an Execute SQL task has specific storage requirements for data with 
one of the SQL Server data types, date, time, datetime, datetime2, or datetimeoffset. You must store this 
data in one of the following parameter types: 


e Aninput parameter of the SQL_WVARCHAR data type 


e An output parameter with the appropriate data type, as listed in the following table. 


OUTPUT PARAMETER TYPE DATE DATA TYPE 
SQL_DATE date 

SQL_SS_TIME2 time 
SQL_TYPE_TIMESTAMP datetime, datetime2 
-or- 


SQL_TIMESTAMP 


SQL_SS_TIMESTAMPOFFSET datetimeoffset 


If the data is not stored in the appropriate input or output parameter, the package fails. 


Use parameters in WHERE clauses 


SELECT, INSERT, UPDATE, and DELETE commands frequently include WHERE clauses to specify filters that define 
the conditions each row in the source tables must meet to qualify for an SQL command. Parameters provide the 
filter values in the WHERE clauses. 


You can use parameter markers to dynamically provide parameter values. The rules for which parameter 
markers and parameter names can be used in the SQL statement depend on the type of connection manager 
that the Execute SQL uses. 


The following table lists examples of the SELECT command by connection manager type. The INSERT, UPDATE, 
and DELETE statements are similar. The examples use SELECT to return products from the Product table in 
AdventureWorks2012 that have a ProductID greater than and less than the values specified by two 
parameters. 


CONNECTION TYPE SELECT SYNTAX 


EXCEL, ODBC, and OLEDB SELECT* FROM Production.Product WHERE ProductId > ? 
AND ProductID < ? 


ADO SELECT* FROM Production.Product WHERE ProductId > ? 
AND ProductID < ? 


ADO.NET SELECT* FROM Production.Product WHERE ProductId > 
@parmMinProductID AND ProductID < @parmMaxProductID 


The examples would require parameters that have the following names: 


e@ The EXCEL and OLED DB connection managers use the parameter names 0 and 1. The ODBC connection 
type uses 1 and 2. 


e The ADO connection type could use any two parameter names, such as Param1 and Param2, but the 
parameters must be mapped by their ordinal position in the parameter list. 


e The ADO.NET connection type uses the parameter names @parmMinProductID and 
@parmMaxProductiD. 


Use parameters with stored procedures 


SQL commands that run stored procedures can also use parameter mapping. The rules for how to use 
parameter markers and parameter names depends on the type of connection manager that the Execute SQL 


uses, just like the rules for parameterized queries. 


The following table lists examples of the EXEC command by connection manager type. The examples run the 
uspGetBillOfMaterials stored procedure in AdventureWorks2012. The stored procedure uses the 


@StartProductID and @CheckDate input parameters. 


CONNECTION TYPE EXEC SYNTAX 
EXCEL and OLEDB EXEC uspGetBillOfMaterials ?, ? 
ODBC {call uspGetBillOfMaterials(?, ?)} 


For more information about ODBC call syntax, see the topic, 
Procedure Parameters, in the ODBC Programmer's Reference 
in the MSDN Library. 


ADO If IsQueryStoredProcedure is set to False, 
EXEC uspGetBillOfMaterials ?, ? 


If IsQueryStoredProcedure is set to True, 
uspGetBillOfMaterials 


ADO.NET If IsQueryStoredProcedure is set to False, 


EXEC uspGetBillOfMaterials @StartProductID, 
@CheckDate 


If IsQueryStoredProcedure is set to True, 
uspGetBillOfMaterials 


To use output parameters, the syntax requires that the OUTPUT keyword follow each parameter marker. For 
example, the following output parameter syntax is correct: EXEC myStoredProcedure ? OUTPUT . 


For more information about using input and output parameters with Transact-SQL stored procedures, see 
EXECUTE (Transact-SQL). 


Map query parameters to variables 


This section describes how to use a parameterized SQL statement in the Execute SQL task and create mappings 
between variables and the parameters in the SQL statement. 


1. In SQL Server Data Tools (SSDT), open the Integration Services package you want to work with. 
2. In Solution Explorer, double-click the package to open it. 


3. Click the Control Flow tab. 


. If the package does not already include an Execute SQL task, add one to the control flow of the package. 
For more information, see Add or Delete a Task or a Container in a Control Flow. 


. Double-click the Execute SQL task. 
. Provide a parameterized SQL command in one of the following ways: 
e Use direct input and type the SQL command in the SQLStatement property. 


e Use direct input, click Build Query, and then create an SQL command using the graphical tools 
that the Query Builder provides. 


e Usea file connection and then reference the file that contains the SQL command. 
e Usea variable and then reference the variable that contains the SQL command. 


The parameter markers that you use in parameterized SQL statements depend on the connection type 
that the Execute SQL task uses. 


CONNECTION TYPE PARAMETER MARKER 
ADO ? 
ADO.NET and SQLMOBILE @<parameter name> 
ODBC ? 
EXCEL and OLE DB ? 


The following table lists examples of the SELECT command by connection manager type. Parameters 
provide the filter values in the WHERE clauses. The examples use SELECT to return products from the 
Product table in AdventureWorks2012 that have a ProductID greater than and less than the values 
specified by two parameters. 


CONNECTION TYPE SELECT SYNTAX 


EXCEL, ODBC, and OLEDB SELECT* FROM Production.Product WHERE ProductId 
> ? AND ProductID < ? 


ADO SELECT* FROM Production.Product WHERE ProductId 
> ? AND ProductID < ? 


ADO.NET SELECT* FROM Production.Product WHERE ProductId 
> @parmMinProductID AND ProductID < 
@parmMaxProductID 


. Click Parameter Mapping. 
. To add a parameter mapping, click Add. 
. Provide a name in the Parameter Name box. 


The parameter names that you use depend on the connection type that the Execute SQL task uses. 


CONNECTION TYPE PARAMETER NAME 


ADO Param1, Param2, ... 


CONNECTION TYPE PARAMETER NAME 


ADO.NET and SQLMOBILE @<parameter name> 
ODBC Vic2p sins 
EXCEL and OLE DB 0.1 2). 3)-38 


10. From the Variable Name list, select a variable. For more information, see Add, Delete, Change Scope of 
User-Defined Variable in a Package. 


11. In the Direction list, specify if the parameter is an input, an output, or a return value. 


12. In the Data Type list, set the data type of the parameter. 


IMPORTANT 


The data type of the parameter must be compatible with the data type of the variable. 





13. Repeat steps 8 through 11 for each parameter in the SQL statement. 





IMPORTANT 


The order of parameter mappings must be the same as the order in which the parameters appear in the SQL 


statement. 








14. Click OK. 


Get the values of return codes 


A stored procedure can return an integer value, called a return code, to indicate the execution status of a 
procedure. To implement return codes in the Execute SQL task, you use parameters of the ReturnValue type. 


The following table lists by connection type some examples of EXEC commands that implement return codes. All 
examples use an input parameter. The rules for how to use parameter markers and parameter names are the 
same for all parameter types-Input, Output, and ReturnValue. 


Some syntax does not support parameter literals. In that case, you must provide the parameter value by using a 


variable. 

CONNECTION TYPE EXEC SYNTAX 

EXCEL and OLEDB EXEC ? = myStoredProcedure 1 

ODBC {? = call myStoredProcedure(1)} 
For more information about ODBC call syntax, see the topic, 
Procedure Parameters, in the ODBC Programmer's Reference 
in the MSDN Library. 

ADO If IsQueryStoreProcedure is set to False, 


EXEC ? = myStoredProcedure 1 


If IsQueryStoreProcedure is set to True, 


myStoredProcedure 


CONNECTION TYPE EXEC SYNTAX 


ADO.NET Set IsQueryStoreProcedure is set to True. 


myStoredProcedure 


In the syntax shown in the previous table, the Execute SQL task uses the Direct Input source type to run the 
stored procedure. The Execute SQL task can also use the File Connection source type to run a stored 
procedure. Regardless of whether the Execute SQL task uses the Direct Input or File Connection source type, 
use a parameter of the ReturnValue type to implement the return code. 


For more information about using return codes with Transact-SQL stored procedures, see RETURN (Transact- 
SQL). 


Result Sets in the Execute SQL Task 


In an Integration Services package, whether a result set is returned to the Execute SQL task depends on the type 
of SQL command that the task uses. For example, a SELECT statement typically returns a result set, but an 
INSERT statement does not. 


What the result set contains also varies by SQL command. For example, the result set from a SELECT statement 
can contain zero rows, one row, or many rows. However, the result set from a SELECT statement that returns a 


count or a sum contains only a single row. 


Working with result sets in an Execute SQL task is more than just knowing whether the SQL command returns a 
result set and what that result set contains. There are additional usage requirements and guidelines to 
successfully use result sets in the Execute SQL task. The remainder of this topic covers these usage requirements 
and guidelines: 


e Specifying a Result Set Type 
e Populating a variable with a result set 


Specify a result set type 
The Execute SQL task supports the following types of result sets: 


e The None result set is used when the query returns no results. For example, this result set is used for 
queries that add, change, and delete records in a table. 


e The Single row result set is used when the query returns only one row. For example, this result set is 
used for a SELECT statement that returns a count or a sum. 


e The Full result set result set is used when the query returns multiple rows. For example, this result set is 
used for a SELECT statement that retrieves all the rows in a table. 


e The XML result set is used when the query returns a result set in an XML format. For example, this result 
set is used for a SELECT statement that includes a FOR XML clause. 


If the Execute SQL task uses the Full result set result set and the query returns multiple rowsets, the task 
returns only the first rowset. If this rowset generates an error, the task reports the error. If other rowsets 
generate errors, the task does not report them. 


Populate a variable with a result set 


You can bind the result set that a query returns to a user-defined variable, if the result set type is a single row, a 
rowset, or XML. 


If the result set type is Single row, you can bind a column in the return result to a variable by using the column 
name as the result set name, or you can use the ordinal position of the column in the column list as the result 
set name. For example, the result set name for the query 

SELECT Color FROM Production.Product WHERE ProductID = ? could be Color or 0. If the query returns multiple 
columns and you want to access the values in all columns, you must bind each column to a different variable. If 
you map columns to variables using numbers as result set names, the numbers reflect the order in which the 
columns appear in the column list of the query. For example, in the query 

SELECT Color, ListPrice, FROM Production.Product WHERE ProductID = ? , you use O for the Color column and 1 
for the ListPrice column. The ability to use a column name as the name of a result set depends on the provider 
that the task is configured to use. Not all providers make column names available. 


Some queries that return a single value may not include column names. For example, the statement 

SELECT COUNT (*) FROM Production.Product returns no column name. You can access the return result using the 
ordinal position, 0, as the result name. To access the return result by column name, the query must include an 
AS <alias name> clause to provide a column name. The statement 

SELECT COUNT (*)AS CountOfProduct FROM Production.Product , provides the CountOfProduct column. You can 


then access the return result column using the CountOfProduct column name or the ordinal position, 0. 
If the result set type is Full result set or XML, you must use 0 as the result set name. 


When you map a variable to a result set with the Single row result set type, the variable must have a data type 
that is compatible with the data type of the column that the result set contains. For example, a result set that 
contains a column with a String data type cannot map to a variable with a numeric data type. When you set the 
TypeConversionMode property to Allowed, the Execute SQL Task will attempt to convert output parameter 
and query results to the data type of the variable the results are assigned to. 


An XML result set can map only to a variable with the String or Object data type. If the variable has the String 
data type, the Execute SQL task returns a string and the XML source can consume the XML data. If the variable 
has the Object data type, the Execute SQL task returns a Document Object Model (DOM) object. 


A Full result set must map to a variable of the Object data type. The return result is a rowset object. You can 
use a Foreach Loop container to extract the table row values that are stored in the Object variable into package 
variables, and then use a Script Task to write the data stored in packages variables to a file. For a demonstration 
on how to do this using a Foreach Loop container and a Script Task. 


The following table summarizes the data types of variables that can be mapped to result sets. 
RESULT SET TYPE DATA TYPE OF VARIABLE TYPE OF OBJECT 


Single row Any type that is compatible with the Not applicable 
type column in the result set. 


RESULT SET TYPE DATA TYPE OF VARIABLE TYPE OF OBJECT 


Full result set Object If the task uses a native connection 
manager, including the ADO, OLE DB, 
Excel, and ODBC connection managers, 
the returned object is an ADO 
Recordset. 


If the task uses a managed connection 
manager, such as the ADO.NET 
connection manager, then the 
returned object is a 
System.Data.DataSet. 


You can use a Script task to access the 
System.Data.DataSet object, as 
shown in the following example. 


Dim dt As Data.DataTable 


Dim ds As Data.DataSet = 
CType(Dts.Variables("Recordset").Value, 
DataSet) dt = ds.Tables(@) 


XML String String 


XML Object If the task uses a native connection 
manager, including the ADO, OLE DB, 
Excel, and ODBC connection managers, 
the returned object is an 
MSXML6.IXMLDOMDocument. 


If the task uses a managed connection 
manager, such as the ADO.NET 
connection manager, the returned 
object is a 
System.Xml.XmIDocument. 


The variable can be defined in the scope of the Execute SQL task or the package. If the variable has package 
scope, the result set is available to other tasks and containers within the package, and is available to any 


packages run by the Execute Package or Execute DTS 2000 Package tasks. 


When you map a variable to a Single row result set, non-string values that the SQL statement returns are 


converted to strings when the following conditions are met: 


e The TypeConversionMode property is set to true. You set the property value in the Properties window 
or by using the Execute SQL Task Editor. 


e The conversion will not result in data truncation. 


Map result sets to variables in an Execute SQL Task 


This section describes how to create a mapping between a result set and a variable in an Execute SQL task. 
Mapping a result set to a variable makes the result set available to other elements in the package. For example, a 
script in a Script task can read the variable and then use the values from the result set or an XML source can 
consume the result set stored in a variable. If the result set is generated by a parent package, the result set can 
be made available to a child package called by an Execute Package task by mapping the result set to a variable in 
the parent package, and then creating a parent package variable configuration in the child package to store the 


parent variable value. 


1. In SQL Server Data Tools (SSDT), open the Integration Services project that contains the package you 
want. 


2. InSolution Explorer, double-click the package to open it. 
3. Click the Control Flow tab. 


4. If the package does not already include an Execute SQL task, add one to the control flow of the package. 
For more information, see Add or Delete a Task or a Container in a Control Flow. 


5. Double-click the Execute SQL task. 


6. Inthe Execute SQL Task Editor dialog box, on the General page, select the Single row, Full result 
set, or XML result set type. 


7. Click Result Set. 
8. To add a result set mapping, click Add. 


9. From the Variables Name list, select a variable or create a new variable. For more information, see Add, 
Delete, Change Scope of User-Defined Variable in a Package. 


10. In the Result Name list, optionally, modify the name of the result set. 


In general, you can use the column name as the result set name, or you can use the ordinal position of 
the column in the column list as the result set. The ability to use a column name as the result set name 
depends on the provider that the task is configured to use. Not all providers make column names 
available. 


11. Click OK. 


Troubleshoot the Execute SQL task 


You can log the calls that the Execute SQL task makes to external data providers. You can use this logging 
capability to troubleshoot the SQL commands that the Execute SQL task runs. To log the calls that the Execute 
SQL task makes to external data providers, enable package logging and select the Diagnostic event at the 
package level. For more information, see Troubleshooting Tools for Package Execution. 


Sometimes a SQL command or stored procedure returns multiple result sets. These result sets include not only 
rowsets that are the result of SELECT queries, but single values that are the result of errors of RAISERROR or 
PRINT statements. Whether the task ignores errors in result sets that occur after the first result set depends on 
the type of connection manager that is used: 


e@ When you use OLE DB and ADO connection managers, the task ignores the result sets that occur after the 
first result set. Therefore, with these connection managers, the task ignores an error returned by an SQL 
command or a stored procedure when the error is not part of the first result set. 


e@ When you use ODBC and ADO.NET connection managers, the task does not ignore result sets that occur 
after the first result set. With these connection managers, the task will fail with an error when a result set 
other than the first result set contains an error. 


Custom Log Entries 


The following table describes the custom log entry for the Execute SQL task. For more information, see 
Integration Services (SSIS) Logging. 


LOG ENTRY DESCRIPTION 


LOG ENTRY 


ExecuteSQLExecutingQuery 


DESCRIPTION 


Provides information about the execution phases of the SQL 
statement. Log entries are written when the task acquires 
connection to the database, when the task starts to prepare 
the SQL statement, and after the execution of the SQL 
statement is completed. The log entry for the prepare phase 
includes the SQL statement that the task uses. 


MERGE in Integration Services Packages 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


In the current release of SQL Serverlntegration Services, the SQL statement in an Execute SQL task can contain a 
MERGE statement. This MERGE statement enables you to accomplish multiple INSERT, UPDATE, and DELETE 
operations in a single statement. 


To use the MERGE statement in a package, follow these steps: 
e Create a Data Flow task that loads, transforms, and saves the source data to a temporary or staging table. 
e Create an Execute SQL task that contains the MERGE statement. 


e Connect the Data Flow task to the Execute SQL task, and use the data in the staging table as the input for 
the MERGE statement. 


NOTE 


Although a MERGE statement typically requires a staging table in this scenario, the performance of the MERGE 
statement usually exceeds that of the row-by-row lookup performed by the Lookup transformation. MERGE is 
also useful when the large size of a lookup table would test the memory that is available to the Lookup 
transformation for caching its reference table. 








Using MERGE 


Typically, you use the MERGE statement when you want to apply changes that include inserts, updates, and 
deletions from one table to another table. Prior to SQL Server 2008, this process required both a Lookup 
transformation and multiple OLE DB Command transformations. The Lookup transformation performed a row- 
by-row lookup to determine whether each row was new or changed. The OLE DB Command transformations 
then performed the necessary INSERT, UPDATE, and DELETE operations. Beginning in SQL Server 2008, a single 
MERGE statement can replace both the Lookup transformation and the corresponding OLE DB Command 
transformations. 


MERGE with Incremental Loads 


The change data capture functionality that is new in SQL Server 2008 makes it easier to perform incremental 
loads reliably to a data warehouse. As an alternative to using parameterized OLE DB Command transformations 
to perform the inserts and the updates, you can use the MERGE statement to combine both operations. 


For more information, see Apply the Changes to the Destination. 


MERGE in Other Scenarios 

In the following scenarios, you can use the MERGE statement either outside or inside an Integration Services 
package. However, an Integration Services package is often required to load this data from multiple 
heterogeneous sources, and then to combine and cleanse the data. Therefore, you might consider using the 
MERGE statement in a package for convenience and ease of maintenance. 


Track Buying Habits 

The FactBuyingHabits table in the data warehouse tracks the last date on which a customer bought a given 
product. The table consists of ProductID, CustomerID and PurchaseDate columns. Every week, the transactional 
database generates a PurchaseRecords table that includes the purchases made during that week. The objective 
is to use a single MERGE statement to merge the information in the PurchaseRecords table into the 


FactBuyingHabits table. For product-customer pairs that do not exist, the MERGE statement inserts new rows. 
For product-customer pairs that exist, the MERGE statement updates the most recent date-of-purchase. 

The DimBook table represents the list of books in the inventory of a book seller and identifies the price history 
of each book. This table has these columns: ISBN, ProductID, Price, Shelf, and IsCurrent. This table also has one 
row for each price the book has had. One of these rows contains the current price. To indicate which row 
contains the current price, the value of the IsCurrent column for that row is set to 1. 


Every week, the database generates a WeeklyChanges table that contains price changes for the week and new 
books that were added during the week. By using a single MERGE statement, you can apply the changes in the 
WeeklyChanges table to the DimBook table. The MERGE statement inserts new rows for newly-added books, 
and updates the IsCurrent column to 0 for rows of existing books whose prices have changed. The MERGE 
statement also inserts new rows for books whose prices have changed, and for these new rows, sets the value of 


the IsCurrent column to 1. 


Merge a Table with New Data Against the Old Table 


The database models the properties of an object by using an "open schema," that is, a table contains name-value 
pairs for each property. The Properties table has three columns: EntityID, Property|ID, and Value. A 
NewProperties table that is a newer version of the table has to be synchronized with the Properties table. To 


synchronize these two tables, you can use a single MERGE statement to perform the following operations: 
e Delete properties from the Properties table if they are absent from the NewProperties table. 


e Update values for properties that are in the Properties table with new values found in the NewProperties 
table. 


e Insert new properties for properties that are in the NewProperties table but are not found in the 
Properties table. 


This approach is useful in scenarios that resemble replication scenarios, where the objective is to keep data in 


two tables on two servers synchronized. 


Track Inventory 


The Inventory database has a ProductsInventory table that has ProductID and StockOnHand columns. A 
Shipments table with ProductID, CustomerID, and Quantity columns tracks shipments of products to customers. 
The ProductInventory table has to be updated daily based on information in the Shipments table. A single 
MERGE statement can reduce the inventory in the ProductInventory table based on the shipments made. If the 
inventory for a product has been reduced to 0, that MERGE statement can also delete that product row from the 
Productinventory table. 


Execute T-SQL Statement Task 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


The Execute T-SQL Statement task runs Transact-SQL statements. For more information, see Transact-SQL 
Reference (Database Engine) and Integration Services (SSIS) Queries. 


This task is similar to the Execute SQL task. However, the Execute T-SQL Statement task supports only the 
Transact-SQL version of the SQL language and you cannot use this task to run statements on servers that use 
other dialects of the SQL language. If you need to run parameterized queries, save the query results to variables, 
or use property expressions, you should use the Execute SQL task instead of the Execute T-SQL Statement task. 
For more information, see Execute SQL Task. 


Configuration of the Execute T-SQL Task 


You can set properties through SSIS Designer. This task is in the Maintenance Plan Tasks section of the 
Toolbox in SSIS Designer. 


For more information about the properties that you can set in SSIS Designer, click the following topic: 
e Execute T-SQL Statement Task (Maintenance Plan) 
For more information about how to set these properties in SSIS Designer, click the following topic: 


e Set the Properties of a Task or Container 


See Also 


Integration Services Tasks 
Control Flow 


MERGE in Integration Services Packages 


Expression Task 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


The Expression Task creates and evaluates expressions that set variable values at runtime, using the Expression 
Builder. When you edit the task, the Expression Builder is launched. 


Expression Examples 


The expression language includes functions and operators. For examples that demonstrate how to use the 
functions and operators, see the Expression Examples sections in the functions and operators topics. Links to 
the topics are in Functions (SSIS Expression)and Operators (SSIS Expression). 


For examples of more complex expressions, see Examples of Advanced Integration Services Expressions. 


For examples of using expressions to set properties, see the Sample Property Expressions section in Use 
Property Expressions in Packages. 


Related Tasks 


Use an Expression in a Data Flow Component 


Related Content 


Technical article, SSIS Expression Cheat Sheet, on pragmaticworks.com 


File System Task 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


The File System task performs operations on files and directories in the file system. For example, by using the 
File System task, a package can create, move, or delete directories and files. You can also use the File System 
task to set attributes on files and directories. For example, the File System task can make files hidden or read- 
only. 


All File System task operations use a source, which can be a file or a directory. For example, the file that the task 
copies or the directory it deletes is a source. The source can be specified by using a File connection manager that 
points to the directory or file or by providing the name of a variable that contains the source path. For more 
information, see File Connection Manager and Integration Services (SSIS) Variables. 


The operations that copy and move file and directories and rename files use a destination and a source. The 
destination is specified by using a File connection manager or a variable. File system task operations can be 
configured to permit overwriting of destination files and directories. The operation that creates a new directory 
can be configured to use an existing directory that has the specified name instead of failing when the directory 
already exists. 


Predefined File System Operations 


The File System task includes a predefined set of operations. The following table describes these operations. 


OPERATION DESCRIPTION 

Copy directory Copies a folder from one location to another. 
Copy file Copies a file from one location to another. 
Create directory Creates a folder in a specified location. 
Delete directory Deletes a folder in a specified location. 
Delete directory content Deletes all files and folders in a folder. 

Delete file Deletes a file in a specified location. 

Move directory Moves a folder from one location to another. 
Move file Moves a file from one location to another. 
Rename file Renames a file in a specified location. 

Set attributes Sets attributes on files and folders. Attributes include 


Archive, Hidden, Normal, ReadOnly, and System. Normal is 
the lack of attributes, and it cannot be combined with other 
attributes. All other attributes can be used in combination. 


The File System task operates on a single file or directory. Therefore, this task does not support the use of 


wildcard characters to perform the same operation on multiple files. To have the File System task repeat an 
operation on multiple files or directories, put the File System task in a Foreach Loop container, as described in 
the following steps: 


e Configure the Foreach Loop container On the Collection page of the Foreach Loop Editor, set the 
enumerator to Foreach File Enumerator and enter the wildcard expression as the enumerator 
configuration for Files. On the Variable Mappings page of the Foreach Loop Editor, map a variable that 
you want to use to pass the file names one at a time to the File System task. 


e Add and configure a File System task Add a File System task to the Foreach Loop container. On the 
General page of the File System Task Editor, set the SourceVariable or DestinationVariable property 
to the variable that you defined in the Foreach Loop container. 


Custom Log Entries Available on the File System Task 


The following table describes the custom log entry for the File System task. For more information, see 
Integration Services (SSIS) Logging. 


LOG ENTRY DESCRIPTION 


FileSystemOperation Reports the operation that the task performs. The log entry 
is written when the file system operation starts and includes 
information about the source and destination. 


Configuring the File System Task 

You can set properties through SSIS Designer or programmatically. 

For more information about the properties that you can set in SSIS Designer, see the following topics: 
e File System Task Editor (General Page) 

e Expressions Page 

For more information about how to set these properties in SSIS Designer, see the following topic: 

e Set the Properties of a Task or Container 

For more information about how to set these properties programmatically, see the following topic: 


e FileSystemTask 


Related Tasks 


Integration Services includes a task that downloads and uploads data files and manages directories on servers. 
For more information, see FTP Task. 


File System Task Editor (General Page) 


Use the General page of the File System Task Editor dialog to configure the file system operation that the 
task performs. 


You must specify a source and destination connection manager by setting the SourceConnection and 
DestinationConnection properties. You can either provide the names of File connection managers that point to 
the files that the task uses as a source or destination, or if the paths of the files are stored in variables, you can 
provide the names of the variables. To use variables to store the file paths, you must set first set the 
IsSourcePathVariable option for the source connection and the IsDestinationPatheVariable option for the 


destination connection to True. You can then choose the existing system or user-defined variables to use, or you 
can create new variables. In the Add Variable dialog box, you can configure and specify the scope of the 
variables. The scope must be the File System task or a parent container. For more information see, Integration 
Services (SSIS) Variables and Use Variables in Packages. 





NOTE 


To override the variables you selected for the SourceConnection and DestinationConnection properties, enter an 
expression for the Source and Destination properties. You enter expressions on the Expressions page of the File 
System Task Editor. For example, to set the path of the files that the task uses as a destination, you may want to use 
variable A under certain conditions and use variable B under other conditions. 








NOTE 


The File System task operates on a single file or directory. Therefore, this task does not support the use of wildcard 
characters to perform the same operation on multiple files or directories. To have the File System task repeat an operation 
on multiple files or directories, put the File System task in a Foreach Loop container. For more information, see File System 
Task. 








You can use expressions to use different variables for the 


Options 

IsDestinationPathVariable 

Indicate whether the destination path is stored in a variable. This property has the options listed in the following 
table. 


VALUE DESCRIPTION 


True The destination path is stored in a variable. Selecting this 
value displays the dynamic option, DestinationVariable. 


False The destination path is specified in a File connection 
manager. Selecting this value displays the dynamic option, 
DestinationConnection. 


OverwriteDestination 
Specify whether the operation can overwrite files in the destination directory. 


Name 
Provide a unique name for the File System task. This name is used as the label in the task icon. 


NOTE 


Task names must be unique within a package. 





Description 
Type a description of the File System task. 


Operation 
Select the file-system operation to perform. This property has the options listed in the following table. 


VALUE 


Copy directory 


Copy file 


Create directory 


Delete directory 


Delete directory content 


Delete file 


Move directory 


Move file 


Rename file 


Set attributes 


IsSourcePathVariable 
Indicate whether the destination path is stored in a variable. 
table. 


VALUE 


True 


False 


IsDestinationPathVariable Dynamic Options 
IsDestinationPathVariable = True 


DestinationVariable 


Select the variable name in the list, or click <New variable. 


DESCRIPTION 


Copy a directory. Selecting this value displays the dynamic 
options for a source and destination. 


Copy a file. Selecting this value displays the dynamic options 
for a source and destination. 


Create a directory. Selecting this value displays the dynamic 
options for a source and a destination directory. 


Delete a directory. Selecting this value displays the dynamic 
options for a source. 


Delete the content of a directory. Selecting this value 
displays the dynamic options for a source. 


Delete a file. Selecting this value displays the dynamic 
options for a source. 


Move a directory. Selecting this value displays the dynamic 
options for a source and destination. 


Move a file. Selecting this value displays the dynamic options 
for a source and destination. When moving a file, do not 
include a file name in the directory path that you provide as 
the destination. 


Rename a file. Selecting this value displays the dynamic 
options for a source and destination. When renaming a file, 
include the new file name in the directory path that you 
provide for the destination. 


Set the attributes of a file or directory. Selecting this value 
displays the dynamic options for a source and operation. 


This property has the options listed in the following 


DESCRIPTION 


The destination path is stored in a variable. Selecting this 
value displays the dynamic option, SourceVariable. 


The destination path is specified in a File connection 
manager. Selecting this value displays the dynamic option, 
DestinationVariable. 


..> to create a new variable. 


Related Topics: Integration Services (SSIS) Variables, Add Variable 


IsDestinationPathVariable = False 


DestinationConnection 
Select a File connection manager in the list, or click <New connection...> to create a new connection manager. 


Related Topics: File Connection Manager, File Connection Manager Editor 


IsSourcePathVariable Dynamic Options 
IsSourcePathVariable = True 
SourceVariable 


Select the variable name in the list, or click <New variable...> to create a new variable. 


Related Topics: Integration Services (SSIS) Variables, Add Variable 


IsSourcePathVariable = False 
SourceConnection 
Select a File connection manager in the list, or click <New connection...> to create a new connection manager. 


Related Topics: File Connection Manager 


Operation Dynamic Options 

Operation = Set Attributes 

Hidden 

Indicate whether the file or directory is visible. 


ReadOnly 
Indicate whether the file is read-only. 


Archive 
Indicate whether the file or directory is ready for archiving. 


System 
Indicate whether the file is an operating system file. 


Operation = Create directory 
UseDirectorylfExists 
Indicates whether the Create directory operation uses an existing directory with the specified name instead of 


creating a new directory. 


See Also 


Integration Services Tasks 
Control Flow 


FTP Task 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


The FTP task downloads and uploads data files and manages directories on servers. For example, a package can 
download data files from a remote server or an Internet location as part of an Integration Services package 
workflow. You can use the FTP task for the following purposes: 


e@ Copying directories and data files from one directory to another, before or after moving data, and 
applying transformations to the data. 


e Logging in to a source FTP location and copying files or packages to a destination directory. 


e Downloading files from an FTP location and applying transformations to column data before loading the 
data into a database. 


At run time, the FTP task connects to a server by using an FTP connection manager. The FTP connection manager 
is configured separately from the FTP task, and then is referenced in the FTP task. The FTP connection manager 
includes the server settings, the credentials for accessing the FTP server, and options such as the time-out and 


the number of retries for connecting to the server. For more information, see FTP Connection Manager. 


IMPORTANT 


The FTP connection manager supports only anonymous authentication and basic authentication. It does not support 


Windows Authentication. 





When accessing a local file or a local directory, the FTP task uses a File connection manager or path information 
stored in a variable. In contrast, when accessing a remote file or a remote directory, the FTP task uses a directly 
specified path on the remote server, as specified in the FTP connection manager, or path information stored in a 


variable. For more information, see File Connection Manager and Integration Services (SSIS) Variables. 


This means that the FTP task can receive multiple files and delete multiple remote files; but the task can send 
only one file and delete only one local file if it uses a connection manager, because a File connection manager 
can access only one file. To access multiple local files, the FTP task must use a variable to provide the path 
information. For example, a variable that contains "C:\Test&#42;.xt" provides a path that supports deleting or 
sending all the files that have a .txt extension in the Test directory. 


To send multiple files and access multiple local files and directories, you can also execute the FTP task multiple 
times by including the task in a Foreach Loop. The Foreach Loop can enumerate across files in a directory using 


the For Each File enumerator. For more information, see Foreach Loop Container. 


The FTP task supports the ?and * wildcard characters in paths. This lets the task access multiple files. However, 
you can use wildcard characters only in the part of the path that specifies the file name. For example, 
C:i\MyDirectory\* txt is a valid path, but C:\*\MyText.txt is not. 


The FTP operations can be configured to stop the File System task when the operation fails, or to transfer files in 
ASCII mode. The operations that send and receive files copy can be configured to overwrite destination files and 
directories. 


Predefined FTP Operations 


The FTP task includes a predefined set of operations. The following table describes these operations. 


OPERATION DESCRIPTION 

Send files Sends a file from the local computer to the FTP server. 
Receive files Saves a file from the FTP server to the local computer. 
Create local directory Creates a folder on the local computer. 

Create remote directory Creates a folder on the FTP server. 

Remove local directory Deletes a folder on the local computer. 

Remove remote directory Deletes a folder on the FTP server. 

Delete local files Deletes a file on the local computer. 

Delete remote files Deletes a file on the FTP server. 


Custom Log Entries Available on the FTP Task 


The following table lists the custom log entries for the FTP task. For more information, see Integration Services 
(SSIS) Logging. 


LOG ENTRY DESCRIPTION 

FTPConnectingToServer Indicates that the task initiated a connection to the FTP 
server. 

FTPOperation Reports the beginning of and the type of FTP operation that 


the task performs. 


Related Tasks 
You can set properties through SSIS Designer or programmatically. 


For information about how to set these properties in SSIS Designer, see Set the Properties of a Task or 


Container. 


For more information about programmatically setting these properties, see FtpTask. 


FTP Task Editor (General Page) 


Use the General page of the FTP Task Editor dialog box to specify the FTP connection manager that connects 
to the FTP server that the task communicates with. You can also name and describe the FTP task. 


Options 
FtpConnection 
Select an existing FTP connection manager, or click <New connection...> to create a connection manager. 





IMPORTANT 


The FTP connection manager supports only anonymous authentication and basic authentication. It does not support 
Windows Authentication. 











Related Topics: FTP Connection Manager, FTP Connection Manager Editor 


StopOnFailure 
Indicate whether the FTP task terminates if an FTP operation fails. 


Name 
Provide a unique name for the FTP task. This name is used as the label in the task icon. 


NOTE 


Task names must be unique within a package. 





Description 
Type a description of the FTP task. 


FTP Task Editor (File Transfer Page) 


Use the File Transfer page of the FTP Task Editor dialog box to configure the FTP operation that the task 


performs. 


Options 

IsRemotePathVariable 

Indicate whether the remote path is stored in a variable. This property has the options listed in the following 
table. 


VALUE DESCRIPTION 


True The destination path is stored in a variable. Selecting the 
value displays the dynamic option, RemoteVariable. 


False The destination path is specified in a File connection 
manager. Selecting the value displays the dynamic option, 
RemotePath. 


OverwriteFileAtDestination 
Specify whether a file at the destination can be overwritten. 


IsLocalPathVariable 
Indicate whether the local path is stored in a variable. This property has the options listed in the following table. 


VALUE DESCRIPTION 


True The destination path is stored in a variable. Selecting the 
value displays the dynamic option, LocalVariable. 


False The destination path is specified in a File connection 
manager. Selecting the value displays the dynamic option, 
LocalPath. 


Operation 


Select the FTP operation to perform. This property has the options listed in the following table. 


VALUE DESCRIPTION 

Send files Send files. Selecting this value displays the dynamic options, 
LocalVariable, LocalPathRemoteVariable and 
RemotePath. 

Receive files Receive files. Selecting this value displays the dynamic 
options, LocalVariable, LocalPathRemoteVariable and 
RemotePath. 

Create local directory Create a local directory. Selecting this value displays the 


dynamic options, LocalVariable and LocalPath. 


Create remote directory Create a remote directory. Selecting this value displays the 
dynamic options, RemoteVariable and RemotelPath. 


Remove local directory Removes a local directory. Selecting this value displays the 
dynamic options, LocalVariable and LocalPath. 


Remove remote directory Remove a remote directory. Selecting this value displays the 
dynamic options, RemoteVariable and RemotePath. 


Delete local files Delete local files. Selecting this value displays the dynamic 
options, LocalVariable and LocalPath. 


Delete remote files Delete remote files. Selecting this value displays the dynamic 
options, RemoteVariable and RemotePath. 


IsTransferASCIl 
Indicate whether files transferred to and from the remote FTP server should be transferred in ASCII mode. 


IsRemotePathVariable Dynamic Options 
IsRemotePathVariable = True 


RemoteVariable 
Select an existing user-defined variable, or click <New variable...> to create a user-defined variable. 


Related Topics: Integration Services (SSIS) Variables, Add Variable 


IsRemotePathVariable = False 
RemotePath 


Select an existing FTP connection manager, or click <New connection...> to create a connection manager. 
Related Topics: FTP Connection Manager, FTP Connection Manager Editor 


IsLocalPathVariable Dynamic Options 
IsLocalPathVariable = True 
LocalVariable 


Select an existing user-defined variable, or click <New variable...> to create a variable. 


Related Topics: Integration Services (SSIS) Variables, Add Variable 


IsLocalPathVariable = False 
LocalPath 


Select an existing File connection manager, or click <New connection...> to create a connection manager. 


Related Topics: Flat File Connection Manager 


See Also 


Integration Services Tasks 
Control Flow 


Hadoop File System Task 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 
The Hadoop File System Task enables an SSIS package to copy files from, to, or within a Hadoop cluster. 


To add a Hadoop File System Task, drag and drop it to the designer. Then double-click on the task, or right-click 
and click Edit, to open the Hadoop File System Task Editor dialog box. 





Ea) Hadoop File System Task Editor - om 


mn) Configure the properties required to perform HDFS file system operations, such as copying files and directories from or 
HDFS —_to the HDFS file system. 


4 Basic 
Expressions Name Hadoop File System Task 1 
Description Hadoop File System Task 
4 Destination 
Hadoop Connection 
Hadoop File Path 
Hadoop File Type File 
Overwrite Destination False 
4 Operation 
Operation CopyToHadoop 
4 Source 
Local File Connection 
Is Recursive False 


Name 
Specifies the name of the task. 








OK | Cancel Help 





Options 


Configure the following options in the Hadoop File System Task Editor dialog box. 
FIELD DESCRIPTION 


Hadoop Connection Specify an existing Hadoop Connection Manager or create a 
new one. This connection manager indicates where the 
destination files are hosted. 


Hadoop File Path Specify the file or directory path on HDFS. 
Hadoop File Type Specify whether the HDFS file system object is a file or 
directory. 


Overwrite Destination Specify whether to overwrite the target file if it already exists. 


FIELD 


Operation 


Local File Connection 


Is Recursive 


See Also 


Hadoop Connection Manager 
File Connection Manager 


DESCRIPTION 


Specify the operation. Available operations are 
CopyToHDFS, CopyFromHDFS, and CopyWithinHDFS. 


Specify an existing File Connection Manager or create a new 
one. This connection manager indicates where the source 
files are hosted. 


Specify whether to copy all subfolders recursively. 


Hadoop Hive Task 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 
Use the Hadoop Hive Task to run Hive script on a Hadoop cluster. 


To add a Hadoop Hive Task, drag and drop it to the designer. Then double-click on the task, or right-click and 
click Edit, to open the Hadoop Hive Task Editor dialog box. 

















3 Hadoop Hive Task Editor - oa 
tT! Submit a Hive job to Hadoop cluster 
+ Basi 
Expressions Name Hadoop Hive Task 
Description Hadoop Hive Task 
4 General 
HadoopConnection 
SourceType Directinput 
InlineScript 
TimeoutinMinutes 1440 
q 
| 
| 
} 
Name q 
Specifies the name of the task. 
4 
OK Cancel Help 
——=———————————————— Ss 


Options 


Configure the following options in the Hadoop Hive Task Editor dialog box. 
FIELD DESCRIPTION 


Hadoop Connection Specify an existing Hadoop Connection Manager or create a 
new one. This connection manager indicates where the 
WebHCat service is hosted. 


SourceType Specify the source type of the query. Available values are 
ScriptFile and DirectInput. 


InlineScript When the value of SourceType is DirectInput, specify the 
hive script. 


FIELD 


HadoopScriptFilePath 


Timeout!InMinutes 


See Also 


Hadoop Connection Manager 


DESCRIPTION 


When the value of SourceType is ScriptFile, specify the 
script file path on Hadoop. 


Specify a timeout value in minutes. The Hadoop job stops if 
it has not finished before the timeout elapses. Specify 0 to 
schedule the Hadoop job to run asynchronously. 


Hadoop Pig Task 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 
Use the Hadoop Pig Task to run Pig script on a Hadoop cluster. 


To add a Hadoop Pig Task, drag and drop it to the designer. Then double-click on the task, or right-click and click 
Edit, to see the Hadoop Pig Task Editor dialog box. 











S Hadoop Pig Task Editor - oz 
Lm) Submit a pig job to Hadoop cluster | 
«Basic 
Expressions Name Hadoop Pig Task | 
Description Hadoop Pig Task 
4 General 
HadoopConnection 
SourceType Directinput 
InlineScript 
TimeoutinMinutes 1440 
q 
} 
Name 
Specifies the name of the task. 
OK Cancel Help 








Options 


Configure the following options in the Hadoop Pig Task Editor dialog box. 


FIELD DESCRIPTION 


Hadoop Connection Specify an existing Hadoop Connection Manager or create a 
new one. This connection manager indicates where the 
WebHCat service is hosted. 


SourceType Specify the source type of the query. Available values are 
ScriptFile and DirectInput. 


InlineScript When the value of SourceType is DirectInput, specify the 
pig script. 


FIELD 


HadoopScriptFilePath 


Timeout!InMinutes 


See Also 


Hadoop Connection Manager 


DESCRIPTION 


When the value of SourceType is ScriptFile, specify the 
script file path on Hadoop. 


Specify a timeout value in minutes. The Hadoop job stops if 
it has not finished before the timeout elapses. Specify 0 to 
schedule the Hadoop job to run asynchronously. 


History Cleanup Task 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 
The History Cleanup task deletes entries in the following history tables in the SQL Server msdb database. 
e backupfile 

e backupfilegroup 

e backupmediafamily 

e backupmediaset 

e@ backupset 

e restorefile 

e restorefilegroup 

e restorehistory 


By using the History Cleanup task, a package can delete historical data related to backup and restore activities, 
SQL Server Agent jobs, and database maintenance plans. 


This task encapsulates the sp_delete_backuphistory system stored procedure and passes the specified date to 
the procedure as an argument. For more information, see sp_delete_backuphistory (Transact-SQL). 


Configuration of the History Cleanup Task 


The task includes a property for specifying the oldest date of data retained in the history tables. You can indicate 
the date by number of days, weeks, months, or years from the current day, and the task automatically translates 
the interval to a date. 


You can set properties through SSIS Designer. This task is in the Maintenance Plan Tasks section of the 
Toolbox in SSIS Designer. 


For more information about the properties that you can set in SSIS Designer, click the following topic: 
e History Cleanup Task (Maintenance Plan) 
For more information about how to set these properties in SSIS Designer, click the following topic: 


e Set the Properties of a Task or Container 


See Also 


Integration Services Tasks 
Control Flow 


Maintenance Cleanup Task 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


The Maintenance Cleanup task removes files related to maintenance plans, including database backup files and 
reports created by maintenance plans. For more information, see Maintenance Plans and Back Up and Restore 
of SQL Server Databases. 


By using the Maintenance Cleanup task, a package can remove the backup files or maintenance plan reports on 
the specified server. The Maintenance Cleanup task includes an option to remove a specific file or remove a 
group of files in a folder. Optionally you can specify the extension of the files to delete. 


When you configure the Maintenance Cleanup task to remove backup files, the default file name extension is 
BAK. For report files, the default file name extension is TXT. You can update the extensions to suit your needs; the 
only limitation is that extensions must be less than 256 characters long. 


Typically, you want to remove old files that are no longer needed, and the Maintenance Cleanup task can be 
configured to delete files that have reached a specified age. For example, the task can be configured to delete 
files that are older than four weeks. You can specify the age of files to delete by using days, weeks, months, or 
years. If you do not specify the minimum age of files to delete, all files of the specified type are deleted. 


In contrast to earlier versions of the Maintenance Cleanup task, the SQL Server version of the task does not 
automatically delete files in the subdirectories of the specified directory. This constraint reduces the surface area 
of any attack that could exploit the functionality of the Maintenance Cleanup task to delete files maliciously. To 
delete the first-level subfolders, you must explicitly elect to do this by checking the Include first-level 
subfolders option in the Maintenance Cleanup Task dialog box. 


Configuration of the Maintenance Cleanup Task 


You can set properties through SSIS Designer. This task is in the Maintenance Plan Tasks section of the 
Toolbox in SSIS Designer. 


For more information about the properties that you can set in SSIS Designer, click the following topic: 


e@ Maintenance Cleanup Task (Maintenance Plan) 


Related Tasks 


For details about how to set these properties in SSIS Designer, see Set the Properties of a Task or Container. 


See Also 


Integration Services Tasks 


Control Flow 


Message Queue Task 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


The Message Queue task allows you to use Message Queuing (also known as MSMQ) to send and receive 
messages between SQL Server Integration Services packages, or to send messages to an application queue that 
is processed by a custom application. These messages can take the form of simple text, files, or variables and 
their values. 


By using the Message Queue task, you can coordinate operations throughout your enterprise. Messages can be 
queued and delivered later if the destination is unavailable or busy; for example, the task can queue messages 
for the offline laptop computer of sales representatives, who receive their messages when they connect to the 
network. You can use the Message Queue task for the following purposes: 


e Delaying task execution until other packages check in. For example, after nightly maintenance at each of 
your retail sites, a Message Queue task sends a message to your corporate computer. A package running 
on the corporate computer contains Message Queue tasks, each waiting for a message from a particular 
retail site. When a message from a site arrives, a task uploads data from that site. After all the sites have 
checked in, the package computes summary totals. 


e Sending data files to the computer that processes them. For example, the output from a restaurant cash 
register can be sent in a data file message to the corporate payroll system, where data about each 
waiter's tips is extracted. 


e Distributing files throughout your enterprise. For example, a package can use a Message Queue task to 
send a package file to another computer. A package running on the destination computer then uses a 
Message Queue task to retrieve and save the package locally. 


When sending or receiving messages, the Message Queue task uses one of four message types: data file, string, 
string message to variable, or variable. The string message to variable message type can be used only when 
receiving messages. 


The task uses an MSMQ connection manager to connect to a message queue. For more information, see MSMQ 
Connection Manager. For more information about Message Queuing, see the MSDN Library. 


The Message Queue task requires that the Integration Services service be installed. Some SQL Server 
components that you may select for installation on the Components to Install page or the Feature 
Selection page of the SQL Server Installation Wizard install a partial subset of Integration Services 
components. These components are useful for specific tasks, but the functionality of Integration Services will be 
limited. For example, the SQL Server Data Tools (SSDT) option installs the Integration Services components 
required to design a package, but the Integration Services service is not installed, and therefore the Message 
Queue task is not functional. To ensure a complete installation of Integration Services, you must select 
Integration Services on the Components to Install page. For more information about installing and running 
the Message Queue task, see Install Integration Services. 


NOTE 


The Message Queue task fails to comply with Federal Information Processing Standard (FIPS) 140-2 when the computer's 
operating system is configured in FIPS mode and the task uses encryption. If the Message Queue task does not use 
encryption, the task can run successfully. 











Message Types 


You can configure the message types that the Message Queue task provides in the following ways: 


e Data file message specifies that a file contains the message. When receiving messages, you can 
configure the task to save the file, overwrite an existing file, and specify the package from which the task 


can receive messages. 


e String message specifies the message as a string. When receiving messages, you can configure the task 
to compare the received string with a user-defined string and take action depending on the comparison. 


String comparison can be exact, case-sensitive or case-insensitive, or use a substring. 


e String message to variable specifies the source message as a string that is sent to a destination 
variable. You can configure the task to compare the received string with a user-defined string using an 
exact, case-insensitive, or substring comparison. This message type is available only when the task is 


receiving messages. 


e Variable specifies that the message contains one or more variables. You can configure the task to specify 
the names of the variables included in the message. When receiving messages, you can configure the 
task to specify both the package from which it can receive messages and the variable that is the 
destination of the message. 


Sending Messages 


When configuring the Message Queue task to send messages, you can use one of the encryption algorithms 
that are currently supported by the Message Queuing technology, RC2 and RC4, to encrypt the message. Both 
of these encryption algorithms are now considered cryptographically weak compared to newer algorithms, 
which Message Queuing technology do not yet support. Therefore, you should consider your cryptography 
needs carefully when sending messages using the Message Queue task. 


Receiving Messages 


When receiving messages, the Message Queue task can be configured in the following ways: 
e Bypassing the message, or removing the message from the queue. 

@ Specifying a time-out. 

e Failing if a time-out occurs. 

e Overwriting an existing file, if the message is stored in a Data file. 


e Saving the message file to a different file name, if the message uses the Data file message type. 


Custom Logging Messages Available on the Message Queue Task 


The following table lists the custom log entries for the Message Queue task. For more information, see 
Integration Services (SSIS) Logging. 


LOG ENTRY DESCRIPTION 
MSMQAfterOpen Indicates that the task finished opening the message queue. 
MSMQBeforeOpen Indicates that the task began to open the message queue. 


MSMQBeginReceive Indicates that the task began to receive a message. 


LOG ENTRY DESCRIPTION 


MSMQBeginSend Indicates that the task began to send a message. 
MSMQEndReceive Indicates that the task finished receiving a message. 
MSMQEndSend Indicates that the task finished sending a message. 
MSMAQtTaskInfo Provides descriptive information about the task. 
MSMQTaskTimeOut Indicates that the task timed out. 


Configuration of the Message Queue Task 


You can set properties through SSIS Designer or programmatically. For information about the properties that 
you can set in SSIS Designer, click the following topic: 


e Expressions Page 


For information about programmatically setting these properties, see the documentation for the 
Microsoft.SqlServer.Dts.Tasks.MessageQueuelask.MessageQueuelask class in the Developer Guide. 


Related Tasks 


For more information about how to set these properties in SSIS Designer, see Set the Properties of a Task or 


Container. 


Message Queue Task Editor (General Page) 


Use the General page of the Message Queue Task Editor dialog box to name and describe the Message 
Queue task, to specify the message format, and to indicate whether the task sends or receives messages. 


Options 


Name 


Provide a unique name for the Message Queue task. This name is used as the label in the task icon. 





NOTE 


Task names must be unique within a package. 





Description 
Type a description of the Message Queue task. 


Use2000Format 
Indicate whether to use the 2000 format of Message Queuing (also known as MSMQ). The default is False. 


MSMQConnection 
Select an existing MSMQ connection manager or click <New connection...> to create a new connection 


manager. 
Related Topics: MSMQ Connection Manager, MSMQ Connection Manager Editor 


Message 
Specify whether the Message Queue task sends or receive messages. If you select Send message, the Send 
page is listed in the left pane of the dialog box; if you select Receive message, the Receive page is listed. By 


default, this value is set to Send message. 


Message Queue Task Editor (Send Page) 


Use the Send page of the Message Queue Task Editor dialog box to configure a Message Queue task to send 
messages from a Microsoft SQL Server Integration Services package. 


Options 
UseEncryption 
Indicate whether to encrypt the message. The default is False. 


EncryptionAlgorithm 
If you choose to use encryption, specify the name of the encryption algorithm to use. The Message Queue task 
can use the RC2 and RC4 algorithms. The default is RC2. 





NOTE 

The RC4 algorithm is only supported for backward compatibility. New material can only be encrypted using RC4 or 
RC4_128 when the database is in compatibility level 90 or 100. (Not recommended.) Use a newer algorithm such as one 
of the AES algorithms instead. In the current release of SQL Server, material encrypted using RC4 or RC4_128 can be 
decrypted in any compatibility level. 


IMPORTANT 

These are the encryption algorithms that the Message Queuing (also known as MSMQ) technology supports. Both of 
these encryption algorithms are now considered cryptographically weak compared to newer algorithms, which Message 
Queuing does not yet support. Therefore, you should consider your cryptography needs carefully when sending 


messages using the Message Queue task. 





Messagelype 
Select the message type. This property has the options listed in the following table. 


VALUE DESCRIPTION 


Data file message The message is stored in a file. Selecting the value displays 
the dynamic option, DataFileMessage. 


Variable message The message is stored in a variable. Selecting the value 
displays the dynamic option, VariableMessage. 


String message The message is stored in the Message Queue task. Selecting 
the value displays the dynamic option, StringMessage. 


MessageType Dynamic Options 

MessageType = Data file message 

DataFileMessage 

Type the path of the data file, or click the ellipsis (...) and then locate the file. 


MessageType = Variable message 
VariableMessage 
Type the variable names, or click the ellipsis (...) and then select the variables. Variables are separated by 


commas. 


Related Topics: Select Variables 





MessageType = String message 

StringMessage 

Type the string message, or click the ellipsis (...) and then type the message in the Enter String Message 
dialog box. 


Message Queue Task Editor (Receive Page) 


Use the Receive page of the Message Queue Task Editor dialog box to configure a Message Queue task to 
receive Microsoft Message Queuing (MSMQ) messages. 


Options 
RemoveFromMessageQueue 
Indicate whether to remove the message from the queue after it is received. By default, this value is set to False. 


ErrorlfMessageTimeOut 
Indicate whether the task fails when the message times out, displaying an error message. The default is False. 


TimeoutAfter 
If you choose to display an error message on task failure, specify the number of seconds to wait before 


displaying the time-out message. 


Messagelype 
Select the message type. This property has the options listed in the following table. 


VALUE DESCRIPTION 


Data file message The message is stored in a file. Selecting the value displays 
the dynamic option, DataFileMessage. 


Variable message The message is stored in a variable. Selecting the value 
displays the dynamic option, VariableMessage. 


String message The message is stored in the Message Queue task. Selecting 
the value displays the dynamic option, StringMessage. 


String message to variable The message 


Selecting the value displays the dynamic option, 
StringMessage. 


MessageType Dynamic Options 

MessageType = Data file message 

SaveFileAs 

Type the path of the file to use, or click the ellipsis button (...) and then locate the file. 


Overwrite 
Indicate whether to overwrite the data in an existing file when saving the contents of a data file message. The 
default is False. 


Filter 
Specify whether to apply a filter to the message. This property has the options listed in the following table. 


VALUE DESCRIPTION 


No filter The task does not filter messages. Selecting the value 
displays the dynamic option, IdentifierReadOnly. 


VALUE DESCRIPTION 


From package The message receives only messages from the specified 
package. Selecting the value displays the dynamic option, 
Identifier. 


Filter Dynamic Options 


Filter = No filter 

IdentifierReadOnly 

This option is read-only. It may be blank or contain the GUID of a package when the Filter property was 
previously set. 

Filter = From package 

Identifier 

If you choose to apply a filter, type the unique identifier of the package from which messages can be received, or 
click the ellipsis button (...) and then specify the package. 


Related Topics: Select a Package 


MessageType = Variable message 
Filter 
Specify whether to apply a filter to messages. This property has the options listed in the following table. 


VALUE DESCRIPTION 


No filter The task does not filter messages. Selecting the value 
displays the dynamic option, IdentifierReadOnly. 


From package The message receives only messages from the specified 
package. Selecting the value displays the dynamic option, 
Identifier. 
Variable 


Type the variable name, or click <New variable...> and then configure a new variable. 


Related Topics: Add Variable 


Filter Dynamic Options 


Filter = No filter 


IdentifierReadOnly 
This option is blank. 


Filter = From package 

Identifier 

If you choose to apply a filter, type the unique identifier of the package from which messages can be received, or 
click the ellipsis button (...) and then specify the package. 


Related Topics: Select a Package 


MessageType = String message 
Compare 


Specify whether to apply a filter to messages. This property has the options listed in the following table. 
VALUE DESCRIPTION 


None Messages are not compared. 


VALUE DESCRIPTION 


Exact match Messages must match exactly the string in the 
CompareString option. 


Ignore case Message must match the string in the CompareString 
option, but the comparison is not case sensitive. 


Containing Message must contain the string in the CompareString 
option. 


CompareString 
Unless the Compare option is set to None, provide the string to which the message is compared. 


MessageType = String message to variable 
Compare 


Specify whether to apply a filter to messages. This property has the options listed in the following table. 


VALUE DESCRIPTION 
None Messages are not compared. 
Exact match The message must match exactly the string in the 


CompareString option. 


Ignore case The message must match the string in the CompareString 
option but the comparison is not case sensitive. 


Containing The message must contain the string in the 
CompareString option. 


CompareString 
Unless the Compare option is set to None, provide the string to which the message is compared. 


Variable 
Type the name of the variable to hold the received message, or click <New variable...> and then configure a 
new variable. 


Related Topics: Add Variable 


Select Variables 


Use the Select Variables dialog box to specify the variables to use in a send message operation in the Message 
Queue task. The Available Variables list includes system and user-defined variables that are in the scope of 
the Message Queue task or its parent container. The task uses the variables in the Selected Variables list. 


Options 
Available Variables 
Select one or more variables. 


Selected Variables 
Select one or more variables. 


Right Arrows 
Move selected variables to the Selected Variables list. 


Left Arrows 


Move selected variables back to the Available Variables list. 


New Variable 
Create a new variable. 


Related Topics: Add Variable 


See Also 


Integration Services Tasks 
Control Flow 


Message Queue Task 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


The Message Queue task allows you to use Message Queuing (also known as MSMQ) to send and receive 
messages between SQL Server Integration Services packages, or to send messages to an application queue that 
is processed by a custom application. These messages can take the form of simple text, files, or variables and 
their values. 


By using the Message Queue task, you can coordinate operations throughout your enterprise. Messages can be 
queued and delivered later if the destination is unavailable or busy; for example, the task can queue messages 
for the offline laptop computer of sales representatives, who receive their messages when they connect to the 
network. You can use the Message Queue task for the following purposes: 


e Delaying task execution until other packages check in. For example, after nightly maintenance at each of 
your retail sites, a Message Queue task sends a message to your corporate computer. A package running 
on the corporate computer contains Message Queue tasks, each waiting for a message from a particular 
retail site. When a message from a site arrives, a task uploads data from that site. After all the sites have 
checked in, the package computes summary totals. 


e Sending data files to the computer that processes them. For example, the output from a restaurant cash 
register can be sent in a data file message to the corporate payroll system, where data about each 
waiter's tips is extracted. 


e Distributing files throughout your enterprise. For example, a package can use a Message Queue task to 
send a package file to another computer. A package running on the destination computer then uses a 
Message Queue task to retrieve and save the package locally. 


When sending or receiving messages, the Message Queue task uses one of four message types: data file, string, 
string message to variable, or variable. The string message to variable message type can be used only when 
receiving messages. 


The task uses an MSMQ connection manager to connect to a message queue. For more information, see MSMQ 
Connection Manager. For more information about Message Queuing, see the MSDN Library. 


The Message Queue task requires that the Integration Services service be installed. Some SQL Server 
components that you may select for installation on the Components to Install page or the Feature 
Selection page of the SQL Server Installation Wizard install a partial subset of Integration Services 
components. These components are useful for specific tasks, but the functionality of Integration Services will be 
limited. For example, the SQL Server Data Tools (SSDT) option installs the Integration Services components 
required to design a package, but the Integration Services service is not installed, and therefore the Message 
Queue task is not functional. To ensure a complete installation of Integration Services, you must select 
Integration Services on the Components to Install page. For more information about installing and running 
the Message Queue task, see Install Integration Services. 


NOTE 


The Message Queue task fails to comply with Federal Information Processing Standard (FIPS) 140-2 when the computer's 
operating system is configured in FIPS mode and the task uses encryption. If the Message Queue task does not use 
encryption, the task can run successfully. 











Message Types 


You can configure the message types that the Message Queue task provides in the following ways: 


e Data file message specifies that a file contains the message. When receiving messages, you can 
configure the task to save the file, overwrite an existing file, and specify the package from which the task 


can receive messages. 


e String message specifies the message as a string. When receiving messages, you can configure the task 
to compare the received string with a user-defined string and take action depending on the comparison. 


String comparison can be exact, case-sensitive or case-insensitive, or use a substring. 


e String message to variable specifies the source message as a string that is sent to a destination 
variable. You can configure the task to compare the received string with a user-defined string using an 
exact, case-insensitive, or substring comparison. This message type is available only when the task is 


receiving messages. 


e Variable specifies that the message contains one or more variables. You can configure the task to specify 
the names of the variables included in the message. When receiving messages, you can configure the 
task to specify both the package from which it can receive messages and the variable that is the 
destination of the message. 


Sending Messages 


When configuring the Message Queue task to send messages, you can use one of the encryption algorithms 
that are currently supported by the Message Queuing technology, RC2 and RC4, to encrypt the message. Both 
of these encryption algorithms are now considered cryptographically weak compared to newer algorithms, 
which Message Queuing technology do not yet support. Therefore, you should consider your cryptography 
needs carefully when sending messages using the Message Queue task. 


Receiving Messages 


When receiving messages, the Message Queue task can be configured in the following ways: 
e Bypassing the message, or removing the message from the queue. 

@ Specifying a time-out. 

e Failing if a time-out occurs. 

e Overwriting an existing file, if the message is stored in a Data file. 


e Saving the message file to a different file name, if the message uses the Data file message type. 


Custom Logging Messages Available on the Message Queue Task 


The following table lists the custom log entries for the Message Queue task. For more information, see 
Integration Services (SSIS) Logging. 


LOG ENTRY DESCRIPTION 
MSMQAfterOpen Indicates that the task finished opening the message queue. 
MSMQBeforeOpen Indicates that the task began to open the message queue. 


MSMQBeginReceive Indicates that the task began to receive a message. 


LOG ENTRY DESCRIPTION 


MSMQBeginSend Indicates that the task began to send a message. 
MSMQEndReceive Indicates that the task finished receiving a message. 
MSMQEndSend Indicates that the task finished sending a message. 
MSMAQtTaskInfo Provides descriptive information about the task. 
MSMQTaskTimeOut Indicates that the task timed out. 


Configuration of the Message Queue Task 


You can set properties through SSIS Designer or programmatically. For information about the properties that 
you can set in SSIS Designer, click the following topic: 


e Expressions Page 


For information about programmatically setting these properties, see the documentation for the 
Microsoft.SqlServer.Dts.Tasks.MessageQueuelask.MessageQueuelask class in the Developer Guide. 


Related Tasks 


For more information about how to set these properties in SSIS Designer, see Set the Properties of a Task or 


Container. 


Message Queue Task Editor (General Page) 


Use the General page of the Message Queue Task Editor dialog box to name and describe the Message 
Queue task, to specify the message format, and to indicate whether the task sends or receives messages. 


Options 


Name 


Provide a unique name for the Message Queue task. This name is used as the label in the task icon. 





NOTE 


Task names must be unique within a package. 





Description 
Type a description of the Message Queue task. 


Use2000Format 
Indicate whether to use the 2000 format of Message Queuing (also known as MSMQ). The default is False. 


MSMQConnection 
Select an existing MSMQ connection manager or click <New connection...> to create a new connection 


manager. 
Related Topics: MSMQ Connection Manager, MSMQ Connection Manager Editor 


Message 
Specify whether the Message Queue task sends or receive messages. If you select Send message, the Send 
page is listed in the left pane of the dialog box; if you select Receive message, the Receive page is listed. By 


default, this value is set to Send message. 


Message Queue Task Editor (Send Page) 


Use the Send page of the Message Queue Task Editor dialog box to configure a Message Queue task to send 
messages from a Microsoft SQL Server Integration Services package. 


Options 
UseEncryption 
Indicate whether to encrypt the message. The default is False. 


EncryptionAlgorithm 
If you choose to use encryption, specify the name of the encryption algorithm to use. The Message Queue task 
can use the RC2 and RC4 algorithms. The default is RC2. 





NOTE 

The RC4 algorithm is only supported for backward compatibility. New material can only be encrypted using RC4 or 
RC4_128 when the database is in compatibility level 90 or 100. (Not recommended.) Use a newer algorithm such as one 
of the AES algorithms instead. In the current release of SQL Server, material encrypted using RC4 or RC4_128 can be 
decrypted in any compatibility level. 


IMPORTANT 

These are the encryption algorithms that the Message Queuing (also known as MSMQ) technology supports. Both of 
these encryption algorithms are now considered cryptographically weak compared to newer algorithms, which Message 
Queuing does not yet support. Therefore, you should consider your cryptography needs carefully when sending 


messages using the Message Queue task. 





Messagelype 
Select the message type. This property has the options listed in the following table. 


VALUE DESCRIPTION 


Data file message The message is stored in a file. Selecting the value displays 
the dynamic option, DataFileMessage. 


Variable message The message is stored in a variable. Selecting the value 
displays the dynamic option, VariableMessage. 


String message The message is stored in the Message Queue task. Selecting 
the value displays the dynamic option, StringMessage. 


MessageType Dynamic Options 

MessageType = Data file message 

DataFileMessage 

Type the path of the data file, or click the ellipsis (...) and then locate the file. 


MessageType = Variable message 
VariableMessage 
Type the variable names, or click the ellipsis (...) and then select the variables. Variables are separated by 


commas. 


Related Topics: Select Variables 





MessageType = String message 

StringMessage 

Type the string message, or click the ellipsis (...) and then type the message in the Enter String Message 
dialog box. 


Message Queue Task Editor (Receive Page) 


Use the Receive page of the Message Queue Task Editor dialog box to configure a Message Queue task to 
receive Microsoft Message Queuing (MSMQ) messages. 


Options 
RemoveFromMessageQueue 
Indicate whether to remove the message from the queue after it is received. By default, this value is set to False. 


ErrorlfMessageTimeOut 
Indicate whether the task fails when the message times out, displaying an error message. The default is False. 


TimeoutAfter 
If you choose to display an error message on task failure, specify the number of seconds to wait before 


displaying the time-out message. 


Messagelype 
Select the message type. This property has the options listed in the following table. 


VALUE DESCRIPTION 


Data file message The message is stored in a file. Selecting the value displays 
the dynamic option, DataFileMessage. 


Variable message The message is stored in a variable. Selecting the value 
displays the dynamic option, VariableMessage. 


String message The message is stored in the Message Queue task. Selecting 
the value displays the dynamic option, StringMessage. 


String message to variable The message 


Selecting the value displays the dynamic option, 
StringMessage. 


MessageType Dynamic Options 

MessageType = Data file message 

SaveFileAs 

Type the path of the file to use, or click the ellipsis button (...) and then locate the file. 


Overwrite 
Indicate whether to overwrite the data in an existing file when saving the contents of a data file message. The 
default is False. 


Filter 
Specify whether to apply a filter to the message. This property has the options listed in the following table. 


VALUE DESCRIPTION 


No filter The task does not filter messages. Selecting the value 
displays the dynamic option, IdentifierReadOnly. 


VALUE DESCRIPTION 


From package The message receives only messages from the specified 
package. Selecting the value displays the dynamic option, 
Identifier. 


Filter Dynamic Options 


Filter = No filter 

IdentifierReadOnly 

This option is read-only. It may be blank or contain the GUID of a package when the Filter property was 
previously set. 

Filter = From package 

Identifier 

If you choose to apply a filter, type the unique identifier of the package from which messages can be received, or 
click the ellipsis button (...) and then specify the package. 


Related Topics: Select a Package 


MessageType = Variable message 
Filter 
Specify whether to apply a filter to messages. This property has the options listed in the following table. 


VALUE DESCRIPTION 


No filter The task does not filter messages. Selecting the value 
displays the dynamic option, IdentifierReadOnly. 


From package The message receives only messages from the specified 
package. Selecting the value displays the dynamic option, 
Identifier. 
Variable 


Type the variable name, or click <New variable...> and then configure a new variable. 


Related Topics: Add Variable 


Filter Dynamic Options 


Filter = No filter 


IdentifierReadOnly 
This option is blank. 


Filter = From package 

Identifier 

If you choose to apply a filter, type the unique identifier of the package from which messages can be received, or 
click the ellipsis button (...) and then specify the package. 


Related Topics: Select a Package 


MessageType = String message 
Compare 


Specify whether to apply a filter to messages. This property has the options listed in the following table. 
VALUE DESCRIPTION 


None Messages are not compared. 


VALUE DESCRIPTION 


Exact match Messages must match exactly the string in the 
CompareString option. 


Ignore case Message must match the string in the CompareString 
option, but the comparison is not case sensitive. 


Containing Message must contain the string in the CompareString 
option. 


CompareString 
Unless the Compare option is set to None, provide the string to which the message is compared. 


MessageType = String message to variable 
Compare 


Specify whether to apply a filter to messages. This property has the options listed in the following table. 


VALUE DESCRIPTION 
None Messages are not compared. 
Exact match The message must match exactly the string in the 


CompareString option. 


Ignore case The message must match the string in the CompareString 
option but the comparison is not case sensitive. 


Containing The message must contain the string in the 
CompareString option. 


CompareString 
Unless the Compare option is set to None, provide the string to which the message is compared. 


Variable 
Type the name of the variable to hold the received message, or click <New variable...> and then configure a 
new variable. 


Related Topics: Add Variable 


Select Variables 


Use the Select Variables dialog box to specify the variables to use in a send message operation in the Message 
Queue task. The Available Variables list includes system and user-defined variables that are in the scope of 
the Message Queue task or its parent container. The task uses the variables in the Selected Variables list. 


Options 
Available Variables 
Select one or more variables. 


Selected Variables 
Select one or more variables. 


Right Arrows 
Move selected variables to the Selected Variables list. 


Left Arrows 


Move selected variables back to the Available Variables list. 


New Variable 
Create a new variable. 


Related Topics: Add Variable 


See Also 


Integration Services Tasks 
Control Flow 


Select a Package 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Use the Select a Package dialog box to specify the package from which the Message Queue task can receive 
messages. 


Static Options 
Location 


Specify the location of the package. This property has the options listed in the following table. 


VALUE DESCRIPTION 


SQL Server Set the location to an instance of SQL Server. Selecting this 
value displays the dynamic options, Server, Use Windows 
Authentication, Use SQL Server Authentication, User 
name, and Password. 


DTSX file Set the location to a DTSX file. Selecting this value displays 
the dynamic option, File name. 


Location Dynamic Options 


Location = SQL Server 


Package name 
Select a package that is stored on the specified server. 


Server 


Provide a server name or select a server from the list. 


Use Windows Authentication 
Click to use Windows Authentication. 


Use SQL Server Authentication 
Click to use SQL Server Authentication. 


User name 


If using SQL Server Authentication, provide a user name to use when logging on to the server. 


Password 


If using SQL Server Authentication, provide a password. 


Location = DTSX file 


File name 
Provide the path of a package or click the browse button (...) and locate the package. 


See Also 


Message Queue Task 
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Applies to: Q@ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


The Notify Operator task sends notification messages to SQL Server Agent operators. A SQL Server Agent 
operator is an alias for a person or group that can receive electronic notifications. For more information about 
SQL Server operators, see Operators. 


By using the Notify Operator task, a package can notify one or more operators via e-mail, pager, or net send. 
Each operator can be notified by different methods. For example, OperatorA is notified by e-mail and pager, and 
OperatorB is notified by pager and net send. The operators who receive notifications from the task must be 
members of the OperatorNotify collection on the Notify Operator task. 


The Notify Operator task is the only database maintenance task that does not encapsulate a Transact-SQL 
statement or a DBCC command. 


Configuration of the Notify Operator Task 


You can set properties through SSIS Designer. This task is in the Maintenance Plan Tasks section of the 
Toolbox in SSIS Designer. 


For more information about the properties that you can set in SSIS Designer, click the following topic: 


e Notify Operator Task (Maintenance Plan) 


For more information about how to set these properties in SSIS Designer, click the following topic: 


e Set the Properties of a Task or Container 


Rebuild Index Task 
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The Rebuild Index task rebuilds indexes in SQL Server database tables and views. For more information about 
managing indexes, see Reorganize and Rebuild Indexes. 


By using the Rebuild Index task, a package can rebuild indexes in a single database or multiple databases. If the 
task rebuilds only the indexes in a single database, you can choose the views and tables whose indexes the task 
rebuilds. 


This task encapsulates an ALTER INDEX REBUILD statement with the following index rebuild options: 
e Specify a FILLFACTOR percentage or use the original FILLFACTOR amount. 


e Set SORT_IN_TEMPDB = ON to store the intermediate sort result used to rebuild the index in tempdb. 
When the intermediate sort result is set to OFF, the result is stored in the same database as the index. 


e Set PAD_INDEX = ON to allocate the free space specified by FILLFACTOR to the intermediate-level pages 
of the index. 


e Set IGNORE_DUP_KEY = ON to allow a multirow insert operation that includes records that violate 
unique constraints to insert the records that do not violate the unique constraints. 


e Set ONLINE = ON to not hold table locks so that queries or updates to the underlying table can proceed 
during re-indexing. 





NOTE 


Online index operations are not available in every edition of MicrosoftSQL Server. For a list of features that are 
supported by the editions of SQL Server, see Features Supported by the Editions of SQL Server 2016. 








e Specify a value for MAXDOP to limit the number of processors used in a parallel plan execution. 


e Specify WAIT_AT_LOW_PRIORITY, MAX_DURATION, and ABORT_AFTER_WAIT to control how long the 
index operation waits for low priority locks. 


For more information about the ALTER INDEX statement and index rebuild options, see ALTER INDEX (Transact- 
SQL). 


IMPORTANT 


The time the task takes to create the Transact-SQL statement that the task runs is proportionate to the number of 
indexes the task rebuilds. If the task is configured to rebuild indexes in all the tables and views in a database with a large 
number of indexes, or to rebuild indexes in multiple databases, the task can take a considerable amount of time to 
generate the Transact-SQL statement. 











Configuration of the Rebuild Index Task 


You can set properties through SSIS Designer. This task is in the Maintenance Plan Tasks section of the 
Toolbox in SSIS Designer. 


For more information about the properties that you can set in SSIS Designer, click the following topic: 


Rebuild Index Task (Maintenance Plan) 


Related Tasks 


For more about how to set these properties in SSIS Designer, see Set the Properties of a Task or Container. 


See Also 


Integration Services Tasks 
Control Flow 


Reorganize Index Task 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


The Reorganize Index task reorganizes indexes in SQL Server database tables and views. For more information 
about managing indexes, see Reorganize and Rebuild Indexes. 


By using the Reorganize Index task, a package can reorganize indexes in a single database or multiple databases. 
If the task reorganizes only the indexes in a single database, you can choose the views or the tables whose 
indexes the task reorganizes. The Reorganize Index task also includes an option to compact large object data. 
Large object data is data with the image, text, ntext, varchar(max), nvarchar(max), varbinary(max), or xml 
data type. For more information, see Data Types (Transact-SQL). 


The Reorganize Index task encapsulates the Transact-SQL ALTER INDEX statement. If you choose to compact 
large object data, the statement uses the REORGANIZE WITH (LOB_COMPACTION = ON) clause, otherwise 
LOB_COMPACTION is set to OFF. For more information, see ALTER INDEX (Transact-SQL). 


IMPORTANT 


The time the task takes to create the Transact-SQL statement that the task runs is proportionate to the number of 
indexes the task reorganizes. If the task is configured to reorganize indexes in all the tables and views in a database that 
holds a large number of indexes, or to reorganize indexes in multiple databases, the task can take a considerable amount 


of time to generate the Transact-SQL statement. 








Configuration of the Reorganize Index Task 


You can set properties through SSIS Designer. This task is in the Maintenance Plan Tasks section of the 
Toolbox in SSIS Designer. 


For information about the properties that you can set in SSIS Designer, click the following topic: 


e@ Reorganize Index Task (Maintenance Plan) 


Related Tasks 


For more information about how to set these properties in SSIS Designer, see Set the Properties of a Task or 
Container. 


See Also 


Integration Services Tasks 
Control Flow 


Script Task 
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The Script task provides code to perform functions that are not available in the built-in tasks and 
transformations that SQL Server Integration Services provides. The Script task can also combine functions in 
one script instead of using multiple tasks and transformations. You use the Script task for work that must be 
done once in a package (or once per enumerated object), instead than once per data row. 


You can use the Script task for the following purposes: 


e Access data by using other technologies that are not supported by built-in connection types. For example, 
a script can use Active Directory Service Interfaces (ADSI) to access and extract user names from Active 
Directory. 


e Create a package-specific performance counter. For example, a script can create a performance counter 
that is updated while a complex or poorly performing task runs. 


e Identify whether specified files are empty or how many rows they contain, and then based on that 
information affect the control flow in a package. For example, if a file contains zero rows, the value of a 
variable set to 0, and a precedence constraint that evaluates the value prevents a File System task from 
copying the file. 


If you have to use the script to do the same work for each row of data in a set, you should use the Script 
component instead of the Script task. For example, if you want to assess the reasonableness of a postage 
amount and skip data rows that have very high or low amounts, you would use a Script component. For more 
information, see Script Component. 


If more than one package uses a script, consider writing a custom task instead of using the Script task. For more 
information, see Developing a Custom Task. 


After you decide that the Script task is the appropriate choice for your package, you have to both develop the 
script that the task uses and configure the task itself. 


Writing and Running the Script that the Task Uses 


The Script task uses Microsoft Visual Studio Tools for Applications (VSTA) as the environment in which you write 
the scripts and the engine that runs those scripts. 


VSTA provides all the standard features of the Visual Studio environment, such as the color-coded Visual Studio 
editor, Intellisense, and Object Explorer. VSTA also uses the same debugger that other Microsoft development 
tools use. Breakpoints in the script work seamlessly with breakpoints on Integration Services tasks and 
containers. VSTA supports both the Microsoft Visual Basic and Microsoft Visual C# programming languages. 


To run a script, you must have VSTA installed on the computer where the package runs. When the package runs, 
the task loads the script engine and runs the script. You can access external .NET assemblies in scripts by adding 
references to the assemblies in the project. Currently we dont support .NET Core and .NET standard assembly 
references. 





NOTE 
Unlike earlier versions where you could indicate whether the scripts were precompiled, all scripts are precompiled in SQL 
Server 2008 Integration Services (SSIS) and later versions. When a script is precompiled, the language engine is not 


loaded at run time and the package runs more quickly. However, precompiled binary files consume significant disk space. 





Configuring the Script Task 
You can configure the Script task in the following ways: 
e Provide the custom script that the task runs. 


e Specify the method in the VSTA project that the Integration Services runtime calls as the entry point into 
the Script task code. 


e Specify the script language. 
e@ Optionally, provide lists of read-only and read/write variables for use in the script. 
You can set these properties through SSIS Designer or programmatically. 


Configuring the Script Task in the Designer 


The following table describes the ScriptTaskLogEntry event that can be logged for Script task. The 
ScriptTaskLogEntry event is selected for logging on the Details tab of the Configure SSIS Logs dialog box. 
For more information, see Integration Services (SSIS) Logging. 


LOG ENTRY DESCRIPTION 


ScriptTaskLogEntry Reports the results of implementing logging in the script. 
The task writes a log entry for each call to the Log method 
of the Dts object. The task writes these entries when the 
code is run. For more information, see Logging in the Script 
Task. 


For more information about the properties that you can set in SSIS Designer, see the following topics: 
e@ Script Task Editor (General Page) 

e Script Task Editor (Script Page) 

e Expressions Page 

For more information about how to set these properties in SSIS Designer, see the following topic: 

e Set the Properties of a Task or Container 


Configuring the Script Task Programmatically 


For more information about programmatically setting these properties, see the following topic: 


@ ScriptTask 


Script Task Editor (General Page) 


Use the General page of the Script Task Editor dialog box to name and describe the Script task. 


To learn more about the Script task, see Script Task and Configuring the Script Task in the Script Task Editor. To 
learn about programming the Script task, see Extending the Package with the Script Task. 


Options 





Name 
Provide a unique name for the Script task. This name is used as the label in the task icon. 





NOTE 


Task names must be unique within a package. 





Description 


Type a description of the Script task. 


Script Task Editor (Script Page) 


Use the Script page of the Script Task Editor dialog box to set script properties and specify variables that can 
be accessed by the script. 





NOTE 


In SQL Server 2008 Integration Services (SSIS) and later versions, all scripts are precompiled. In earlier versions, you set a 
PrecompileScriptIntoBinaryCode property to specify that the script was precompiled. 











To learn more about the Script task, see Script Task and Configuring the Script Task in the Script Task Editor. To 
learn about programming the Script task, see Extending the Package with the Script Task. 


Options 
ScriptLanguage 
Select the scripting language for the task, either Microsoft Visual Basic or Microsoft Visual C#. 


After you have created a script for the task, you cannot change the value of the ScriptLanguage property. 


To set the default scripting language for the Script task, use the Scripting language option on General page 
of the Options dialog box. For more information, see General Page. 


EntryPoint 

Specify the method that the Integration Services runtime calls as the entry point into the code of the Script task. 
The specified method must be in the ScriptMain class of the Microsoft Visual Studio Tools for Applications 
(VSTA) project The ScriptMain class is the default class generated by the script templates. 


If you change the name of the method in the VSTA project, you must change the value of the EntryPoint 
property. 


ReadOnlyVariables 
Type a comma-separated list of read-only variables that are available to the script, or click the ellipsis (...) button 
and select the variables in the Select variables dialog box. 





NOTE 


Variable names are case sensitive. 











ReadWriteVariables 
Type a comma-separated list of read/write variables that are available to the script, or click the ellipsis (...) button 
and select the variables in the Select variables dialog box. 





NOTE 


Variable names are case sensitive. 





Edit Script 


Opens the VSTA IDE where you can create or modify the script. 


Related Content 


@ Technical article, How to send email with delivery notification in C#, on shareourideas.com 


Select Variables Page 
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Use the Select variables dialog box to select one or more variables for the ReadOnlyVariables and 
ReadWriteVariables properties when you configure a Script task or a Script component. 


To open the Select Variables dialog box, on the Script page of the Script Transformation Editor dialog box, 
under Custom Properties, locate either the ReadOnlyVariables or ReadWriteVariables property, and then 
click the ellipsis (...) button associated with that property. 


Options 


Select box 
Selects a specific variable, selects all the variables, or clears the selection of all variables. 


Name 
Specifies the name of a variable. 


Type 


Specifies the data type of a variable. 


See Also 


Script Task Editor (Script Page) 


Send Mail Task 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


The Send Mail task sends an e-mail message. By using the Send Mail task, a package can send messages if tasks 
in the package workflow succeed or fail, or send messages in response to an event that the package raises at run 
time. For example, the task can notify a database administrator about the success or failure of the Backup 
Database task. 


You can configure the Send Mail task in the following ways: 
e Provide the message text for the e-mail message. 
e Provide a subject line for the e-mail message. 


e Set the priority level of the message. The task supports three priority levels: normal, low, and high. 


e Specify the recipients on the To, Cc, and Bcc lines. If the task specifies multiple recipients, they are 
separated by semicolons. 





NOTE 


The To, Cc, and Bcc lines are limited to 256 characters each in accordance with Internet standards. 





e Include attachments. If the task specifies multiple attachments, they are separated by the pipe (|) 
character. 





NOTE 


If an attachment file does not exist when the package runs, an error occurs. 





e@ Specify the SMTP connection manager to use. 





IMPORTANT 


The SMTP connection manager supports only anonymous authentication and Windows Authentication. It does 
not support basic authentication. 








The message text can be a string that you provide, a connection to a file that contains the text, or the name of a 
variable that contains the text. The task uses a File connection manager to connect to a file. For more 
information, see Flat File Connection Manager. 


The task uses an SMTP connection manager to connect to a mail server. For more information, see SMTP 
Connection Manager. 


Custom Logging Messages Available on the Send Mail Task 


The following table lists the custom log entries for the Send Mail task. For more information, see Integration 
Services (SSIS) Logging. 


LOG ENTRY DESCRIPTION 


SendMailTaskBegin Indicates that the task began to send an e-mail message. 
SendMailTaskEnd Indicates that the task finished sending an e-mail message. 
SendMailTaskInfo Provides descriptive information about the task. 


Configuring the Send Mail Task 

You can set properties through SSIS Designer or programmatically. 

For information about the properties that you can set in SSIS Designer, click the following topic: 
e Expressions Page 

For information about programmatically setting these properties, click the following topic: 


e SendMailTask 


Related Tasks 


For information about how to set these properties in SSIS Designer, click Set the Properties of a Task or 


Container. 


Related Content 


@ Technical article, How to send email with delivery notification in C#, on shareourideas.com 


Send Mail Task Editor (General Page) 


Use the General page of the Send Mail Task Editor dialog box to name and describe the Send Mail task. 


Options 
Name 
Provide a unique name for the Send Mail task. This name is used as the label in the task icon. 


Note Task names must be unique within a package. 


Description 
Type a description of the Send Mail task. 


Send Mail Task Editor (Mail Page) 


Use the Mail page of the Send Mail Task Editor dialog box to specify recipients, message type, and priority for 
a message. You can also attach files to the message. The message text can be a string you provide, a file 
connection to a file that contains the text, or the name of a variable that contains the text. 


Options 
SMTPConnection 
Select an SMTP connection manager in the list, or click <New connection...> to create a new connection 


Manager. 





IMPORTANT 


The SMTP connection manager supports only anonymous authentication and Windows Authentication. It does not 


support basic authentication. 











Related Topics: SMTP Connection Manager 


From 


Specify the e-mail address of the sender. 


To 
Provide the e-mail addresses of the recipients, delimited by semicolons. 


Cc 
Specify the e-mail addresses, delimited by semicolons, of individuals who also receive copies of the message. 


Bcc 
Specify the e-mail addresses, delimited by semicolons, of individuals who receive blind carbon copies (Bcc) 
copies of the message. 


Subject 
Provide a subject for the e-mail message. 


MessageSourceType 
Select the source type of the message. This property has the options listed in the following table. 


VALUE DESCRIPTION 


Direct input Set the source to the message text. Selecting this value 
displays the dynamic option, MessageSource. 


File connection Set the source to the file that contains the message text. 
Selecting this value displays the dynamic option, 
MessageSource. 
Variable Set the source to a variable that contains the message text. 
Selecting this value displays the dynamic option, 
MessageSource. 
Priority 


Set the priority of the message. 


Attachments 
Provide the file names of attachments to the e-mail message, delimited by the pipe (|) character. 





NOTE 


The To, Cc, and Bcc lines are limited to 256 characters in accordance with Internet standards. 











MessageSourceType Dynamic Options 

MessageSourceType = Direct Input 

MessageSource 

Type the message text or click the browse button (...) and then type the message in the Message source dialog 
box. 


MessageSourceType = File connection 


MessageSource 
Select a File connection manager in the list or click <New connection...> to create a new connection manager. 


Related Topics: File Connection Manager, File Connection Manager Editor 


MessageSourceType = Variable 
MessageSource 
Select a variable in the list or click <New variable...> to create a new variable. 


Related Topics: Integration Services (SSIS) Variables, Add Variable 


See Also 


Integration Services Tasks 
Control Flow 


Shrink Database Task 


11/23/2021 * 2 minutes to read « Edit Online 





Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 
The Shrink Database task reduces the size of SQL Server database data and log files. 
By using the Shrink Database task, a package can shrink files for a single database or multiple databases. 


Shrinking data files recovers space by moving pages of data from the end of the file to unoccupied space closer 
to the front of the file. When enough free space is created at the end of the file, data pages at end of the file can 
deallocated and returned to the file system. 





WARNING 


Data that is moved to shrink a file can be scattered to any available location in the file. This causes index fragmentation 
and can slow the performance of queries that search a range of the index. To eliminate the fragmentation, consider 
rebuilding the indexes on the file after shrinking. 








Commands 


The Shrink Database task encapsulates a DBCC SHRINKDATABASE command, including the following arguments 
and options: 


e database_name 
e target_percent 
e NOTRUNCATE or TRUNCATEONLY. 


If the Shrink Database task shrinks multiple databases, the task runs multiple SHRINKDATABASE commands, one 
for each database. All instances of the SHRINKDATABASE command use the same argument values, except for 
the database_name argument. For more information, see DBCC SHRINKDATABASE (Transact-SQL). 


Configuration of the Shrink Database Task 


You can set properties through the SSIS Designer. This task is in the Maintenance Plan Tasks section of the 
Toolbox in SSIS Designer. 


For more information about the properties that you can set in the SSIS Designer, click the following topic: 
e Shrink Database Task (Maintenance Plan) 
For more information about setting these properties in the SSIS Designer, click the following topic: 


e Set the Properties of a Task or Container 
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The Transfer Database task transfers a SQL Server database between two instances of SQL Server. In contrast to 
the other tasks that only transfer SQL Server objects by copying them, the Transfer Database task can either 
copy or move a database. This task can also be used to copy a database within the same server. 


Offline and Online Modes 


The database can be transferred by using online or offline mode. When you use online mode, the database 
remains attached and it is transferred by using SQL Management Object (SMO) to copy the database objects. 
When you use offline mode, the database is detached, the database files are copied or moved, and the database 
is attached at the destination after the transfer finishes successfully. If the database is copied, it is automatically 
reattached at the source if the copy is successful. In offline mode, the database is copied more quickly, but the 
database is unavailable to users during the transfer. 


Offline mode requires that you specify the network file shares on the source and destination servers that 
contain the database files. If the folder is shared and can be accessed by the user, you can reference the network 
share using the syntax \\computername\Program Files\myfolder\. Otherwise, you must use the syntax 
\\computername\c$\Program Files\myfolder\. To use the latter syntax, the user must have write access to the 
source and destination network shares. 


Transfer of Databases Between Versions of SQL Server 


The Transfer Database task can transfer a database between instances of different SQL Server versions. 


Events 


The Transfer Database task does not report incremental progress of the error message transfer; it reports only 
0% and 100 % completion. 


Execution Value 


The execution value, defined in the ExecutionValue property of the task, returns the value 1, because in 
contrast to other transfer tasks, the Transfer Database task can transfer only one database. 


By assigning a user-defined variable to the ExecValueVariable property of the Transfer Database task, 
information about the error message transfer can be made available to other objects in the package. For more 
information, see Integration Services (SSIS) Variables and Use Variables in Packages. 


Log Entries 

The Transfer Database task includes the following custom log entries: 

e SourceSQLServer This log entry lists the name of the source server. 

e@ DestSQLServer This log entry lists the name of the destination server. 


e SourceDB This log entry lists the name of the database that is transferred. 


In addition, a log entry for the OnInformation event is written when the destination database is overwritten. 


Security and Permissions 


To transfer a database using offline mode, the user who runs the package must be a member of the sysadmin 


server role. 


To transfer a database using online mode, the user who runs the package must be a member of the sysadmin 
server role or the database owner (dbo) of the selected database. 


Configuration of the Transfer Database Task 


You can specify whether the task tries to reattach the source database if the database transfer fails. 


The Transfer Database task can also be configured to permit overwriting a destination database that has the 
same name, replacing the destination database. 


The source database can also be renamed as part of the transfer process. If you want to transfer a database to a 
destination instance of SQL Server that already contains a database that has the same name, renaming the 
source database allows the database to be transferred. However, the database file names must also be different; 
if database files that have the same names already exist at the destination, the task fails. 


When you copy a database, the database cannot be smaller than the size of the model database on the 


destination server. You can either increase the size of the database to copy, or reduce the size of model. 


At run time, the Transfer Database task connects to the source and destination servers by using one or two SMO 
connection managers. When you create a copy of a database on the same server, only one SMO connection 
manager is required. The SMO connection managers are configured separately from the Transfer Database task, 
and then are referenced in the Transfer Database task. The SMO connection managers specify the server and the 
authentication mode to use when the task accesses the server. For more information, see SMO Connection 
Manager. 


You can set properties through SSIS Designer or programmatically. 

For more information about the properties that you can set in SSIS Designer, click the following topic: 
e Expressions Page 

For more information about how to set these properties in SSIS Designer, click the following topic: 


e Set the Properties of a Task or Container 


Programmatic Configuration of the Transfer Database Task 
For more information about programmatically setting these properties, click the following topic: 


e TransferDatabaseTask 


Transfer Database Task Editor (General Page) 


Use the General page of the Transfer Database Task Editor dialog box to name and describe the Transfer 
Database task. The Transfer Database task copies or moves a SQL Server database between two instances of 
SQL Server. This task can also be used to copy a database within the same server. 


Options 
Name 
Type a unique name for the Transfer Database task. This name is used as the label in the task icon. 





NOTE 


Task names must be unique within a package. 





Description 


Type a description of the Transfer Database task. 


Transfer Database Task Editor (Databases Page) 


Use the Databases page of the Transfer Database Task Editor dialog box to specify properties for the source 
and destination databases involved in the Transfer Database task. The Transfer Database task copies or moves a 
SQL Server database between two instances of SQL Server. This task can also be used to copy a database within 


the same server. 


Options 
SourceConnection 
Select a SMO connection manager in the list, or click <New connection...> to create a new connection to the 


source server. 


DestinationConnection 
Select a SMO connection manager in the list, or click <New connection...> to create a new connection to the 


destination server. 


DestinationDatabaseName 
Specify the name of the SQL Server database on the destination server. 


To automatically populate this field with the source database name, specify the SourceConnection and 
SourceDatabaseName first. 


To rename the database on the destination server, type the new name in this field. 


DestinationDatabaseFiles 
Specifies the names and locations of the database files on the destination server. 


To automatically populate this field with the source database file names and locations, specify the 
SourceConnection, SourceDatabaseName, and SourceDatabaseFiles first. 


To rename the database files or to specify the new locations on the destination server, populate this field with 
the source database information, and then click the browse button. In the Destination database files dialog 
box, edit the Destination File, Destination Folder, or Network File Share. 





NOTE 
If you locate the database files by using the browse button, the file location is entered using the local drive notation: for 
example, c:\. You must replace this with the network share notation, including the computer name and share name. If the 


default administrative share is used, you must use the $ notation, and have administrative access to the share. 











DestinationOverwrite 
Specify whether the database on the destination server can be overwritten. 


This property has the options listed in the following table: 
VALUE DESCRIPTION 


True Overwrite destination server database. 


VALUE DESCRIPTION 


False Do not overwrite destination server database. 


Caution 

The data in the destination server database will be overwritten if you specify True for DestinationOver write, 
which may result in data loss. To avoid this, back up the destination server database to another location before 
executing the Transfer Database task. 


Action 
Specify whether the task will Copy or Move the database to the destination server. 


Method 
Specify whether the task will be executed while the database on the source server is in online or offline mode. 


To transfer a database using offline mode, the user that runs the package must be a member of the sysadmin 
fixed server role. 


To transfer a database using the online mode, the user that runs the package must be a member of the 


sysadmin fixed server role, or the database owner (dbo) of the selected database. 


SourceDatabaseName 
Select the name of the database to be copied or moved. 


SourceDatabaseFiles 
Click the browse button to select the database files. 


ReattachSourceDatabase 
Specify whether the task will attempt to reattach the source database if a failure occurs. 


This property has the options listed in the following table: 


VALUE DESCRIPTION 
True Reattach source database. 
False Do not reattach source database. 


Source database files 


Use the Source Database Files dialog box to view the database file names and locations on the source server, 
or to specify a network file share location for the Transfer Database task. 


To populate this dialog box with the database file names and locations on the source server, specify the 
SourceConnection and SourceDatabaseName first in the Databases page of the Transfer Database Task 
Editor dialog box. 


Options 
Source File 


Database file names on the source server that will be transferred. Source File is read only. 


Source Folder 
Folder on the source server where the database files to be transferred reside. Source Folder is read only. 


Network File Share 
Network shared folder on the source server from where the database files will be transferred. Use Network 
File Share when you transfer a database in offline mode by specifying DatabaseOffline for Method in the 


Databases page of the Transfer Database Task Editor dialog box. 
Enter the network file share location, or click the browse button (...) to locate the network file share location. 


When you transfer a database in offline mode, the database files are copied to the Network file share location 
on the source server before they are transferred to the destination server. 


Destination Database Files 


Use the Destination Database Files dialog box to view or change the database file names and locations on 
the destination server, or to specify a network file location for the Transfer Database task. 


To automatically populate this dialog box with the database file names and locations on the source server, 
specify the SourceConnection, SourceDatabaseName, and SourceDatabaseFiles first in the Databases 
page of the Transfer Database Task Editor dialog box. 


Options 


Destination File 
Names of the transferred database files on the destination server. 


Enter the file name, or click the file name to edit it. 


Destination Folder 
Folder on the destination server where the database files will be transferred to. 


Enter the folder path, click the folder path to edit it, or click browse to locate the folder where you want to 


transfer the database files on the destination server. 


Network File Share 

Network shared folder on the destination server where the database files will be transferred to. Use Network 
file share when you transfer a database in offline mode by specifying DatabaseOffline for Method in the 
Databases page of the Transfer Database Task Editor dialog box. 


Enter the network file share location, or click browse to locate the network file share location. 


When you transfer a database in offline mode, the database files are copied to the Network file share location 
before they are transferred to the Destination folder location. 


Transfer Error Messages Task 
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The Transfer Error Messages task transfers one or more SQL Server user-defined error messages between 
instances of SQL Server. User-defined messages are messages with an identifier that is equal to or greater than 
50000. Messages with an identifier less than 50000 are system error messages, and cannot be transferred by 
using the Transfer Error Messages task. 


The Transfer Error Messages task can be configured to transfer all error messages, or only the specified error 
messages. User-defined error messages may be available in a number of different languages and the task can 
be configured to transfer only messages in selected languages. A us_english version of the message that uses 
code page 1033 must exist on the destination server before you can transfer other language versions of the 
message to that server. 


The sysmessages table in the master database contains all the error messages-both system and user-defined- 
that SQL Server uses. 


The user-defined messages to be transferred may already exist on the destination. An error message is defined 
as a duplicate error message if the identifier and the language are the same. The Transfer Error Messages task 
can be configured to handle existing error messages in the following ways: 


e Overwrite existing error messages. 
e Fail the task when duplicate messages exist. 
e Skip duplicate error messages. 


At run time, the Transfer Error Messages task connects to the source and destination servers by using one or 
two SMO connection managers. The SMO connection manager is configured separately from the Transfer Error 
Messages task, and then is referenced in the Transfer Error Messages task. The SMO connection manager 
specifies the server and the authentication mode to use when accessing the server. For more information, see 
SMO Connection Manager. 


The Transfer Error Messages task supports a SQL Server source and destination. There are no restrictions on 


which version to use as a source or destination. 


Events 


The task raises an information event that reports the number of error messages that have been transferred. 


The Transfer Error Messages task does not report incremental progress of the error message transfer; it reports 
only 0% and 100 % completion. 


Execution Value 


The execution value, defined in the ExecutionValue property of the task, returns the number of error messages 
that have been transferred. By assigning a user-defined variable to the ExecValueVariable property of the 
Transfer Error Message task, information about the error message transfer can be made available to other 
objects in the package. For more information, see Integration Services (SSIS) Variables and Use Variables in 
Packages. 


Log Entries 


The Transfer Error Messages task includes the following custom log entries: 


e TransferErrorMessagestTaskStartTransferringObjects This log entry reports that the transfer has started. 
The log entry includes the start time. 


@ TransferErrorMessagesTaskFinishedTransferringObjects This log entry reports that the transfer has 
finished. The log entry includes the end time. 


In addition, a log entry for the OnInformation event reports the number of error messages that were 
transferred, and a log entry for the OnWarning event is written for each error message on the destination that 


is overwritten. 


Security and Permissions 


To create new error messages, the user that runs the package must be a member of the sysadmin or 


serveradmin server role on the destination server. 


Configuration of the Transfer Error Messages Task 

You can set properties through SSIS Designer or programmatically. 

For more information about the properties that you can set in SSIS Designer, click the following topic: 
e Expressions Page 

For information about programmatically setting these properties, click the following topic: 


e TransferErrorMessages Task 


Related Tasks 


For more information about how to set these properties in SSIS Designer, click the following topic: 


e Set the Properties of a Task or Container 


Transfer Error Messages Task Editor (General Page) 


Use the General page of the Transfer Error Messages Task Editor dialog box to name and describe the 
Transfer Error Messages task. The Transfer Error Messages task transfers one or more SQL Server user-defined 


error messages between instances of SQL Server. 


Options 
Name 
Type a unique name for the Transfer Error Messages task. This name is used as the label in the task icon. 


NOTE 


Task names must be unique within a package. 





Description 
Type a description of the Transfer Error Messages task. 


Transfer Error Messages Task Editor (Messages Page) 


Use the Messages page of the Transfer Error Messages Task Editor dialog box to specify properties for 


copying one or more SQL Server user-defined error messages from one instance of SQL Server to another. 


Options 
SourceConnection 


Select a SMO connection manager in the list, or click <New connection...> to create a new connection to the 
source server. 


DestinationConnection 
Select a SMO connection manager in the list, or click <New connection...> to create a new connection to the 
destination server. 


IfObjectExists 
Select whether the task should overwrite existing user-defined error messages, skip existing messages, or fail if 
error messages of the same name already exist on the destination server. 


TransferAllErrorMessages 
Select whether the task should copy all or only the specified user-defined messages from the source server to 
the destination server. 


This property has the options listed in the following table: 


VALUE DESCRIPTION 
True Copy all user-defined messages. 
False Copy only the specified user-defined messages. 


ErrorMessagesList 


Click the browse button (...) to select the error messages to copy. 





NOTE 


You must specify the SourceConnection before you can select error messages to copy. 





ErrorMessageLanguagesList 

Click the browse button (...) to select the languages for which to copy user-defined error messages to the 
destination server. A us_english (code page 1033) version of the message must exist on the destination server 
before you can transfer other language versions of the message to that server. 





NOTE 


You must specify the SourceConnection before you can select error messages to copy. 





See Also 


Integration Services Tasks 
Control Flow 


Transfer Jobs Task 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 
The Transfer Jobs task transfers one or more SQL Server Agent jobs between instances of SQL Server. 


The Transfer Jobs task can be configured to transfer all jobs, or only specified jobs. You can also indicate whether 
the transferred jobs are enabled at the destination. 


The jobs to be transferred may already exist on the destination. The Transfer Jobs task can be configured to 
handle existing jobs in the following ways: 


e Overwrite existing jobs. 
e Fail the task when duplicate jobs exist. 
e Skip duplicate jobs. 


At run time, the Transfer Jobs task connects to the source and destination servers by using one or two SMO 
connection managers. The SMO connection manager is configured separately from the Transfer Jobs task, and 
then is referenced in the Transfer Jobs task. The SMO connection manager specifies the server and the 


authentication mode to use when accessing the server. For more information, see SMO Connection Manager. 


Transferring Jobs Between Instances of SQL Server 


The Transfer Jobs task supports a SQL Server source and destination. There are no restrictions on which version 
to use as a source or destination. 


Events 


The Transfer Jobs task raises an information event that reports the number of jobs transferred and a warning 
event when a job is overwritten. The task does not report incremental progress of the job transfer; it reports 
only 0% and 100% completion. 


Execution Value 


The execution value, defined in the ExecutionValue property of the task, returns the number of jobs that are 
transferred. By assigning a user-defined variable to the ExecValueVariable property of the Transfer Jobs task, 
information about the job transfer can be made available to other objects in the package. For more information, 
see Integration Services (SSIS) Variables and Use Variables in Packages. 


Log Entries 


The Transfer Jobs task includes the following custom log entries: 


e TransferJobsTaskStarTransferringObjects This log entry reports that the transfer has started. The log entry 
includes the start time. 


e TransferJobsTaskFinishedTransferringObjects This log entry reports that the transfer has finished. The log 
entry includes the end time. 


In addition, a log entry for the OnInformation event reports the number of jobs that were transferred and a 


log entry for the OnWarning event is written for each job on the destination that is overwritten. 


Security and Permissions 


To transfer jobs, the user must be a member of the sysadmin fixed server role or one of the fixed SQL Server 
Agent fixed database roles on the msdb database on the both the source and destination instances of SQL 
Server. 


Configuration of the Transfer Jobs Task 

You can set properties through SSIS Designer or programmatically. 

For information about the properties that you can set in SSIS Designer, click the following topic: 
e Expressions Page 

For information about programmatically setting these properties, click the of the following topic: 


e TransferJobsTask 


Related Tasks 


For more information about how to set these properties in SSIS Designer, click the following topic: 


@ Set the Properties of a Task or Container 


Transfer Jobs Task Editor (General Page) 


Use the General page of the Transfer Jobs Task Editor dialog box to name and describe the Transfer Jobs 
task. 





NOTE 


Only members of the sysadmin fixed server role or one of the SQL Server Agent fixed database roles on the destination 
server can successfully create jobs there. To access jobs on the source server, users must be a member of at least the 
SQLAgentUserRole fixed database role there. For more information about SQL Server Agent fixed database roles and 


their permissions, see SQL Server Agent Fixed Database Roles. 











Options 
Name 
Type a unique name for the Transfer Jobs task. This name is used as the label in the task icon. 





NOTE 


Task names must be unique within a package. 





Description 


Type a description of the Transfer Jobs task. 


Transfer Jobs Task Editor Jobs Page) 


Use the Jobs page of the Transfer Jobs Task Editor dialog box to specify properties for copying one or more 
SQL Server Agent jobs from one instance of SQL Server to another. 





NOTE 


To access jobs on the source server, users must be a member of at least the SQLAgentUserRole fixed database role on 
the server. To successfully create jobs on the destination server, the user must be a member of the sysadmin fixed server 
role or one of the SQL Server Agent fixed database roles. For more information about SQL Server Agent fixed database 
roles and their permissions, see SQL Server Agent Fixed Database Roles. 











Options 
SourceConnection 


Select a SMO connection manager in the list, or click <New connection...> to create a new connection to the 
source server. 


DestinationConnection 
Select a SMO connection manager in the list, or click <New connection...> to create a new connection to the 
destination server. 


TransferAllJobs 
Select whether the task should copy all or only the specified SQL Server Agent jobs from the source to the 
destination server. 


This property has the options listed in the following table: 


VALUE DESCRIPTION 

True Copy all jobs. 

False Copy only the specified jobs. 
JobsList 


Click the browse button (...) to select the jobs to copy. At least one job must be selected. 





NOTE 


Specify the SourceConnection before selecting jobs to copy. 





The JobsList option is unavailable when TransferAllJobs is set to True. 


IfObjectExists 
Select how the task should handle jobs of the same name that already exist on the destination server. 


This property has the options listed in the following table: 
VALUE DESCRIPTION 


FailTask Task fails if jobs of the same name already exist on the 
destination server. 


Overwrite Task overwrites jobs of the same name on the destination 
server. 
Skip Task skips jobs of the same name that exist on the 


destination server. 


EnableJobsAtDestination 
Select whether the jobs copied to the destination server should be enabled. 


This property has the options listed in the following table: 


VALUE DESCRIPTION 

True Enable jobs on destination server. 

False Disable jobs on destination server. 
See Also 


Integration Services Tasks 
Control Flow 


Transfer Logins Task 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


The Transfer Logins task transfers one or more logins between instances of SQL Server. 


Transfer Logins Between Instances of SQL Server 


The Transfer Logins task supports a SQL Server source and destination. 


Events 


The task raises an information event that reports the number of logins transferred and a warning event when a 
login is overwritten. 


The Transfer Logins task does not report incremental progress of the login transfer; it reports only 0% and 100 
% completion. 


Execution Value 


The execution value, defined in the ExecutionValue property of the task, returns the number of logins 
transferred. By assigning a user-defined variable to the ExecValueVariable property of the Transfer Logins 
task, information about the login transfer can be made available to other objects in the package. For more 
information, see Integration Services (SSIS) Variables and Use Variables in Packages. 


Log Entries 
The Transfer Logins task includes the following custom log entries: 


e TransferLoginsTaskStarTransferringObjects This log entry reports the transfer has started. The log entry 
includes the start time. 


e TransferLoginsTaskFinishedTransferringObjects This log entry reports the transfer has completed. The log 
entry includes the end time. 


In addition, a log entry for the OnInformation event reports the number of logins that were transferred, and a 
log entry for the OnWarning event is written for each login on the destination that is overwritten. 


Security and Permissions 


To browse logins on the source server and to create logins on the destination server, the user must be a member 
of the sysadmin server role on both servers. 


Configuration of the Transfer Logins Task 


The Transfer Logins task can be configured to transfer all logins, only specified logins, or all logins that have 
access to specified databases only. The sa login cannot be transferred. The sa login may be renamed; however, 
the renamed sa login cannot be transferred either. 


You can also indicate whether the task copies the security identifiers (SIDs) associated with the logins. If the 
Transfer Logins task is used in conjunction with the Transfer Database task the SIDs must be copied to the 


destination; otherwise, the transferred logins are not recognized by the destination database. 


At the destination, the transferred logins are disabled and assigned random passwords. A member of the 
sysadmin role on the destination server must change the passwords and enable the logins before the logins can 
be used. 


The logins to be transferred may already exist on the destination. The Transfer Logins task can be configured to 
handle existing logins in the following ways: 


e Overwrite existing logins. 
e Fail the task when duplicate logins exist. 
e Skip duplicate logins. 


At run time, the Transfer Logins task connects to the source and destination servers by using two SMO 
connection managers. The SMO connection managers are configured separately from the Transfer Logins task, 
and then referenced in the Transfer Logins task. The SMO connection managers specify the server and the 
authentication mode to use when accessing the server. For more information, see SMO Connection Manager. 


You can set properties through SSIS Designer or programmatically. 

For more information about the properties that you can set in SSIS Designer, click the following topic: 
e Expressions Page 

For more information about how to set these properties in SSIS Designer, click the following topic: 


e Set the Properties of a Task or Container 


Programmatic Configuration of the Transfer Logins Task 


For more information about programmatically setting these properties, click the following topic: 


e TransferLoginsTask 


Transfer Logins Task Editor (General Page) 


Use the General page of the Transfer Logins Task Editor dialog box to name and describe the Transfer 
Logins task. 


Options 


Name 


Type a unique name for the Transfer Logins task. This name is used as the label in the task icon. 





NOTE 


Task names must be unique within a package. 





Description 
Type a description of the Transfer Logins task. 


Transfer Logins Task Editor (Logins Page) 


Use the Logins page of the Transfer Logins Task Editor dialog box to specify properties for copying one or 
more SQL Server logins from one instance of SQL Server to another. 





IMPORTANT 
When the Transfer Logins task is executed, logins are created on the destination server with random passwords and the 
passwords are disabled. To use these logins, a member of the sysadmin fixed server role must change the passwords and 


then enable them. The sa login cannot be transferred. 





Options 
SourceConnection 
Select a SMO connection manager in the list, or click <New connection...> to create a new connection to the 


source server. 


DestinationConnection 
Select a SMO connection manager in the list, or click <New connection...> to create a new connection to the 


destination server. 


LoginsToTransfer 
Select the SQL Server logins to copy from the source to the destination server. This property has the options 
listed in the following table: 


VALUE DESCRIPTION 


AllLogins All SQL Server logins on the source server will be copied to 
the destination server. 


SelectedLogins Only logins specified with LoginsList will be copied to the 
destination server. 


AllLoginsFromSelectedDatabases All logins from the databases specified with DatabasesList 
will be copied to the destination server. 


LoginsList 
Select the logins on the source server to be copied to the destination server. This option is only available when 
SelectedLogins is selected for LoginsToTransfer. 


DatabasesList 
Select the databases on the source server that contain logins to be copied to the destination server. This option 
is only available when AllLoginsFromSelectedDatabases is selected for LoginsToTransfer. 


IfObjectExists 
Select how the task should handle logins of the same name that already exist on the destination server. 


This property has the options listed in the following table: 
VALUE DESCRIPTION 


FailTask Task fails if logins of the same name already exist on the 
destination server. 


Overwrite Task overwrites logins of the same name on the destination 
server. 
Skip Task skips logins of the same name that exist on the 


destination server. 


CopySids 





Select whether the security identifiers associated with the logins should be copied to the destination server. 
CopySids must be set to True if the Transfer Logins task is used along with the Transfer Database task. 
Otherwise, the copied logins will not be recognized by the transferred database. 


Transfer Master Stored Procedures Task 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


The Transfer Master Stored Procedures task transfers one or more user-defined stored procedures between 
master databases on instances of SQL Server. To transfer a stored procedure from the master database, the 
owner of the procedure must be dbo. 


The Transfer Master Stored Procedures task can be configured to transfer all stored procedures or only specified 
stored procedures. This task does not copy system stored procedures. 


The master stored procedures to be transferred may already exist on the destination. The Transfer Master Stored 
Procedures task can be configured to handle existing stored procedures in the following ways: 


e Overwrite existing stored procedures. 
e Fail the task when duplicate stored procedures exist. 
e Skip duplicate stored procedures. 


At run time, the Transfer Master Stored Procedures task connects to the source and destination servers by using 
two SMO connection managers. The SMO connection managers are configured separately from the Transfer 
Master Stored Procedures task, and then referenced in the Transfer Master Stored Procedures task. The SMO 
connection managers specify the server and the authentication mode to use when accessing the server. For 
more information, see SMO Connection Manager. 


Transferring Stored Procedures Between Instances of SQL Server 


The Transfer Master Stored Procedures task supports a SQL Server source and destination. 


Events 


The task raises an information event that reports the number of stored procedures transferred and a warning 
event when a stored procedure is overwritten. 


The Transfer Master Stored Procedures task does not report incremental progress of the login transfer; it reports 
only 0% and 100 % completion. 


Execution Value 


The execution value, defined in the ExecutionValue property of the task, returns the number of stored 
procedures transferred. By assigning a user-defined variable to the ExecValueVariable property of the Transfer 
Master Stored Procedures task, information about the stored procedure transfer can be made available to other 
objects in the package. For more information, see Integration Services (SSIS) Variables and Use Variables in 
Packages. 


Log Entries 
The Transfer Master Stored Procedures task includes the following custom log entries: 


e TransferStoredProceduresTaskStartTransferringObjects This log entry reports that the transfer has started. 
The log entry includes the start time. 


e TransferSStoredProceduresTaskFinishedTransferringObjects This log entry reports that the transfer has 
finished. The log entry includes the end time. 


In addition, a log entry for the OnInformation event reports the number of stored procedures that were 
transferred, and a log entry for the OnWarning event is written for each stored procedure on the destination 
that is overwritten. 


Security and Permissions 


The user must have permission to view the list of stored procedure in the master database on the source, and 
must be a member of the sysadmin server role or have permission to created stored procedures in the master 
database on the destination server. 


Configuration of the Transfer Master Stored Procedures Task 


You can set properties through SSIS Designer or programmatically. 

For information about the properties that you can set in SSIS Designer, click the following topic: 
e Expressions Page 

For information about programmatically setting these properties, click the following topic: 

e TransferStoredProcedures Task 


Configuring the Transfer Master Stored Procedures Task Programmatically 


Related Tasks 


For more information about how to set these properties in SSIS Designer, click the following topic: 


e Set the Properties of a Task or Container 


Transfer Master Stored Procedures Task Editor (General Page) 


Use the General page of the Transfer Master Stored Procedures Task Editor dialog box to name and 
describe the Transfer Master Stored Procedures task. 





NOTE 


This task transfers only user-defined stored procedures owned by dbo from a master database on the source server to a 
master database on the destination server. Users must be granted the CREATE PROCEDURE permission in the master 
database on the destination server or be members of the sysadmin fixed server role on the destination server to create 


stored procedures there. 











Options 
Name 


Type a unique name for the Transfer Master Stored Procedures task. This name is used as the label in the task 
icon. 





NOTE 


Task names must be unique within a package. 





Description 


Type a description of the Transfer Master Stored Procedures task. 


Transfer Master Stored Procedures Task Editor (Stored Procedures 
Page) 


Use the Stored Procedures page of the Transfer Master Stored Procedures Task Editor dialog box to 
specify properties for copying one or more user-defined stored procedures from the master database in one 
instance of SQL Server instance to a master database in another instance of SQL Server. 


NOTE 


This task transfers only user-defined stored procedures owned by dbo from a master database on the source server to a 
master database on the destination server. Users must be granted the CREATE PROCEDURE permission in the master 
database on the destination server or be members of the sysadmin fixed server role on the destination server to create 
stored procedures there. 











Options 
SourceConnection 


Select a SMO connection manager in the list, or click <New connection...> to create a new connection to the 
source server. 


DestinationConnection 
Select a SMO connection manager in the list, or click <New connection...> to create a new connection to the 
destination server. 


IfObjectExists 
Select how the task should handle user-defined stored procedures of the same name that already exist in the 
master database on the destination server. 


This property has the options listed in the following table: 
VALUE DESCRIPTION 


FailTask Task fails if stored procedures of the same name already exist 
in the master database on the destination server. 


Overwrite Task overwrites stored procedures of the same name in the 
master database on the destination server. 


Skip Task skips stored procedures of the same name that exist in 
the master database on the destination server. 


TransferAllStoredProcedures 
Select whether all user-defined stored procedures in the master database on the source server should be 
copied to the destination server. 


VALUE DESCRIPTION 

True Copy all user-defined stored procedures in the master 
database. 

False Copy only the specified stored procedures. 


StoredProceduresList 
Select which user-defined stored procedures in the master database on the source server should be copied to 


the destination master database. This option is only available when TransferAllStoredProcedures is set to 
False. 


See Also 


Transfer SQL Server Objects Task 
Integration Services Tasks 
Control Flow 


Transfer SQL Server Objects Task 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


The Transfer SQL Server Objects task transfers one or more types of objects in a SQL Server database between 
instances of SQL Server. For example, the task can copy tables and stored procedures. Depending on the version 
of SQL Server that is used as a source, different types of objects are available to copy. For example, only a SQL 
Server database includes schemas and user-defined aggregates. 


Objects to Transfer 


Server roles, roles, and users from the specified database can be copied, as well as the permissions for the 
transferred objects. By copying the associated users, roles, and permissions together with the objects, you can 
make the transferred objects immediately operable on the destination server. 


The following table lists the type of objects that can be copied. 

OBJECT 

Tables 

Views 

Stored Procedures 

User-Defined Functions 

Defaults 

User-Defined Data Types 

Partition Functions 

Partition Schemes 

Schemas 

Assemblies 

User-Defined Aggregates 

User-Defined Types 

XML Schema Collection 
User-defined types (UDTs) that were created in an instance of SQL Server have dependencies on common 
language runtime (CLR) assemblies. If you use the Transfer SQL Server Objects task to transfer UDTs, you must 


also configure the task to transfer dependent objects. To transfer dependent objects, set the 
IncludeDependentObjects property to True. 


Table Options 


When copying tables, you can indicate the types of table-related items to include in the copy process. The 
following types of items can be copied together with the related table: 


e Indexes 

e Triggers 

e Full-text indexes 
e Primary keys 

e Foreign keys 


You can also indicate whether the script that the task generates is in Unicode format. 


Destination Options 


You can configure the Transfer SQL Server Objects task to include schema names, data, extended properties of 
transferred objects, and dependent objects in the transfer. If data is copied, it can replace or append existing data. 


Some options apply only to SQL Server. For example, only SQL Server supports schemas. 


Security Options 


The Transfer SQL Server Objects task can include SQL Server database-level users and roles from the source, 
SQL Server logins, and the permissions for transferred objects. For example, the transfer can include the 


permissions on the transferred tables. 


Transfer Objects Between Instances of SQL Server 


The Transfer SQL Server Objects task supports a SQL Server source and destination. 


Events 


The task raises an information event that reports the object transferred and a warning event when an object is 
overwritten. An information event is also raised for actions such as the truncation of database tables. 


The Transfer SQL Server Objects task does not report incremental progress of the object transfer; it reports only 
0% and 100 % completion. 


Execution Value 


The execution value, stored in the ExecutionValue property of the task, returns the number of objects 
transferred. By assigning a user-defined variable to the ExecValueVariable property of the Transfer SQL Server 
Objects task, information about the object transfer can be made available to other objects in the package. For 
more information, see Integration Services (SSIS) Variables and Use Variables in Packages. 


Log Entries 


The Transfer SQL Server Objects task includes the following custom log entries: 


e TransferSqlServerObjectsTaskStartTransferringObjects This log entry reports that the transfer has started. 
The log entry includes the start time. 


e TransferSqlServerObjectsTaskFinishedTransferringObjects This log entry reports that the transfer has 
completed. The log entry includes the end time. 


In addition, a log entry for an OnInformation event reports the number of objects of the object types that have 
been selected for transfer, the number of objects that were transferred, and actions such as the truncation of 
tables when data is transferred with tables. A log entry for the OnWarning event is written for each object on 
the destination that is overwritten. 


Security and Permissions 


The user must have permission to browse objects on the source server, and must have permission to drop and 
create objects on the destination server; moreover, the user must have access to the specified database and 
database objects. 


Configuration of the Transfer SQL Server Objects Task 


The Transfer SQL Server Objects task can be configured to transfer all objects, all objects of a type, or only 
specified objects of a type. For example, you can choose to copy only selected tables in the AdventureWorks 
database. 


If the Transfer SQL Server Objects task transfers tables, you can specify the types of table-related objects to copy 
with the tables. For example, you can specify that primary keys are copied with tables. 


To further enhance functionality of transferred objects, you can configure the Transfer SQL Server Objects task 
to include schema names, data, extended properties of transferred objects, and dependent objects in the 
transfer. When copying data, you can specify whether to replace or append existing data. 


At run time, the Transfer SQL Server Objects task connects to the source and destination servers by using two 
SMO connection managers. The SMO connection managers are configured separately from the Transfer SQL 
Server Objects task, and then referenced in the Transfer SQL Server Objects task. The SMO connection 
managers specify the server and the authentication mode to use when accessing the server. For more 


information, see SMO Connection Manager. 

You can set properties through SSIS Designer or programmatically. 

For more information about the properties that you can set in SSIS Designer, click the following topic: 
e Expressions Page 

For more information about how to set these properties in SSIS Designer, click the following topic: 


e Set the Properties of a Task or Container 


Programmatic Configuration of the Transfer SQL Server Objects Task 
For more information about programmatically setting these properties, click the following topic: 


e TransferSqlServerObjectsTask 


Transfer SQL Server Objects Task Editor (General Page) 


Use the General page of the Transfer SQL Server Objects Task Editor dialog box to name and describe the 
Transfer SQL Server Objects task. 


NOTE 


The user who creates the Transfer SQL Server Objects task must have adequate permissions on the source server objects 


to select them for copying, and permission to access the destination server database where the objects will be transferred. 





Options 


Name 
Type a unique name for the Transfer SQL Server Objects task. This name is used as the label in the task icon. 





NOTE 


Task names must be unique within a package. 





Description 


Type a description of the Transfer SQL Server Objects task. 


Transfer SQL Server Objects Task Editor (Objects Page) 


Use the Objects page of the Transfer SQL Server Objects Task Editor dialog box to specify properties for 
copying one or more SQL Server objects from one instance of SQL Server to another. Tables, views, stored 
procedures, and user-defined functions are a few examples of SQL Server objects that you can copy. 


NOTE 


The user who creates the Transfer SQL Server Objects task must have sufficient permissions on the source server objects 


to select them for copying, and permission to access the destination server database where the objects will be transferred. 





Static Options 


SourceConnection 
Select a SMO connection manager in the list, or click <New connection...> to create a new connection to the 
source server. 


SourceDatabase 
Select a database on the source server from which objects will be copied. 


DestinationConnection 
Select a SMO connection manager in the list, or click <New connection...> to create a new connection to the 


destination server. 


DestinationDatabase 
Select a database on the destination server to which objects will be copied. 


DropObjectsFirst 
Select whether the selected objects will be dropped first on the destination server before copying. 


IncludeExtendedProperties 
Select whether extended properties will be included when objects are copied from the source to the destination 
server. 


CopyData 
Select whether data will be included when objects are copied from the source to the destination server. 


ExistingData 
Specify how data will be copied to the destination server. This property has the options listed in the following 
table: 


VALUE DESCRIPTION 


Replace Data on the destination server will be overwritten. 


VALUE DESCRIPTION 


Append Data copied from the source server will be appended to 
existing data on the destination server. 





NOTE 


The ExistingData option is only available when CopyData is set to True. 





CopySchema 
Select whether the schema is copied during the Transfer SQL Server Objects task. 





NOTE 


CopySchema is only available for SQL Server. 











UseCollation 
Select whether the transfer of objects should include the collation specified on the source server. 


IncludeDependentObjects 
Select whether copying the selected objects will cascade to include other objects that depend on the objects 
selected for copying. 


CopyAllObjects 

Select whether the task will copy all objects in the specified source database or only selected objects. Setting this 
option to False gives you the option to select the objects to transfer, and displays the dynamic options in the 
section, CopyAllObjects. 


Objects ToCopy 
Expand ObjectsToCopy to specify which objects should be copied from the source database to the destination 
database. 





NOTE 
ObjectsToCopy is only available when CopyAllObjects is set to False. 





The options to copy the following types of objects are supported only on SQL Server: 


Assemblies 

Partition functions 
Partition schemes 
Schemas 

User-defined aggregates 
User-defined types 

XML schema collections 


CopyDatabaseUsers 
Specify whether database users should be included in the transfer. 


CopyDatabaseRoles 


Specify whether database roles should be included in the transfer. 


CopySqlServerLogins 
Specify whether SQL Server logins should be included in the transfer. 


CopyObjectLevelPermissions 
Specify whether object-level permissions should be included in the transfer. 


Copy!Indexes 
Specify whether indexes should be included in the transfer. 


CopyTriggers 
Specify whether triggers should be included in the transfer. 


CopyFullTextIndexes 
Specify whether full-text indexes should be included in the transfer. 


CopyPrimaryKeys 
Specify whether primary keys should be included in the transfer. 


CopyForeignKeys 
Specify whether foreign keys should be included in the transfer. 


GenerateScriptsInUnicode 
Specify whether the generated transfer scripts are in Unicode format. 


Dynamic Options 

CopyAllObjects = False 

CopyAllTables 

Select whether the task will copy all tables in the specified source database or only the selected tables. 


TablesList 
Click to open the Select Tables dialog box. 


CopyAllViews 


Select whether the task will copy all views in the specified source database or only the selected views. 


ViewsList 
Click to open the Select Views dialog box. 


CopyAllStoredProcedures 
Select whether the task will copy all user-defined stored procedures in the specified source database or only the 
selected procedures. 


StoredProceduresList 
Click to open the Select Stored Procedures dialog box. 


CopyAllUserDefinedFunctions 
Select whether the task will copy all user-defined functions in the specified source database or only the selected 
UDFs. 


UserDefinedFunctionsList 
Click to open the Select User Defined Functions dialog box. 


CopyAllDefaults 
Select whether the task will copy all defaults in the specified source database or only the selected defaults. 


DefaultsList 
Click to open the Select Defaults dialog box. 


CopyAllUserDefinedDataTypes 
Select whether the task will copy all user-defined data types in the specified source database or only the selected 
user-defined data types. 


UserDefinedDataTypesList 
Click to open the Select User-Defined Data Types dialog box. 


CopyAllPartitionFunctions 
Select whether the task will copy all user-defined partition functions in the specified source database or only the 
selected partition functions. Supported only on SQL Server. 


PartitionFunctionsList 
Click to open the Select Partition Functions dialog box. 


CopyAllPartitionSchemes 
Select whether the task will copy all partition schemes in the specified source database or only the selected 
partition schemes. Supported only on SQL Server. 


PartitionSchemesList 
Click to open the Select Partition Schemes dialog box. 


CopyAllSchemas 
Select whether the task will copy all schemas in the specified source database or only the selected schemas. 
Supported only on SQL Server. 


SchemasList 
Click to open the Select Schemas dialog box. 


CopyAllSqlAssemblies 
Select whether the task will copy all SQL assemblies in the specified source database or only the selected SQL 
assemblies. Supported only on SQL Server. 


SqlAssembliesList 
Click to open the Select SQL Assemblies dialog box. 


CopyAllUserDefinedAggregates 
Select whether the task will copy all user-defined aggregates in the specified source database or only the 
selected user-defined aggregates. Supported only on SQL Server. 


UserDefinedAggregatesList 
Click to open the Select User-Defined Aggregates dialog box. 


CopyAllUserDefinedTypes 
Select whether the task will copy all user-defined types in the specified source database or only the selected 
UDTs. Supported only on SQL Server. 


UserDefinedTypes 
Click to open the Select User-Defined Types dialog box. 


CopyAllXmISchemaCollections 
Select whether the task will copy all XML Schema collections in the specified source database or only the 
selected XML schema collections. Supported only on SQL Server. 


XmISchemaCollectionsList 


Click to open the Select XML Schema Collections dialog box. 


See Also 


Integration Services Error and Message Reference 


Integration Services Tasks 

Transfer SQL Server Objects Task Editor (General Page) 
Expressions Page 

Data Formats for Bulk Import or Bulk Export (SQL Server) 
Security Considerations for a SQL Server Installation 


Select Objects to Transfer 
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Applies to: Q sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Use this dialog box to select objects to transfer from one instance of SQL Server to another by using an 
Integration Services transfer task. 


To specify that all objects should be transferred, select the check box in the title row of the objects grid. 


To choose specific objects for transfer, select the check box in the first column for the row in the grid where the 
object is listed. 


See Also 


Integration Services Error and Message Reference 

Transfer Jobs Task Editor (General Page) 

Transfer Logins Task Editor (Logins Page) 

Transfer SQL Server Objects Task Editor (Objects Page) 

Transfer Master Stored Procedures Task Editor (Stored Procedures Page) 
Transfer Error Messages Task Editor (Messages Page) 


Update Statistics Task 


11/23/2021 * 2 minutes to read « Edit Online 





Applies to: Q sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


The Update Statistics task updates information about the distribution of key values for one or more statistics 
groups (collections) in the specified table or indexed view. For more information, see Statistics. 


By using the Update Statistics task, a package can update statistics for a single database or multiple databases. If 
the task updates only the statistics in a single database, you can choose the views or the tables whose statistics 
the task updates. You can configure the update to update all statistics, column statistics only, or index statistics 
only. 


This task encapsulates an UPDATE STATISTICS statement, including the following arguments and clauses: 
e The table_name or view_name argument. 

e If the update applies to all statistics, the WITH ALL clause is implied. 

e If the update applies only to columns, the WITH COLUMN clause is included. 

e If the update applies only to indexes, the WITH INDEX clause is included. 


If the Update Statistics task updates statistics in multiple databases, the task runs multiple UPDATE STATISTICS 
statements, one for each table or view. All instances of UPDATE STATISTICS use the same clause, but different 
table_name or view_name values. For more information, see CREATE STATISTICS (Transact-SQL) and UPDATE 
STATISTICS (Transact-SQL). 





IMPORTANT 

The time the task takes to create the Transact-SQL statement that the task runs is proportionate to the number of 
statistics the task updates. If the task is configured to update statistics in all the tables and views in a database with a 
large number of indexes, or to update statistics in multiple databases, the task can take a considerable amount of time to 
generate the Transact-SQL statement. 











Configuration of the Update Statistics Task 


You can set properties through SSIS Designer. This task is in the Maintenance Plan Tasks section of the 
Toolbox in SSIS Designer. 


For information about the properties that you can set in SSIS Designer, click the following topic: 


e Update Statistics Task (Maintenance Plan) 


Related Tasks 


For more information about how to set these properties in SSIS Designer, click the following topic: 


e Set the Properties of a Task or Container 


See Also 


Integration Services Tasks 


Control Flow 


Web Service Task 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


The Web Service task executes a Web service method. You can use the Web Service task for the following 
purposes: 


e Writing to a variable the values that a Web service method returns. For example, you could obtain the 
highest temperature of the day from a Web service method, and then use that value to update a variable 
that is used in an expression that sets a column value. 


e Writing to a file the values that a Web service method returns. For example, a list of potential customers 
can be written to a file and the file then used as a data source in a package that cleans the data before it is 
written to a database. 


WSDL File 


The Web Service task uses an HTTP connection manager to connect to the Web service. The HTTP connection 
manager is configured separately from the Web Service task, and is referenced in the task. The HTTP connection 
manager specifies the server proxy settings such as the server URL, credentials for accessing the Web services 
server, and time-out length. For more information, see HTTP Connection Manager. 


IMPORTANT 


The HTTP connection manager supports only anonymous authentication and basic authentication. It does not support 


Windows Authentication. 





The HTTP connection manager can point to a Web site or to a Web Service Description Language (WSDL) file. 
The URL of the HTTP connection manager that points to a WSDL file includes the ?wspL parameter: for example, 


https: //MyServer/MyWebService/MyPage.asmx?WSDL . 


The WSDL file must be available locally to configure the Web Service task using the Web Service Task Editor 
dialog box that SSIS Designer provides. 


e If the HTTP connection manager points to a Web site, the WSDL file must be copied manually to a local 
computer. 


e Ifthe HTTP connection manager points to a WSDL file, the file can be downloaded from the Web site to a 
local file by the Web Service task. 


The WSDL file lists the methods that the Web service offers, the input parameters that the methods require, the 
responses that the methods return, and how to communicate with the Web service. 


If the method uses input parameters, the Web Service task requires parameter values. For example, a Web 
service method that recommends the length of skis you should purchase based on your height requires that 
your height be submitted in an input parameter. The parameter values can be provided either by strings that are 
defined in the task, or by variables defined in the scope of the task or a parent container. The advantage of using 
variables is that they let you dynamically update the parameter values by using package configurations or 
scripts. For more information, see Integration Services (SSIS) Variables and Package Configurations. 


Many Web service methods do not use input parameters. For example, a Web service method that gets the 


names of presidents who were born in the current month would not require an input parameter because the 
Web service can determine the current month locally. 


The results of the Web service method can be written to a variable or to a file. You use the File connection 
manager either to specify the file or to provide the name of the variable to write the results to. For more 
information, see File Connection Manager and Integration Services (SSIS) Variables. 


Custom Logging Messages Available on the Web Service Task 


The following table lists the custom log entries that you can enable for the Web Service task. For more 
information, see Integration Services (SSIS) Logging. 


LOG ENTRY DESCRIPTION 

WSTaskBegin The task began to access a Web service. 
WSTaskEnd The task completed a Web service method. 
WSTaskinfo Descriptive information about the task. 


Configuration of the Web Service Task 

You can set properties through SSIS Designer or programmatically. 

For more information about the properties that you can set in SSIS Designer, click the following topic: 
e Expressions Page 

For more information about how to set these properties in SSIS Designer, click the following topic: 


e Set the Properties of a Task or Container 


Programmatic Configuration of the Web Service Task 


For more information about programmatically setting these properties, click one of the following topics: 


e WebServiceTask 


Web Service Task Editor (General Page) 


Use the General page of the Web Services Task Editor dialog box to specify an HTTP connection manager, 
specify the location of the Web Services Description Language (WSDL) file the Web Service task uses, describe 
the Web Services task, and download the WSDL file. 


Options 
HTTPConnection 


Select a connection manager in the list, or click <New connection...> to create a new connection manager. 





IMPORTANT 


The HTTP connection manager supports only anonymous authentication and basic authentication. It does not support 
Windows Authentication. 








Related Topics: HTTP Connection Manager, HTTP Connection Manager Editor (Server Page) 


WSDLFile 


Type the fully qualified path of a WSDL file that is local to the computer, or click the browse button (...) and 
locate this file. 


If you have already manually downloaded the WSDL file to the computer, select this file. However, if the WSDL 
file has not yet been downloaded, follow these steps: 


e Create an empty file that has the ".wsdl" file name extension. 
e Select this empty file for the WSDLFile option. 


e Set the value of OverwriteWSDLFile to True to enable the empty file to be overwritten with the actual 
WSDL file. 


e Click Download WSDL to download the actual WSDL file and overwrite the empty file. 





NOTE 


The Download WSDL option is not enabled until you provide the name of an existing local file in the WSDLFile 
box. 








OverwriteWSDLFile 
Indicate whether the WSDL file for the Web Service task can be overwritten. 


If you intend to download the WSDL file by using the Download WSDL button, set this value to True. 


Name 


Provide a unique name for the Web Service task. This name is used as the label in the task icon. 





NOTE 


Task names must be unique within a package. 





Description 
Type a description of the Web Service task. 


Download WSDL 
Download the WSDL file. 


This button is not enabled until you provide the name of an existing local file in the WSDLFile box. 


Web Service Task Editor (Input Page) 


Use the Input page of the Web Service Task Editor dialog box to specify the Web Service, the Web method, 
and the values to provide to the Web method as input. The values can be provided either by typing strings 
directly in the Value column, or by selecting variables in the Value column. 


Options 
Service 


Select a Web service from the list to use to execute the Web method. 


Method 
Select a Web method from the list for the task to execute. 


WebMethodDocumentation 
Type a description of Web method, or the click the browse button (...) and then type the description in the Web 
Method Documentation dialog box. 


Name 
Lists the names of the inputs to the Web method. 


Type 
Lists the data type of the inputs. 





NOTE 


The Web Service task supports parameters of the following data types only: primitive types such as integers and strings; 


arrays and sequences of primitive types; and enumerations. 











Variable 


Select the check boxes to use variables to provide inputs. 


Value 
If the Variable check-boxes are selected, select the variables in the list to provide the inputs; otherwise, type the 
values to use in the inputs. 


Web Service Task Editor (Output Page) 


Use the Output page of the Web Service Task Editor dialog box to specify where to store the result returned 
by the Web method. 
Static Options 


OutputType 
Select the storage type to use when storing the results. This property has the options listed in the following 
table. 


VALUE DESCRIPTION 


File Connection Store the results in a file. Selecting this value displays the 
dynamic option, File. 


Variable Store the results in a variable. Selecting this value displays 
the dynamic option, Variable. 


OutputType Dynamic Options 

OutputType = File Connection 

File 

Select a File connection manager in the list or click <New Connection...> to create a new connection manager. 


Related Topics: File Connection Manager, File Connection Manager Editor 


OutputType = Variable 
Variable 
Select a variable in the list or click <New Variable...> to create a new variable. 


Related Topics: Integration Services (SSIS) Variables, Add Variable 


Related Content 


Video, How to: Call a Web Service by Using the Web Service Task (SQL Server Video), on technet.microsoft.com. 


WMI Data Reader Task 


11/23/2021 * 5 minutes to read « Edit Online 





Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


The WMI Data Reader task runs queries using the Windows Management Instrumentation (WMI) Query 
Language that returns information from WMI about a computer system. You can use the WMI Data Reader task 
for the following purposes: 


@ Query the Windows event logs on a local or remote computer and write the information to a file or 
variable. 


e Obtain information about the presence, state, or properties of hardware components, and then use this 
information to determine whether other tasks in the control flow should run. 


e Geta list of applications and determine what version of each application is installed. 
You can configure the WMI Data Reader task in the following ways: 
e@ Specify the WMI connection manager to use. 


e Specify the source of the WQL query. The query can be stored in a task property, or the query can be 
stored outside the task, in a variable or a file. 


e Define the format of the WQL query results. The task supports a table, property name/value pair, or 
property value format. 


e Specify the destination of the query. The destination can be a variable or a file. 
@ Indicate whether the query destination is overwritten, kept, or appended. 


If the source or destination is a file, the WMI Data Reader task uses a File connection manager to connect to the 
file. For more information, see Flat File Connection Manager. 


The WMI Data Reader task uses a WMI connection manager to connect to the server from which it reads WMI 
information. For more information, see WMI Connection Manager. 


WAQL Query 


WAL is a dialect of SQL with extensions to support WMI event notification and other WMI-specific features. For 
more information about WQL, see the Windows Management Instrumentation documentation in the MSDN 
Library. 





NOTE 


WMI classes vary between versions of Windows. 











The following WQL query returns entries in the Application log event. 


SELECT * FROM Win32_NTLogEvent WHERE LogFile = 'Application' AND (SourceName='SQLISService' OR 
SourceName='SQLISPackage') AND TimeGenerated > '20050117' 


The following WQL query returns logical disk information. 


SELECT FreeSpace, DeviceId, Size, SystemName, Description FROM Win32_LlogicalDisk 


The following WQL query returns a list of the quick fix engineering (QFE) updates to the operating system. 


Select * FROM Win32_QuickFixEngineering 


Custom Logging Messages Available on the WMI Data Reader Task 


The following table lists the custom log entries for the WMI Data Reader task. For more information, see 
Integration Services (SSIS) Logging. 


LOG ENTRY DESCRIPTION 
WMIDataReaderGettingWMIData Indicates that the task began to read WMI data. 
WM IDataReaderOperation Reports the WQL query that the task ran. 


Configuration of the WMI Data Reader Task 

You can set properties programmatically or through SSIS Designer. 

For information about the properties that you can set in SSIS Designer, click the following topic: 
e Expressions Page 

For information about programmatically setting these properties, click the following topic: 


e WmiDataReaderTask 


Related Tasks 


For more information about how to set these properties in SSIS Designer, click the following topic: 


e Set the Properties of a Task or Container 


WMI Data Reader Task Editor (General Page) 


Use the General page of the WMI Data Reader Task Editor dialog box to name and describe the WMI Data 
Reader task. 


For more information about WMI Query Language (WQL), see the Windows Management Instrumentation 
topic, Querying with WQL, in the MSDN Library. 
Options 


Name 
Provide a unique name for the WMI Data Reader task. This name is used as the label in the task icon. 





NOTE 


Task names must be unique within a package. 





Description 


Type a description of the WMI Data Reader task. 


WMI Data Reader Task Editor (WMI Options Page) 


Use the WMI Options page of the WMI Data Reader Task Editor dialog box to specify the source of the 
Windows Management Instrumentation Query Language (WQL) query and the destination of the query result. 


For more information about WMI Query Language (WQL), see the Windows Management Instrumentation 
topic, Querying with WQL, in the MSDN Library. 
Static Options 


WMIConnectionName 
Select a WMI connection manager in the list, or click <New WMI Connection...> to create a new connection 
manager. 


Related Topics: WMI Connection Manager, WMI Connection Manager Editor 


WQLQuerySourceType 
Select the source type of the WQL query that the task runs. This property has the options listed in the following 
table. 


VALUE DESCRIPTION 


Direct input Set the source to a WQL query. Selecting this value displays 
the dynamic option WQLQuerySourceType. 


File connection Select a file that contains the WQL query. Selecting this value 
displays the dynamic option WQLQuerySourceType. 


Variable Set the source to a variable that defines the WQL query. 
Selecting this value displays the dynamic option 
WQLQuerySourceType. 
OutputType 


Specify whether the output should be a data table, property value, or property name and value. 


OverwriteDestination 


Specifies whether to keep, overwrite, or append to the original data in the destination file or variable. 


DestinationType 
Select the destination type of the WQL query that the task runs. This property has the options listed in the 
following table. 


VALUE DESCRIPTION 


File connection Select a file to save the results of the WQL query in. 
Selecting this value displays the dynamic option, 
DestinationType. 


Variable Set the variable to store the results of the WQL query in. 
Selecting this value displays the dynamic option, 
DestinationType. 


WQLQuerySourceType Dynamic Options 

WaQLQuerySourceType = Direct input 

WQLQuerySource 

Provide a query, or click the ellipsis (...) and enter a query using the WQL Query dialog box. 


WaQLQuerySourceType = File connection 


WQLQuerySource 
Select a File connection manager in the list, or click <New connection...> to create a new connection manager. 


Related Topics: File Connection Manager, File Connection Manager Editor 


WaQLQuerySourceType = Variable 
WQLQuerySource 
Select a variable in the list, or click <New variable...> to create a new variable. 


Related Topics: Integration Services (SSIS) Variables, Add Variable 


DestinationType Dynamic Options 

DestinationType = File connection 

Destination 

Select a File connection manager in the list, or click <New connection...> to create a new connection manager. 


Related Topics: File Connection Manager, File Connection Manager Editor 


DestinationType = Variable 
Destination 
Select a variable in the list, or click <New variable...> to create a new variable. 


Related Topics: Integration Services (SSIS) Variables, Add Variable 


See Also 


Integration Services Tasks 
Control Flow 


WMI Event Watcher Task 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


The WMI Event Watcher task watches for a Windows Management Instrumentation (WMI) event using a 
Management Instrumentation Query Language (WQL) event query to specify events of interest. You can use the 
WMI Event Watcher task for the following purposes: 


e Wait for notification that files have been added to a folder and then initiate the processing of the file. 


e Runa package that deletes files when the available memory on a server drops lower than a specified 
percentage. 


e Watch for installation of an application, and then run a package that uses the application. 
Integration Services includes a task that reads WMI information. 
For more information about this task, click the following topic: 


e WMI Data Reader Task 


WAQL Queries 


WAL is a dialect of SQL with extensions to support WMI event notification and other WMl-specific features. For 
more information about WQL, see the Windows Management Instrumentation documentation in the MSDN 
Library. 





NOTE 


WMI classes vary between versions of Windows. 





The following query watches for notification that the CPU use is more than 40 percent. 


SELECT * from __InstanceModificationEvent WITHIN 2 WHERE TargetInstance ISA 'Win32_Processor' and 
TargetInstance.LoadPercentage > 40 


The following query watches for notification that a file has been added to a folder. 


SELECT * FROM __InstanceCreationEvent WITHIN 10 WHERE TargetInstance ISA "CIM _DirectoryContainsFile" and 
TargetInstance.GroupComponent= "Win32_Directory.Name=\"c:\\\\WMIFileWatcher\"" 


Custom Logging Messages Available on the WMI Event Watcher Task 


The following table lists the custom log entries for the WMI Event Watcher task. For more information, see 
Integration Services (SSIS) Logging. 


LOG ENTRY DESCRIPTION 


WMlEventWatcherEventOccurred Indicates that an event occurred that the task was 
monitoring. 


LOG ENTRY DESCRIPTION 
WMlEventWatcherTimedout Indicates that the task timed out. 


WMlEventWatcherWatchingForWMlEvents Indicates that the task began to execute the WQL query. The 
entry includes the query. 


Configuration of the WMI Event Watcher Task 


You can configure the WMI Data Reader task in the following ways: 
@ Specify the WMI connection manager to use. 


e Specify the source of the WQL query. The source can be external to the task, a variable or a file, or the 
query can be stored in a task property. 


e Specify the action that the task takes when the WMI event occurs. You can log the event notification and 
the status after the event, or raise custom Integration Services events that provide information associated 
with the WMI event, the notification, and the status after the event. 


e Define how the task responds to the event. The task can be configured to succeed or fail, depending on 
the event, or the task can just watch for the event again. 


e Specify the action the task takes when the WMI query times out. You can log the time-out and the status 
after time-out, or raise a custom Integration Services event, indicating that the WMI event timed out and 
logging the time-out and time-out status. 


e Define how the task responds to the time-out. The task can be configured to succeed or fail, or the task 
can just watch for the event again. 


@ Specify the number of times the task watches for the event. 
e Specify the time-out. 


If the source is a file, the WMI Event Watcher task uses a File connection manager to connect to the file. For more 


information, see Flat File Connection Manager. 


The WMI Event Watcher task uses a WMI connection manager to connect to the server from which it reads WMI 


information. For more information, see WMI Connection Manager. 

You can set properties through SSIS Designer or programmatically. 

For more information about the properties that you can set in SSIS Designer, click the following topic: 
e Expressions Page 

For more information about how to set these properties in SSIS Designer, click the following topic: 


e Set the Properties of a Task or Container 


Programmatic Configuration of the WMI Event Watcher Task 
For more information about programmatically setting these properties, click the following topic: 


e WmiEventWatcherTask 


WMI Event Watcher Task Editor (General Page) 


Use the General page of the WMI Event Watcher Task Editor dialog box to name and describe the WMI 


Event Watcher task. 


For more information about WMI Query Language (WQL), see the Windows Management Instrumentation 
topic, Querying with WQL, in the MSDN Library. 


Options 


Name 


Provide a unique name for the WMI Event Watcher task. This name is used as the label in the task icon. 





NOTE 


Task names must be unique within a package. 





Description 
Type a description of the WMI Event Watcher task. 


WMI Event Watcher Task Editor (WMI Options Page) 


Use the WMI Options page of the WMI Event Watcher Task Editor dialog box to specify the source of the 
Windows Management Instrumentation Query Language (WQL) query and how the WMI Event Watcher task 
responds to Microsoft Windows Instrumentation (WMI) events. 


For more information about WMI Query Language (WQL), see the Windows Management Instrumentation 
topic, Querying with WQL, in the MSDN Library. 


Static Options 


WM!IConnectionName 
Select a WMI connection manager in the list, or click <New WMI Connection...> to create a new connection 


manager. 
Related Topics: WMI Connection Manager, WMI Connection Manager Editor 


WQLQuerySourceType 
Select the source type of the WQL query that the task runs. This property has the options listed in the following 
table. 


VALUE DESCRIPTION 


Direct input Set the source to a WQL query. Selecting this value displays 
the dynamic option, WQLQuerySource. 


File connection Select a file that contains the WQL query. Selecting this value 
displays the dynamic option, WQLQuerySource. 


Variable Set the source to a variable that defines WQL query. 
Selecting this value displays the dynamic option, 
WQLQuerySource. 


ActionAtEvent 
Specify whether the WMI event logs the event and initiates an SSIS action, or only logs the event. 


AfterEvent 
Specify whether the task succeeds or fails after it receives the WMI event, or if the task continues watching for 
the event to occur again. 


ActionAtTimeout 


Specify whether the task logs a WMI query time-out and initiates an SSIS event in response, or only logs the 
time-out. 


AfterTimeout 
Specify whether the task succeeds or fails in response to a time-out, or if the task continues watching for 
another time-out to recur. 


NumberOfEvents 
Specify the number of events to watch for. 


Timeout 
Specify the number of seconds to wait for the event to occur. A value of 0 means that no time-out is in effect. 


WQLQuerySource Dynamic Options 

WaQLQuerySource = Direct input 

WQLQuerySource 

Provide a query, or click the ellipsis button (...) and enter a query using the WQL Query dialog box. 


WQLQuerySource = File connection 
WQLQuerySource 
Select a File connection manager in the list, or click <New connection...> to create a new connection manager. 


Related Topics: File Connection Manager, File Connection Manager Editor 


WaQLQuerySource = Variable 
WQLQuerySource 


Select a variable in the list, or click <New variable...> to create a new variable. 


Related Topics: Integration Services (SSIS) Variables, Add Variable 


XML Task 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


The XML task is used to work with XML data. Using this task, a package can retrieve XML documents, apply 
operations to the documents by using Extensible Stylesheet Language Transformations (XSLT) style sheets and 
XPath expressions, merge multiple documents, or validate, compare, and save the updated documents to files 
and variables. 


This task enables an Integration Services package to dynamically modify XML documents at run time. You can 
use the XML task for the following purposes: 


e Reformat an XML document. For example, the task can access a report that resides in an XML file and 
dynamically apply an XSLT style sheet to customize the document presentation. 


e Select sections of an XML document. For example, the task can access a report that resides in an XML file 
and dynamically apply an XPath expression to select a section of the document. The operation can also 
get and process values in the document. 


e Merge documents from many sources. For example, the task can download reports from multiple 
sources and dynamically merge them into one comprehensive XML document. 


e Validate an XML document and optionally get detailed error output. For more info, see Validate XML with 
the XML Task. 


You can include XML data in a data flow by using an XML source to extract values from an XML document. For 
more information, see XML Source. 


XML Operations 


The first action the XML task performs is to retrieve a specific XML document. This action is built into the XML 
task and occurs automatically. The retrieved XML document is used as the source of data for the operation that 
the XML task performs. 


The XML operations Diff, Merge, and Patch require two operands. The first operand specifies the source XML 
document. The second operand also specifies an XML document, the contents of which depend on the 
requirements of the operation. For example, the Diff operation compares two documents; therefore, the second 
operand specifies another, similar XML document to which the source XML document is compared. 


The XML task can use a variable or a File connection manager as its source, or include the XML data in a task 
property. 


If the source is a variable, the specified variable contains the path of the XML document. 


If the source is a File connection manager, the specified File connection manager provides the source 
information. The File connection manager is configured separately from the XML task, and is referenced in the 
XML task. The connection string of the File connection manager specifies the path of the XML file. For more 


information, see File Connection Manager. 


The XML task can be configured to save the result of the operation to a variable or to a file. If saving to a file, the 
XML task uses a File connection manager to access the file. You can also save the results of the Diffgram 
generated by the Diff operation to files and variables. 


Predefined XML Operations 


The XML task includes a predefined set of operations for working with XML documents. The following table 
describes these operations. 


OPERATION DESCRIPTION 


Diff Compares two XML documents. Using the source XML 
document as the base document, the Diff operation 
compares it to a second XML document, detects their 
differences, and writes the differences to an XML Diffgram 
document. This operation includes properties for 
customizing the comparison. 


Merge Merges two XML documents. Using the source XML 
document as the base document, the Merge operation adds 
the content of a second document into the base document. 
The operation can specify a merge location within the base 
document. 


Patch Applies the output from the Diff operation, called a Diffgram 
document, to an XML document, to create a new parent 
document that includes content from the Diffgram 
document. 


Validate Validates the XML document against a Document Type 
Definition (DTD) or XML Schema definition (XSD) schema. 


XPath Performs XPath queries and evaluations. 
XSLT Performs XSL transformations on XML documents. 
Diff Operation 


The Diff operation can be configured to use a different comparison algorithm depending on whether the 
comparison must be fast or precise. The operation can also be configured to automatically select a fast or 
precise comparison based on the size of the documents being compared. 


The Diff operation includes a set of options that customize the XML comparison. The following table describes 


the options. 

OPTION DESCRIPTION 

IgnoreComments A value that specifies whether comment nodes are 
compared. 

IgnoreNamespaces A value that specifies whether the namespace uniform 
resource identifier (URI) of an element and its attribute 
names are compared. If this option is set to true, two 
elements that have the same local name but a different 
namespace are considered to be identical. 

IgnorePrefixes A value that specifies whether prefixes of element and 


attribute names are compared. If this option is set to true, 
two elements that have the same local name but a different 
namespace URI and prefix are considered identical. 


OPTION DESCRIPTION 


IgnoreXMLDeclaration A value that specifies whether the XML declarations are 
compared. 
IgnoreOrderOfChildElements A value that specifies whether the order of child elements is 


compared. If this option is set to true, child elements that 
differ only in their position in a list of siblings are considered 
to be identical. 


IgnoreWhiteSpaces A value that specifies whether white spaces are compared. 

IgnoreProcessingInstructions A value that specifies whether processing instructions are 
compared. 

IgnoreDTD A value that specifies whether the DTD is ignored. 


Merge Operation 


When you use an XPath statement to identify the merge location in the source document, this statement is 
expected to return a single node. If the statement returns multiple nodes, only the first node is used. The 
contents of the second document are merged under the first node that the XPath query returns. 


XPath Operation 


The XPath operation can be configured to use different types of XPath functionality. 
e Select the Evaluation option to implement XPath functions such as sum(). 
e Select the Node list option to return the selected nodes as an XML fragment. 


e Select the Values option to return the inner text value of all the selected nodes, concatenated into a 
string. 
Validation Operation 


The Validation operation can be configured to use either a Document Type Definition (DTD) or XML Schema 
definition (XSD) schema. 


Enable ValidationDetails to get detailed error output. For more info, see Validate XML with the XML Task. 


XML Document Encoding 


The XML task supports merging of Unicode documents only. This means the task can apply the Merge operation 
only to documents that have a Unicode encoding. Use of other encodings will cause the XML task to fail. 


NOTE 


The Diff and Patch operations include an option to ignore the XML declaration in the second-operand XML data, making 


it possible to use documents that have other encodings in these operations. 











To verify that the XML document can be used, review the XML declaration. The declaration must explicitly specify 
UTF-8, which indicates 8-bit Unicode encoding. 


The following tag shows the Unicode 8-bit encoding. 


<?xml version="1.0" encoding="UTF-8"?> 


Custom Logging Messages Available on the XML Task 


The following table describes the custom log entry for the XML task. For more information, see Integration 
Services (SSIS) Logging. 


LOG ENTRY DESCRIPTION 
XMLOperation Provides information about the operation that the task 
performs 


Configuration of the XML Task 

You can set properties through SSIS Designer or programmatically. 

For more information about the properties that you can set in SSIS Designer, click one of the following topics: 
e Validate XML with the XML Task 

e Expressions Page 

For more information about how to set properties in SSIS Designer, click the following topic: 


e Set the Properties of a Task or Container 


Programmatic Configuration of the XML Task 
For more information about programmatically setting these properties, click the following topic: 


e XMLTask 


Related Tasks 


Set the Properties of a Task or Container 


XML Task Editor (General Page) 


Use the General Node of the XML Task Editor dialog box to specify the operation type and configure the 
operation. 


To learn about this task, see Validate XML with the XML Task. For information about working with XML 
documents and data, see "Employing XML in the .NET Framework" in the MSDN Library. 


Static Options 


OperationType 
Select the operation type from the list. This property has the options listed in the following table. 


VALUE DESCRIPTION 


Validate Validates the XML document against a Document Type 
Definition (DTD) or XML Schema definition (XSD) schema. 
Selecting this option displays the dynamic options in section, 
Validate. 


XSLT Performs XSL transformations on XML documents. Selecting 
this option displays the dynamic options in section, XSLT. 


VALUE DESCRIPTION 


XPATH Performs XPath queries and evaluations. Selecting this option 
displays the dynamic options in section, XPATH. 


Merge Merges two XML documents. Selecting this option displays 
the dynamic options in section, Merge. 


Diff Compares two XML documents. Selecting this option 
displays the dynamic options in section, Diff. 


Patch Applies the output from the Diff operation to create a new 
document. Selecting this option displays the dynamic 
options in section, Patch. 


SourceType 
Select the source type of the XML document. This property has the options listed in the following table. 


VALUE DESCRIPTION 
Direct input Set the source to an XML document. 
File connection Select a file that contains the XML document. 
Variable Set the source to a variable that contains the XML 
document. 
Source 


If Source is set to Direct input, provide the XML code or click the ellipsis button (...) and then provide the XML 
by using the Document Source Editor dialog box. 


If Source is set to File connection, select a File connection manager, or click <New connection...> to create a 


new connection manager. 

Related Topics: File Connection Manager, File Connection Manager Editor 

If Source is set to Variable, select an existing variable, or click <New variable...> to create a new variable. 
Related Topics: Integration Services (SSIS) Variables, Add Variable. 


OperationType Dynamic Options 
OperationType = Validate 


Specify options for the Validate operation. 


SaveOperationResult 
Specify whether the XML task saves the output of the Validate operation. 


OverwriteDestination 
Specify whether to overwrite the destination file or variable. 


Destination 
Select an existing File connection manager, or click <New connection...> to create a new connection manager. 


Related Topics: File Connection Manager, File Connection Manager Editor 


DestinationType 
Select the destination type of the XML document. This property has the options listed in the following table. 


VALUE DESCRIPTION 


File connection Select a file that contains the XML document. 
Variable Set the source to a variable that contains the XML 
document. 


ValidationType 
Select the validation type. This property has the options listed in the following table. 


VALUE DESCRIPTION 
DTD Use a Document Type Definition (DTD). 
XSD Use an XML Schema definition (XSD) schema. Selecting this 


option displays the dynamic options in section, 
ValidationType. 


FailOnValidationFail 
Specify whether the operation fails if the document fails to validate. 


ValidationDetails 
Provides rich error output when the value of this property is true. For more info, see Validate XML with the XML 
Task. 


ValidationType Dynamic Options 

ValidationType = XSD 

SecondOperandType 

Select the source type of the second XML document. This property has the options listed in the following table. 


VALUE DESCRIPTION 
Direct input Set the source to an XML document. 
File connection Select a file that contains the XML document. 
Variable Set the source to a variable that contains the XML 
document. 
SecondOperand 


If SecondOperandType is set to Direct input, provide the XML code or click the ellipsis button (...) and then 
provide the XML by using the Source Editor dialog box. 


If SecondOperandType is set to File connection, select a File connection manager, or click <New 
connection...> to create a new connection manager. 


Related Topics: File Connection Manager, File Connection Manager Editor 


If XPathStringSourceType is set to Variable, select an existing variable, or click <New variable...> to create a 


new variable. 


Related Topics: Integration Services (SSIS) Variables, Add Variable. 


OperationType = XSLT 
Specify options for the XSLT operation. 


SaveOperationResult 


Specify whether the XML task saves the output of the XSLT operation. 


OverwriteDestination 
Specify whether to overwrite the destination file or variable. 


Destination 
If DestinationType is set to File connection, select a File connection manager, or click <New connection...> 


to create a new connection manager. 
Related Topics: File Connection Manager, File Connection Manager Editor 


lf DestinationType is set to Variable, select an existing variable, or click <New variable...> to create a new 


variable. 
Related Topics: Integration Services (SSIS) Variables, Add Variable. 


DestinationType 
Select the destination type of the XML document. This property has the options listed in the following table. 


VALUE DESCRIPTION 
File connection Select a file that contains the XML document. 
Variable Set the source to a variable that contains the XML 
document. 
SecondOperandType 


Select the source type of the second XML document. This property has the options listed in the following table. 


VALUE DESCRIPTION 
Direct input Set the source to an XML document. 
File connection Select a file that contains the XML document. 
Variable Set the source to a variable that contains the XML 
document. 
SecondOperand 


If SecondOperandType is set to Direct input, provide the XML code or click the ellipsis button (...) and then 
provide the XML by using the Source Editor dialog box. 


If SecondOperandType is set to File connection, select a File connection manager, or click <New 


connection...> to create a new connection manager. 
Related Topics: File Connection Manager, File Connection Manager Editor 


If XPathStringSourceType is set to Variable, select an existing variable, or click <New variable...> to create a 


new variable. 


Related Topics: Integration Services (SSIS) Variables, Add Variable. 


OperationType = XPATH 
Specify options for the XPath operation. 


SaveOperationResult 
Specify whether the XML task saves the output of the XPath operation. 


OverwriteDestination 


Specify whether to overwrite the destination file or variable. 


Destination 
lf DestinationType is set to File connection, select a File connection manager, or click <New connection...> 
to create a new connection manager. 


Related Topics: File Connection Manager, File Connection Manager Editor 


lf DestinationType is set to Variable, select an existing variable, or click <New variable...> to create a new 
variable. 


Related Topics: Integration Services (SSIS) Variables, Add Variable. 


DestinationType 
Select the destination type of the XML document. This property has the options listed in the following table. 


VALUE DESCRIPTION 
File connection Select a file that contains the XML document. 
Variable Set the source to a variable that contains the XML 
document. 
SecondOperandType 


Select the source type of the second XML document. This property has the options listed in the following table. 


VALUE DESCRIPTION 
Direct input Set the source to an XML document. 
File connection Select a file that contains the XML document. 
Variable Set the source to a variable that contains the XML 
document. 
SecondOperand 


If SecondOperandType is set to Direct input, provide the XML code or click the ellipsis button (...) and then 
provide the XML by using the Source Editor dialog box. 


If SecondOperandType is set to File connection, select a File connection manager, or click <New 


connection...> to create a new connection manager. 
Related Topics: File Connection Manager, File Connection Manager Editor 


If XPathStringSourceType is set to Variable, select an existing variable, or click <New variable...> to create a 
new variable. 


Related Topics: Integration Services (SSIS) Variables, Add Variable. 


PutResultInOneNode 
Specify whether the result is written to a single node. 


XPathOperation 
Select the XPath result type. This property has the options listed in the following table. 


VALUE DESCRIPTION 


VALUE DESCRIPTION 


Evaluation Returns the results of an XPath function. 
Node list Return the selected nodes as an XML fragment. 
Values Return the inner text value of all selected nodes, 


concatenated into a string. 


OperationType = Merge 
Specify options for the Merge operation. 


XPathStringSourceType 
Select the source type of the XML document. This property has the options listed in the following table. 


VALUE DESCRIPTION 

Direct input Set the source to an XML document. 

File connection Select a file that contains the XML document. 

Variable Set the source to a variable that contains the XML 
document. 


XPathStringSource 
If XPathStringSourceType is set to Direct input, provide the XML code or click the ellipsis button (...) and 
then provide the XML by using the Document Source Editor dialog box. 


If XPathStringSourceType is set to File connection, select a File connection manager, or click <New 
connection...> to create a new connection manager. 


Related Topics: File Connection Manager, File Connection Manager Editor 


If XPathStringSourceType is set to Variable, select an existing variable, or click <New variable...> to create a 
new variable. 


Related Topics: Integration Services (SSIS) Variables, Add Variable 


When you use an XPath statement to identify the merge location in the source document, this statement is 
expected to return a single node. If the statement returns multiple nodes, only the first node is used. The 
contents of the second document are merged under the first node that the XPath query returns. 


SaveOperationResult 
Specify whether the XML task saves the output of the Merge operation. 


OverwriteDestination 
Specify whether to overwrite the destination file or variable. 


Destination 
If DestinationType is set to File connection, select a File connection manager, or click <New connection...> 
to create a new connection manager. 


Related Topics: File Connection Manager, File Connection Manager Editor 


lf DestinationType is set to Variable, select an existing variable, or click <New variable...> to create a new 
variable. 


Related Topics: Integration Services (SSIS) Variables, Add Variable. 


DestinationType 
Select the destination type of the XML document. This property has the options listed in the following table. 


VALUE DESCRIPTION 
File connection Select a file that contains the XML document. 
Variable Set the source to a variable that contains the XML 
document. 
SecondOperandType 


Select the destination type of the second XML document. This property has the options listed in the following 
table. 


VALUE DESCRIPTION 
Direct input Set the source to an XML document. 
File connection Select a file that contains the XML document. 
Variable Set the source to a variable that contains the XML 
document. 
SecondOperand 


If SecondOperandType is set to Direct input, provide the XML code or click the ellipsis button (...) and then 
provide the XML by using the Document Source Editor dialog box. 


If SecondOperandType is set to File connection, select a File connection manager, or click <New 
connection...> to create a new connection manager. 


Related Topics: File Connection Manager, File Connection Manager Editor 


If SecondOperand Type is set to Variable, select an existing variable, or click <New variable...> to create a 


new variable. 


Related Topics: Integration Services (SSIS) Variables, Add Variable 
OperationType = Diff 

Specify options for the Diff operation. 

DiffAlgorithm 


Select the Diff algorithm to use when comparing documents. This property has the options listed in the 
following table. 


VALUE DESCRIPTION 


Auto Let the XML task determine whether to use the fast or 
precise algorithm. 


Fast Use a fast, but less precise Diff algorithm. 
Precise Use a precise Diff algorithm. 
Diff Options 


Set the Diff options to apply to the Diff operation. The options are listed in the following table. 


VALUE DESCRIPTION 


IgnoreXMLDeclaration Specify whether to compare the XML declaration. 

IgnoreDTD Specify whether to ignore the document type definition 
(DTD). 

IgnoreWhite Spaces Specify whether to ignore differences in the amount of white 


space when comparing documents. 


IgnoreNamespaces Specify whether to compare the namespace uniform 
resource identifier (URI) of an element and its attribute 
names. 


Note: If this option is set to True, two elements that have 


the same local name but different namespaces are 
considered identical. 


IgnoreProcessingInstructions Specify whether to compare processing instructions. 


IgnoreOrderOf ChildElements Specify whether to compare the order of child elements. 


Note: If this option is set to True, child elements that differ 
only in their position in a list of siblings are considered 


identical. 
IgnoreComments Specify whether to compare comment nodes. 
IgnorePrefixes Specify whether to compare prefixes of element and 


attribute names. 
Note: If you set this option to True, two elements that have 


the same local name, but different namespace URIs and 
prefixes, are considered identical. 


FailOnDifference 
Specify whether the task fails if the Diff operation fails. 


SaveDiffGram 
Specify whether to save the comparison result, a DiffGram document. 


SaveOperationResult 
Specify whether the XML task saves the output of the Diff operation. 


OverwriteDestination 
Specify whether to overwrite the destination file or variable. 


Destination 
If DestinationType is set to File connection, select a File connection manager, or click <New connection...> 


to create a new connection manager. 
Related Topics: File Connection Manager, File Connection Manager Editor 


lf DestinationType is set to Variable, select an existing variable, or click <New variable...> to create a new 
variable. 


Related Topics: Integration Services (SSIS) Variables, Add Variable. 


DestinationType 


Select the destination type of the XML document. This property has the options listed in the following table. 


VALUE DESCRIPTION 
File connection Select a file that contains the XML document. 
Variable Set the source to a variable that contains the XML 
document. 
SecondOperandType 


Select the destination type of the XML document. This property has the options listed in the following table. 


VALUE DESCRIPTION 
Direct input Set the source to an XML document. 
File connection Select a file that contains the XML document. 
Variable Set the source to a variable that contains the XML 
document. 
SecondOperand 


If SecondOperandType is set to Direct input, provide the XML code or click the ellipsis button (...) and then 
provide the XML by using the Document Source Editor dialog box. 


If SecondOperandType is set to File connection, select a File connection manager, or click <New 
connection...> to create a new connection manager. 


Related Topics: File Connection Manager, File Connection Manager Editor 


If SecondOperand Type is set to Variable, select an existing variable, or click <New variable...> to create a 
new variable. 


Related Topics: Integration Services (SSIS) Variables, Add Variable 


OperationType = Patch 
Specify options for the Patch operation. 


SaveOperationResult 
Specify whether the XML task saves the output of the Patch operation. 


OverwriteDestination 
Specify whether to overwrite the destination file or variable. 


Destination 
lf DestinationType is set to File connection, select a File connection manager, or click <New connection...> 
to create a new connection manager. 


Related Topics: File Connection Manager, File Connection Manager Editor 


lf DestinationType is set to Variable, select an existing variable, or click <New variable...> to create a new 
variable. 


Related Topics: Integration Services (SSIS) Variables, Add Variable. 


DestinationType 
Select the destination type of the XML document. This property has the options listed in the following table. 


VALUE DESCRIPTION 


File connection Select a file that contains the XML document. 
Variable Set the source to a variable that contains the XML 
document. 
SecondOperandType 


Select the destination type of the XML document. This property has the options listed in the following table. 


VALUE DESCRIPTION 
Direct input Set the source to an XML document. 
File connection Select a file that contains the XML document. 
Variable Set the source to a variable that contains the XML 
document. 
SecondOperand 


If SecondOperandType is set to Direct input, provide the XML code or click the ellipsis button (...) and then 
provide the XML by using the Document Source Editor dialog box. 


If SecondOperandType is set to File connection, select a File connection manager, or click <New 
connection...> to create a new connection manager. 


Related Topics: File Connection Manager, File Connection Manager Editor 


If SecondOperand Type is set to Variable, select an existing variable, or click <New variable...> to create a 
new variable. 


Related Topics: Integration Services (SSIS) Variables, Add Variable 


Validate XML with the XML Task 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 
Validate XML documents and get rich error output by enabling the ValidationDetails property of the XML Task. 


The following screenshot shows the XML Task Editor with the settings required for XML validation with rich 
error output. 





{XML Task Editor - Tat el 
(=) Configure the properties used to apply an XML operation to a retrieved XML document. 
(2) General « Input 
@) Expressions OperationType Validate 
SourceType File connection 
Source XMLDestination.xml 
« Output 
SaveOperationResult True 
. 
DestinationType File Connection 
Destination XMLValidation.txt 
OverwriteDestination True 
+ Second Operand 
SecondOperandType File connection 
SecondOperand XMLValidation.xsd 
+ Validation Options 
ValidationType xsd 
FailOnValidationFail False 
OperationResult 
Specifies the options for saving the results of the operation. 
OK Cancel r Help 








Before the ValidationDetails property was available, XML validation by the XML Task returned only a true or 
false result, with no information about errors or their locations. Now, when you set ValidationDetails to True, 
the output file contains detailed information about every error including the line number and the position. You 
can use this information to understand, locate, and fix errors in XML documents. 


The XML validation functionality scales easily for large XML documents and large numbers of errors. Since the 
output file itself is in XML format, you can query and analyze the output. For example, if the output contains a 
large number of errors, you can group the errors by using a Transact-SQL query, as described in this topic. 





NOTE 


SQL Server Integration Services ( SSIS) introduced the ValidationDetails property in SQL Server 2012 (11.x) Service 
Pack 2. The property is also available in SQL Server 2014 (12.x) and in SQL Server 2016 (13.x). 





Sample output for XML that's valid 


Here is a sample output file with validation results for a valid XML file. 





<root xmlns:ns="https://schemas.microsoft.com/xmltools/2002/xmlvalidation"> 
<metadata> 
<result>true</result> 
<errors>®@</errors> 
<warnings>@</warnings> 
<startTime>2015-05-28T10:27:22.087</startTime> 
<endTime>2015-@5-28T10:29:07.007</endTime> 
<xmlFile>d:\Temp\TestData.xml</xmlFile> 
<xsdFile>d:\Temp\TestSchema. xsd</xsdFile> 
</metadata> 
<messages /> 
</root> 


Sample output for XML that's not valid 


Here is a sample output file with validation results for an XML file that contains a small number of errors. The 
text of the <error> elements has been wrapped for readability. 


<root xmlns:ns="https://schemas.microsoft.com/xmltools/2002/xmlvalidation"> 
<metadata> 

<result>false</result> 
<errors>2</errors> 
<warnings>@</warnings> 
<startTime>2015 -05-28T10:45:09.538</startTime> 
<endTime>2015-@5-28T10:45:09.558</endTime> 
<xmlFile>C:\Temp\TestData. xml</xmlFile> 
<xsdFile>C:\Temp\TestSchema. xsd</xsdFile> 


</metadata> 
<messages> 
<error line="5" position="26">The 'ApplicantRole' element is invalid - The value ‘wer3' is invalid 
according to its datatype 'ApplicantRoleType' - The Enumeration constraint failed.</error> 
<error line="16" position="28">The ‘Phone’ element is invalid - The value ‘we3@56666666' is invalid 
according to its datatype ‘phone’ - The Pattern constraint failed.</error> 
</messages> 
</root> 
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Analyze XML validation output with a Transact-SQL query 


If the output of XML validation contains a large number of errors, you can use a Transact-SQL query to load the 
output in SQL Server Management Studio. Then you can analyze the error list with all the capabilities of the T- 
SQL language including WHERE, GROUP BY, ORDER BY, JOIN, and so forth. 


DECLARE @xml XML; 


SELECT @xml = Xml1Doc 
FROM OPENROWSET (BULK N'C:\Temp\XMLValidation_2016-02-212T10-41-00.xml', SINGLE_BLOB) AS Tab(XmlDoc) ; 


-- Query #1, flat list of errors 
-- convert to relational/rectangular 
3;WITH XMLNAMESPACES ('‘https://schemas.microsoft.com/xmltools/2002/xmlvalidation' AS ns), rs AS 
( 
SELECT col.value('@line','INT') AS line 

, col.value('@position','INT') AS position 

,» col.value('.','VARCHAR(1024)') AS error 
FROM @XML.nodes('/root/messages/error') AS tab(col) 
) 
SELECT * FROM rs: 
-- WHERE error LIKE '%whatever_string%' 


-- Query # 2, count of errors grouped by the error message 
-- convert to relational/rectangular 
3;WITH XMLNAMESPACES ('‘https://schemas.microsoft.com/xmltools/2002/xmlvalidation’' AS ns), rs AS 
( 
SELECT col.value('@line','INT') AS line 
» col.value('@position','INT') AS position 
,» col.value('.','VARCHAR(1024)') AS error 
FROM @XML.nodes('/root/messages/error') AS tab(col) 
) 
SELECT COALESCE(error, 'Total # of errors:') AS [error], COUNT(*) AS [counter] 
FROM rs 
GROUP BY GROUPING SETS ((error), ()) 
ORDER BY 2 DESC, COALESCE(error, 'Z'); 


Here is the result in Management Studio of the second sample query shown in the preceding text. 





DECLARE @xml XML; + 


SELECT @xml = XmlDoc 
FROM OPENROWSET (BULK N'd:\Temp\idl189_PY201509_SubsidyTrackingFact_RECEIPT_2015-10-22T10-18-54.xml', SINGLE_BLOB) AS Tab(XmUDoc) ; 


- convert to relational/rectangular 
;WITH XMLNAMESPACES ( ‘http://schemas microsoft, com/xmltoo1s/2002/xmivalidation® AS ns), rs AS 


SELECT col.value('@line’, "INT') AS line 
, Col. value(‘@position’, INT’) AS position 
, col.value(’.*, 'VARCHAR(1024)") AS error 
FROM @XML.nodes('/root/messages/error') AS tab(col) 


) 

SELECT COALESCE(error, ‘Total # of errors:") AS [error], COUNT(*) AS [counter] 
FROM rs 

GROUP BY GROUPING SETS ((error), | 

ORDER BY 2 DESC, COALESCE(error, ‘Z° 
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2 Clement MonthiyPaymert does not seesty assertion ¢ (abs(ConbutonMargn - (GrossMargn - SslesMarketngCost)) ke 0 2248 
3 Element ¢ dows not setety essertion, Fuse #6: The ElapsedMorths value shell be Date minus ContrectEtectveDete in # of S867 
4 Bement r does not satsty assertion. Fuse #16: The SubsidpAmount valve shel be greater than zero for new Subse cfm S476 
5 The content “MIGRATION” of element <Subsidy Type? does not match the required senple type Value “MIGRATION” contre m2 
6 Element MonthyPeymert does not ssesty assecton ¢ (abs(GrossMargin - (Revenue - DrectCost)) le 0 01 } then trve() ete 403 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Precedence constraints link executables, containers, and tasks in packages in a control flow, and specify 
conditions that determine whether executables run. An executable can be a For Loop, Foreach Loop, or Sequence 
container; a task; or an event handler. Event handlers also use precedence constraints to link their executables 
into a control flow. 


A precedence constraint links two executables: the precedence executable and the constrained executable. The 
precedence executable runs before the constrained executable, and the execution result of the precedence 
executable may determine whether the constrained executable runs. The following diagram shows two 
executables linked by a precedence constraint. 


[seriot Task 


Script Task 


In a linear control flow, that is, one without branching, precedence constraints alone govern the sequence in 





which tasks run. If a control flow branches, the Integration Services run-time engine determines the execution 
order among the tasks and containers that immediately follow the branching. The run-time engine also 
determines execution order among unconnected workflows in a control flow. 


The nested-container architecture of Integration Services enables all containers, except for the task host 
container that encapsulates only a single task, to include other containers, each with its own control flow. The 
For Loop, Foreach Loop, and Sequence containers can include multiple tasks and other containers, which in turn 
can include multiple tasks and containers. For example, a package with a Script task and a Sequence container 
has a precedence constraint that links the Script task and the Sequence container. The Sequence container 
includes three Script tasks, and its precedence constraints link the three Script tasks into a control flow. The 
following diagram shows the precedence constraints in a package with two levels of nesting. 
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Because the package is at the top of the SSIS container hierarchy, multiple packages cannot be linked by 
precedence constraints; however, you can add an Execute Package task to a package and indirectly link another 
package into the control flow. 


You can configure precedence constraints in the following ways: 


e Specify an evaluation operation. The precedence constraint uses a constraint value, an expression, both, 
or either to determine whether the constrained executable runs. 


e If the precedence constraint uses an execution result, you can specify the execution result to be success, 
failure, or completion. 


e If the precedence constraint uses an evaluation result, you can provide an expression that evaluates to a 


Boolean. 


e Specify whether the precedence constraint is evaluated singly or together with other constraints that 
apply to the constrained executable. 


Evaluation Operations 
Integration Services provides the following evaluation operations: 


e Aconstraint that uses only the execution result of the precedence executable to determine whether the 
constrained executable runs. The execution result of the precedence executable can be completion, 
success, or failure. This is the default operation. 


e Anexpression that is evaluated to determine whether the constrained executable runs. If the expression 
evaluates to true, the constrained executable runs. 


e An expression and a constraint that combines the requirements of execution results of the precedence 
executable and the return results of evaluating the expression. 


e Anexpression or a constraint that uses either the execution results of the precedence executable or the 


return results of evaluating the expression. 


SSIS Designer uses color to identify the type of precedence constraint. The Success constraint is green, the 
Failure constraint is red, and the Completion constraint is blue. To display text labels in SSIS designer that show 
the type of the constraint, you must configure the accessibility features of SSIS Designer. 


The expression must be a valid SSIS expression, and it can include functions, operators, and system and custom 
variables. For more information, see Integration Services (SSIS) Expressions and Integration Services (SSIS) 
Variables. 


Execution Results 


The precedence constraint can use the following execution results alone or in combination with an expression. 


e Completion requires only that the precedence executable has completed, without regard to outcome, in 
order for the constrained executable to run. 


e Success requires that the precedence executable must complete successfully for the constrained 
executable to run. 


e Failure requires that the precedence executable fail for the constrained executable to run. 


NOTE 


Only precedence constraints that are members of the same Precedence Constraint collection can be grouped in a 


logical AND condition. For example, you cannot combine precedence constraints from two Foreach Loop containers. 





Set the properties of a precedence constraint with the Precedence 
Constraint Editor 


1. In SQL Server Data Tools (SSDT), open the Integration Services project that contains the package you 
want. 


2. In Solution Explorer, double-click the package to open it. 


3. Click the Control Flow tab. 


4. Double-click the precedence constraint. 
The Precedence Constraint Editor opens. 
5. In the Evaluation operation drop-down list, select an evaluation operation. 
6. In the Value drop-down list, select the execution result of the precedence executable. 


7. If the evaluation operation uses an expression, in the Expression box, type an expression, and click Test 
to evaluate the expression. 





NOTE 


Variable names are case-sensitive. 





8. If multiple tasks or containers are connected to the constrained executable, select Logical AND to specify 
that the execution results of all preceding executables must evaluate to true. Select Logical OR to 
specify that only one execution result must evaluate to true. 


9. Click OK to close the Precedence Constraint Editor. 


10. To save the updated package, click Save Selected Items on the File menu. 


Precedence Constraint Editor 


Use the Precedence Constraint Editor dialog box to configure precedence constraints. 


Options 

Evaluation operation 

Specify the evaluation operation that the precedence constraint uses. The operations are: Constraint, 
Expression, Expression and Constraint, and Expression or Constraint. 


Value 


Specify the constraint value: Success, Failure, or Completion. 





NOTE 


The precedence constraint line is green for Success, highlighted for Failure, and blue for Completion. 





Expression 
If using the operations Expression, Expression and Constraint, or Expression or Constraint, type an 


expression or launch the Expression Builder to create the expression. The expression must evaluate to a Boolean. 


Test 
Validate the expression. 


Logical AND 
Select to specify that multiple precedence constraints on the same executable must be evaluated together. All 


constraints must evaluate to True. 





NOTE 


This type of precedence constraint appears as a solid green, highlighted or blue line. 





Logical OR 
Select to specify that multiple precedence constraints on the same executable must be evaluated together. At 


least one constraint must evaluate to True. 





NOTE 


This type of precedence constraint appears as a dotted green, highlighted, or blue line. 





Set the properties of a precedence constraint in Properties window 


1. In SQL Server Data Tools (SSDT), open the Integration Services project that contains the package you 
want to modify. 


2. In Solution Explorer, double-click the package to open it. 


3. Click the Control Flow tab. On the design surface of the Control Flow tab, right-click the precedence 
constraint, and then click Properties. In the Properties window, modify the property values. 


4. In the Properties window, set the following read/write properties of precedence constraints: 


READ/WRITE PROPERTY CONFIGURATION ACTION 
Description Provide a description. 
EvalOp Select an evaluation operation. If the Expression, 


ExpressionAndConstant, or ExpressionOrConstant 
operation is selected, you can specify an expression. 


Expression If the evaluation operation includes and expression, 
provide an expression. The expression must evaluate to a 
Boolean. For more information about the expression 
language, see Integration Services (SSIS) Expressions. 


LogicalAnd Set LogicalAnd to specify whether the precedence 
constraint is evaluated in concert with other precedence 
constraints, when multiple executables precede and are 
linked to the constrained executable 


Name Update the name of the precedence constraint. 


ShowAnnotation Specify the type of annotation to use. Choose Never to 
disable annotations, AsNeeded to enable annotation on 
demand, ConstraintName to automatically annotate 
using the value of the Name property, 
ConstraintDescription to automatically annotate 
using the value of the Description property, and 
ConstraintOptions to automatically annotate using 
the values of the Value and Expression properties. 


Value If the evaluation operation specified in the EvalOP 
property includes a constraint, select the execution result 
of the constraining executable. 


5. Close the Properties window. 


6. To save the updated package, click Save Selected Items on the File menu. 


Set the value of a precedence constraint with the shortcut menu 


1. In SQL Server Data Tools (SSDT), open the Integration Services project that contains the package you 


want. 
2. In Solution Explorer, double-click the package to open it. 
3. Click the Control Flow tab. 


4. On the design surface of the Control Flow tab, right-click the precedence constraint, and then click 
Success, Failure, or Completion. 


5. To save the updated package, click Save Selected Item on the File menu. 


Add expressions to precedence constraints 


A precedence constraint can use an expression to define the constraint between two executables: the precedence 
executable and the constrained executable. The executables can be tasks or containers. The expression can be 
used alone or in combination with the execution result of the precedence executable. The execution result of an 
executable is either success or failure. When you configure the execution result of a precedence constraint, you 
can set the execution result to Success, Failure, or Completion. Success requires that the precedence 
executable succeed, Failure requires that the precedence executable fail, and Completion indicates that the 
constrained executable should run regardless of whether the precedence task succeeds or fails. For more 


information, see Precedence Constraints. 


The expression must evaluate to True or False and it must be a valid Integration Services expression. The 
expression can use literals, system and custom variables, and the functions and operators that the SSIS 
expression grammar provides. For example, the expression @count == SQRT(144) + 10 uses the variable Count, 
the SQRT function , and the equal (==) and add (+) operators. For more information, see Integration Services 
(SSIS) Expressions. 


In the following illustration, task A and task B are linked by a precedence constraint that uses an execution result 
and an expression. The constraint value is set to Success and the expression is @x >== @z . Task B, the 
constrained task, runs only if task A completes successfully and the value of variable X is greater than or equal 
to the value of variable Z. 


Success and X>=Z 


Executables can also be linked by using multiple precedence constraints that contain different expressions. For 
example, in the following illustration, tasks B and C are linked to task A by precedence constraints that use 
execution results and expressions. Both of the constraint values are set to Success. One precedence constraint 
includes the expression @x >== @z , and the other precedence constraint includes the expression @x < @Zz. 
Depending on the values of variable X and variable Z, either task C or task B runs. 






Success and X>Z Success and X< Z 


You can add or modify an expression by using the Precedence Constraint Editor in SSIS Designer and the 
Properties window that SQL Server Data Tools (SSDT) provides. However, the Properties window does not 
provide verification of the expression syntax. 


If a precedence constraint includes an expression, an icon appears on the design surface of the Control Flow 
tab, next to the precedence constraint, and the ToolTip on the icon displays the expression. 


Add an expression to a precedence constraint 


1. In SQL Server Data Tools (SSDT), open the Integration Services project that contains the package you 
want. 


2. In Solution Explorer, double-click the package to open it. 
3. Click the Control Flow tab. 


4. On the design surface of the Control Flow tab, double-click the precedence constraint. The Precedence 
Constraint Editor opens. 


5. Select Expression, Expression and Constraint, or Expression or Constraint in the Evaluation 
operation list. 


6. Type an expression in the Expression text box or launch the Expression Builder to create an expression. 
7. To validate the expression syntax, click Test. 
8. To save the updated package, click Save Selected Items on the File menu. 


Combine execution values and expressions 


The following table describes the effects of combining an execution value constraint and an expression in a 
precedence constraint. 


CONSTRAINT EVALUATES CONSTRAINED 
EVALUATION OPERATION TO EXPRESSION EVALUATES TO EXECUTABLE RUNS 
Constraint True N/A True 
Constraint False N/A False 
Expression N/A True True 
Expression N/A False False 
Constraint and Expression True True True 
Constraint and Expression True False False 
Constraint and Expression False True False 
Constraint and Expression False False False 
Constraint or Expression True True True 
Constraint or Expression True False True 
Constraint or Expression False True True 
Constraint or Expression False False False 


Complex constraint scenarios with multiple precedence constraints 


A precedence constraint connects two executables: two tasks, two containers, or one of each. They are known as 
the precedence executable and the constrained executable. A constrained executable can have multiple 
precedence constraints. For more information, see Precedence Constraints. 


Assembling complex constraint scenarios by grouping constraints enables you to implement complex control 
flow in packages. For example, in the following illustration, Task D is linked to Task A by a Success constraint, 
Task D is linked to Task B by a Failure constraint, and Task D is linked to Task C by a Success constraint. The 


precedence constraints between Task D and Task A, between Task D and Task B, and between Task D and Task C 
participate in a logical and relationship. Therefore, for Task D to run, Task A must run successfully, Task B must 
fail, and Task C must run successfully. 





LogicalAnd Property 


If a task or a container has multiple constraints, the LogicalAnd property specifies whether a precedence 
constraint is evaluated singly or in concert with other constraints. 


You can set the LogicalAnd property using the Precedence Constraint Editor in SSIS Designer, or in the 
Properties window that SQL Server Data Tools (SSDT) provides. 


Set the default value for precedence constraints 


When you first use SSIS Designer, the default value of a precedence constraint is Success. Follow these steps to 
configure SSIS Designer to use a different default value for precedence constraints. 


1. Open SQL Server Data Tools (SSDT). 
2. On the Tools menu, click Options. 


3. In the Options dialog box, expand Business Intelligence Designers, and then expand Integration 
Services Designers. 


4. Click Control Flow Auto Connect and select Connect a new shape to the selected shape by 
default. 


5. In the drop-down list, choose either Use a Failure constraint for the new shape or Use a 
Completion constraint for the new shape. 


6. Click OK. 


Create a default precedence constraint 


1. In SQL Server Data Tools (SSDT), open the Integration Services project that contains the package you 


want. 
2. In Solution Explorer, double-click the package to open it. 
3. Click the Control Flow tab. 


4. On the design surface of the Control Flow tab, click the task or container and drag its connector to the 
executable to which you want the precedence constraint to apply. 


5. To save the updated package, click Save Selected Items on the File menu. 


Data Flow 


11/23/2021 * 14 minutes to read « Edit Online 





Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


SQL Server Integration Services provides three different types of data flow components: sources, 
transformations, and destinations. Sources extract data from data stores such as tables and views in relational 
databases, files, and Analysis Services databases. Transformations modify, summarize, and clean data. 
Destinations load data into data stores or create in-memory datasets. 





NOTE 


When you use custom providers, you need to update the ProviderDescriptors.xml file with the metadata column values. 











Additionally, Integration Services provides paths that connect the output of one component to the input of 
another component. Paths define the sequence of components, and let you add annotations to the data flow or 
view the source of the column. 


You connect data flow components by connecting the output of sources and destinations to the input of 
transformations and destinations. When constructing a data flow you typically connect the second and 
subsequent components as you add them to the data flow. After you connect the component, the input columns 
are available for use in configuring the component. When no input columns are available, you will have to 
complete the configuration of the component after it is connected to the data flow. For more information, see 
Integration Services Paths and Connect Components with Paths. 


The following diagram shows a data flow that has a source, a transformation with one input and one output, and 
a destination. The diagram includes the inputs, outputs, and error outputs in addition to the input, output, and 


external columns. 
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Data Flow Implementation 


Adding a Data Flow task to the control flow of a package is the first step in implementing a data flow in a 
package. A package can include multiple Data Flow tasks, each with its own data flow. For example, if a package 
requires that data flows be run in a specified sequence, or that other tasks be performed between the data flows, 
you must use a separate Data Flow task for each data flow. 


After the control flow includes a Data Flow task, you can begin to build the data flow that a package uses. For 
more information, see Data Flow Task. 


Creating a data flow includes the following steps: 


e Adding one or more sources to extract data from files and databases, and add connection managers to 
connect to the sources. 


e Adding the transformations that meet the business requirements of the package. A data flow is not 
required to include transformations. 


Some transformations require a connection manager. For example, the Lookup transformation uses a 
connection manager to connect to the database that contains the lookup data. 


e Connecting data flow components by connecting the output of sources and transformations to the input 
of transformations and destinations. 


e Adding one or more destinations to load data into data stores such as files and databases, and adding 
connection managers to connect to the data sources. 


e Configuring error outputs on components to handle problems. 


At run time, row-level errors may occur when data flow components convert data, perform a lookup, or 
evaluate expressions. For example, a data column with a string value cannot be converted to an integer, 
or an expression tries to divide by zero. Both operations cause errors, and the rows that contain the errors 
can be processed separately using an error flow. For more information about how to use error flows in 
package data flow, see Error Handling in Data. 


e Include annotations to make the data flow self-documenting. For more information, see Use Annotations 
in Packages. 





NOTE 


When you create a new package, you can also use a wizard to help you configure connection managers, sources, and 
destinations correctly. For more information, see Create Packages in SQL Server Data Tools. 











When the Data Flow tab is active, the Toolbox contains the sources, transformations, and destinations that you 
can add to the data flow. 


Expressions 


A number of the data flow components-sources, transformations, and destinations-support the use of property 
expressions in some of their properties. A property expression is an expression that replaces the value of the 
property when the package is loaded. At run time, the package uses the updated property values. The 
expressions are built using the Integration Services expression syntax and can include Integration Services 
functions, operators, identifiers, and variables. For more information, see Integration Services (SSIS) Expressions, 


Integration Services (SSIS) Expressions, and Use Property Expressions in Packages. 


If you construct a package in SQL Server Data Tools (SSDT), the properties of any data flow components that 
support property expressions are exposed on the Data Flow task to which they belong. To add, change, and 


remove the property expressions of data flow components, click the Data Flow task, and then use the Properties 
window or the editor for the task to add, change, or delete property expressions. Property expressions for the 
Data Flow task itself are managed in the Properties window. 


If the data flow contains any components that use expressions, the expressions are also exposed in the 
Properties window. To view expressions, select the Data Flow task to which the component belongs. You can 
view properties by categories, or in alphabetical order. If you use the categorized view in the Properties window, 
any expressions that are not used in a specific property are listed in the Misc category. If you use the 
alphabetical view, expressions are listed in order of the name of the data flow component. 


Sources 


In Integration Services, a source is the data flow component that makes data from different external data 
sources available to the other components in the data flow. You can extract data from flat files, XML files, 
Microsoft Excel workbooks, and files that contain raw data. You can also extract data by accessing tables and 


views in databases and by running queries. 
A data flow can include a single source or multiple sources. 


The source for a data flow typically has one regular output. The regular output contains output columns, which 
are columns the source adds to the data flow. 


The regular output references external columns. An external column is a column in the source. For example, the 
MadeFlag column in the Product table of the AdventureWorks database is an external column that can be 
added to the regular output. Metadata for external columns includes such information as the name, data type, 
and length of the source column. 


An error output for a source contains the same columns as the regular output, and also contains two additional 
columns that provide information about errors. The Integration Services object model does not restrict the 
number of regular outputs and error outputs that sources can have. Most of the sources that Integration 
Services includes, except the Script component, have one regular output, and many of the sources have one 


error output. Custom sources can be coded to implement multiple regular outputs and error outputs. 
All the output columns are available as input columns to the next data flow component in the data flow. 


You can also write custom sources. For more information, see Developing a Custom Data Flow Component and 
Developing Specific Types of Data Flow Components. 


The following sources have properties that can be updated by property expressions: 

e ADO NET Source 

e XML Source 

Sources Available for Download 

The following table lists additional sources that you can download from the Microsoft website. 


SOURCE DESCRIPTION 


Oracle Source The Oracle source is the source component of the Microsoft 
Connector for Oracle by Attunity. The Microsoft Connector 
for Oracle by Attunity also includes a connection manager 
and a destination. For more information, see the download 
page, Microsoft Connectors for Oracle and Teradata by 
Attunity. 


SOURCE DESCRIPTION 


SAP BI Source The SAP BI source is the source component of the Microsoft 
Connector for SAP BI. The Microsoft Connector for SAP BI 
also includes a connection manager and a destination. For 
more information, see the download page, Microsoft SQL 
Server Feature Pack. 


Teradata Source The Teradata source is the source component of the 
Microsoft Connector for Teradata by Attunity. The Microsoft 
Connector for Teradata by Attunity also includes a 
connection manager and a destination. For more 
information, see the download page, Microsoft Connectors 
for Oracle and Teradata by Attunity. 


For a demonstration on how to leverage the performance gains of the Microsoft Connector for Oracle by 
Attunity, see Performance of Microsoft Connector for Oracle by Attunity (SQL Server Video). 


Transformations 


The capabilities of transformations vary broadly. Transformations can perform tasks such as updating, 
summarizing, cleaning, merging, and distributing data. You can modify values in columns, look up values in 
tables, clean data, and aggregate column values. 


The inputs and outputs of a transformation define the columns of incoming and outgoing data. Depending on 
the operation performed on the data, some transformations have a single input and multiple outputs, while 
other transformations have multiple inputs and a single output. Transformations can also include error outputs, 
which provide information about the error that occurred, together with the data that failed: For example, string 
data that could not be converted to an integer data type. The Integration Services object model does not restrict 
the number of inputs, regular outputs, and error outputs that transformations can contain. You can create 


custom transformations that implement any combination of multiple inputs, regular outputs, and error outputs. 


The input of a transformation is defined as one or more input columns. Some Integration Services 
transformations can also refer to external columns as input. For example, the input to the OLE DB Command 
transformation includes external columns. An output column is a column that the transformation adds to the 
data flow. Both regular outputs and error outputs contain output columns. These output columns in turn act as 
input columns to the next component in the data flow, either another transformation or a destination. 


The following transformations have properties that can be updated by property expressions: 
e Conditional Split Transformation 

e Derived Column Transformation 

e Fuzzy Grouping Transformation 

e Fuzzy Lookup Transformation 

e OLE DB Command Transformation 

e Percentage Sampling Transformation 

e Pivot Transformation 

e Row Sampling Transformation 

e Sort Transformation 


e Unpivot Transformation 


For more information, see Integration Services Transformations. 


Destinations 


A destination is the data flow component that writes the data from a data flow to a specific data store, or creates 
an in-memory dataset. You can load data into flat files, process analytic objects, and provide data to other 
processes. You can also load data by accessing tables and views in databases and by running queries. 


A data flow can include multiple destinations that load data into different data stores. 


An Integration Services destination must have at least one input. The input contains input columns, which come 


from another data flow component. The input columns are mapped to columns in the destination. 


Many destinations also have one error output. The error output for a destination contains output columns, 
which typically contain information about errors that occur when writing data to the destination data store. 
Errors occur for many different reasons. For example, a column may contain a null value, whereas the 


destination column cannot be set to null. 


The Integration Services object model does not restrict the number of regular inputs and error outputs that 
destinations can have, and you can create custom destinations that implement multiple inputs and error 


outputs. 


You can also write custom destinations. For more information, see Developing a Custom Data Flow Component 


and Developing Specific Types of Data Flow Components. 

The following destinations have properties that can be updated by property expressions: 
e Flat File Destination 

e SQL Server Compact Edition Destination 


Destinations Available for Download 


The following table lists additional destinations that you can download from the Microsoft website. 
SOURCE DESCRIPTION 


Oracle Destination The Oracle destination is the destination component of the 
Microsoft Connector for Oracle by Attunity. The Microsoft 
Connector for Oracle by Attunity also includes a connection 
manager and a source. For more information, see the 
download page, Microsoft Connectors for Oracle and 
Teradata by Attunity. 


SAP BI Destination The SAP BI destination is the destination component of the 
Microsoft Connector for SAP BI. The Microsoft Connector for 
SAP BI also includes a connection manager and a source. For 
more information, see the download page, Microsoft SQL 
Server Feature Pack. 


Teradata Destination The Teradata destination is the destination component of the 
Microsoft Connector for Teradata by Attunity. The Microsoft 
Connector for Teradata by Attunity also includes a 
connection manager and a source. For more information, see 
the download page, Microsoft Connectors for Oracle and 
Teradata by Attunity. 


For a demonstration on how to leverage the performance gains of the Microsoft Connector for Oracle by 
Attunity, see Performance of Microsoft Connector for Oracle by Attunity (SQL Server Video). 


Connection Managers 


Many data flow components connect to data sources, and you must add the connection managers that the 
components require to the package before the component can be configured correctly. You can add the 
connection managers as you construct the data flow, or before you start to construct the data flow. For more 
information, see Integration Services (SSIS) Connections and Create Connection Managers. 


External Metadata 


When you create a data flow in a package using SSIS Designer, the metadata from the sources and destinations 
is copied to the external columns on sources and destinations, serving as a snapshot of the schema. When 
Integration Services validates the package, SSIS Designer compares this snapshot against the schema of the 
source or destination, and posts errors and warnings, depending on the changes. 


The Integration Services project provides an offline mode. When you work offline no connections are made to 


the sources or destinations the package uses, and the metadata of external columns is not updated. 


Inputs and Outputs 


Sources have outputs, destinations have inputs, and transformations have both inputs and outputs. Additionally, 
many data flow components can be configured to use an error output. 


Inputs 


Destinations and transformations have inputs. An input contains one or more input columns, which can refer to 
external columns if the data flow component has been configured to use them. Inputs can be configured to 
monitor and control the flow of data: For example, you can specify if the component should fail in response to 
an error, ignore errors, or redirect error rows to the error output. You can also assign a description to the input 
or update the input name. In SSIS Designer, inputs are configured by using the Advanced Editor dialog box. 
For more information about the Advanced Editor, see Integration Services User Interface. 


Outputs 


Sources and transformations always have outputs. An output contains one or more output columns, which can 
refer to external columns if the data flow component has been configured to use them. Outputs can be 
configured to provide information useful to downstream processing of the data. For example, you can indicate 
whether the output is sorted. You can also provide a description for the output, or update the output name. In 
SSIS Designer, outputs are configured by using the Advanced Editor dialog box. 


Error Outputs 


Sources, destinations, and transformations can include error outputs. You can specify how the data flow 
component responds to errors in each input or column by using the Configure Error Output dialog box. If an 
error or data truncation occurs at run time and the data flow component is configured to redirect rows, the data 
rows with the error are sent to the error output. The error output can be connected to transformations that 
apply additional transformations or direct data to a different destination. By default, an error output contains the 
output columns and two error columns: ErrorCode and ErrorColumn. The output columns contain the data 
from the row that failed, ErrorCode provides the error code, and ErrorColumn identifies the failing column. 


For more information, see Error Handling in Data. 


Columns 


Inputs, outputs, and error outputs are collections of columns. Each column is configurable and depending on the 
column type-input, output, or external- Integration Services provides different properties for the column. 
Integration Services provides three different ways of setting column properties: programmatically, by using 
component-specific dialog boxes, or by using the Advanced Editor dialog box. 


Paths 


Paths connect data flow components. In SSIS Designer, you can view and modify the path properties, view the 
output metadata for the path start point, and attach data viewers to a path. 


For more information, see Integration Services Paths and Debugging Data Flow. 


Configuration of Data Flow Components 


Data flow components can be configured at the component level; at the input, output, and error output levels; 
and at the column level. 


e Atthe component level, you set properties that are common to all components, and you set the custom 
properties of the component. 


e At the input, output, and error output levels, you set the common properties of inputs, outputs, and the 
error output. If the component supports multiple outputs, you can add outputs. 


e@ At the column level, you set the properties that are common to all columns, in addition to any custom 
properties that the component provides for columns. If the component supports the addition of output 
columns, you can add columns to outputs. 


You can set properties through SSIS Designer or programmatically. In SSIS Designer, you can set element 
properties using the custom dialog boxes provided for each element type, or by using the Properties window or 
the Advanced Editor dialog box. 


For more information about how to set properties by using SSIS Designer, see Set the Properties of a Data Flow 
Component. 


Related Tasks 


Add or Delete a Component in a Data Flow 


Connect Components in a Data Flow 


Related Content 


Video, Performance of Microsoft Connector for Oracle by Attunity (SQL Server Video), on technet.microsoft.com. 


Data in Data Flows 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Integration Services provides a set of data types that are used in data flows. 


Data Type Conversion 


The source that you add to a data flow converts the source data to Integration Services data types. Subsequent 
transformations may convert the data to different Integration Services data types, and depending on the type of 
data store into which data is loaded, destinations may convert the final Integration Services data type to the data 
type required by the destination data store. For more information, see Integration Services Data Types. 


To convert the data to an Integration Services data type, a data flow component parses the data. Integration 
Services provides two types of data parsing: fast parse and standard parse. Most data flow components can use 
only standard parsing; however, the Flat File source and the Data Conversion transformation can use either fast 
parse or standard parse. For more information, see Parsing Data. 


Data Type Comparison 


Many transformations compare data values. For example, the Aggregate transformation compares values for 
the purpose of aggregating values across a set of data rows, the Sort transformation compares values in order 
to sort them, and the Lookup transformation compares values against values in a separate reference table. To 
specify how strings should be compared, the transformation includes a set of comparison options such as 
whether to ignore case sensitivity, how to handle kana types in Japanese text, and whether to ignore white-space 
characters in the string. For more information, see Comparing String Data. 


The expression evaluator also compares data values when it evaluates the expressions that variables, 
precedence constraints, and transformations use. 


Data Flow Troubleshooting 


Once you have deployed a package to the Integration Services catalog, you can analyze the data flow in the 
package during execution to check performance or look for other issues. Standard reports are available that 
allow you to view package status and history, and you can query database views that provide detailed 
information about package execution. You also can dynamically add and remove data taps during execution to 
target specific components of your package. For more information, see Debugging Data Flow. 


Integration Services Data Types 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


When data enters a data flow in a package, the source that extracts the data converts the data to an Integration 
Services data type. Numeric data is assigned a numeric data type, string data is assigned a character data type, 
and dates are assigned a date data type. Other data, such as GUIDs and Binary Large Object Blocks (BLOBs), are 
also assigned appropriate Integration Services data types. If data has a data type that is not convertible to an 
Integration Services data type, an error occurs. 


Some data flow components convert data types between the Integration Services data types and the managed 
data types of the Microsoft .NET Framework. For more information about the mapping between Integration 
Services and managed data types, see Working with Data Types in the Data Flow. 


The following table lists the Integration Services data types. Some of the data types in the table have precision 
and scale information that applies to them. For more information about precision and scale, see Precision, Scale, 
and Length (Transact-SQL). 


DATA TYPE DESCRIPTION 
DT_BOOL A Boolean value. 
DT_BYTES A binary data value. The length is variable and the maximum 


length is 8000 bytes. 


DT_CY A currency value. This data type is an eight-byte signed 
integer with a scale of 4 and a maximum precision of 19 
digits. 

DT_DATE A date structure that consists of year, month, day, hour, 


minute, seconds, and fractional seconds. The fractional 
seconds have a fixed scale of 7 digits. 


The DT_DATE data type is implemented using an 8-byte 
floating-point number. Days are represented by whole 
number increments, starting with 30 December 1899, and 
midnight as time zero. Hour values are expressed as the 
absolute value of the fractional part of the number. However, 
a floating point value cannot represent all real values; 
therefore, there are limits on the range of dates that can be 
presented in DT_DATE. 


On the other hand, DT_DBTIMESTAMP is represented by a 
structure that internally has individual fields for year, month, 


day, hours, minutes, seconds, and milliseconds. This data 
type has larger limits on ranges of the dates it can present. 


DT_DBDATE A date structure that consists of year, month, and day. 


DT_DBTIME A time structure that consists of hour, minute, and second. 


DATA TYPE 


DT_DBTIME2 


DT_DBTIMESTAMP 


DT_DBTIMESTAMP2 


DT_DBTIMESTAMPOFFSET 


DT_DECIMAL 


DT_FILETIME 


DT_GUID 


DT_|1 


DT_l2 


DT_l4 


DT_I8 


DESCRIPTION 


A time structure that consists of hour, minute, second, and 
fractional seconds. The fractional seconds have a maximum 
scale of 7 digits. 


A timestamp structure that consists of year, month, day, 
hour, minute, second, and fractional seconds. The fractional 
seconds have a maximum scale of 3 digits. 


A timestamp structure that consists of year, month, day, 
hour, minute, second, and fractional seconds. The fractional 
seconds have a maximum scale of 7 digits. 


A timestamp structure that consists of year, month, day, 
hour, minute, second, and fractional seconds. The fractional 
seconds have a maximum scale of 7 digits. 


Unlike the DT_DBTIMESTAMP and DT_DBTIMESTAMP2 data 
types, the DT_DBTIMESTAMPOFFSET data type has a time 
zone offset. This offset specifies the number of hours and 
minutes that the time is offset from the Coordinated 
Universal Time (UTC). The time zone offset is used by the 
system to obtain the local time. 


The time zone offset must include a sign, plus or minus, to 
indicate whether the offset is added or subtracted from the 
UTC. The valid number of hours offset is between -14 and 
+14. The sign for the minute offset depends on the sign for 
the hour offset: 


If the sign of the hour offset is negative, the minute offset 
must be negative or zero. 


If the sign for the hour offset is positive, the minute offset 
must be positive or zero. 


If the sign for the hour offset is zero, the minute offset can 
be any value from negative 0.59 to positive 0.59. 


An exact numeric value with a fixed precision and a fixed 
scale. This data type is a 12-byte unsigned integer with a 
separate sign, a scale of 0 to 28, and a maximum precision of 
29. 


A 64-bit value that represents the number of 100- 
nanosecond intervals since January 1, 1601. The fractional 
seconds have a maximum scale of 3 digits. 


A globally unique identifier (GUID). 


A one-byte, signed integer. 


A two-byte, signed integer. 


A four-byte, signed integer. 


An eight-byte, signed integer. 


DATA TYPE DESCRIPTION 


DT_NUMERIC An exact numeric value with a fixed precision and scale. This 
data type is a 16-byte unsigned integer with a separate sign, 
a scale of 0 - 38, and a maximum precision of 38. 


DT_R4 A single-precision floating-point value. 
DT_R8 A double-precision floating-point value. 
DT_STR A null-terminated ANSI/MBCS character string with a 


maximum length of 8000 characters. (If a column value 
contains additional null terminators, the string will be 
truncated at the occurrence of the first null.) 


DT_UI1 A one-byte, unsigned integer. 

DT_UI2 A two-byte, unsigned integer. 

DT_UI4 A four-byte, unsigned integer. 

DT_UI8 An eight-byte, unsigned integer. 

DT_WSTR A null-terminated Unicode character string with a maximum 


length of 4000 characters. (If a column value contains 
additional null terminators, the string will be truncated at the 
occurrence of the first null.) 


DT_IMAGE A binary value with a maximum size of 2“31-1 
(2,147,483,647) bytes. . 


DT_NTEXT A Unicode character string with a maximum length of 2*30 
- 1 (1,073,741,823) characters. 


DT_TEXT An ANSI/MBCS character string with a maximum length of 
2431-1 (2,147,483,647) characters. 


Conversion of Data Types 


If the data in a column does not require the full width allocated by the source data type, you might want to 
change the data type of the column. Making each data row as narrow as possible helps optimize performance 
when transferring data because the narrower each row is, the faster the data is moved from source to 


destination. 


Integration Services includes a complete set of numeric data types, so that you can match the data type closely 
to the size of the data. For example, if the values in a column with a DT_UI8 data type are always integers 
between 0 and 3000, you can change the data type to DT_UI2. Similarly, if a column with the DT_CY data type 
can meet the package data requirements by using an integer data type instead, you can change the data type to 
DT_I4. 


You can change the data type of a column in the following ways: 


e Use an expression to implicitly convert data types. For more information, see Integration Services Data 
Types in Expressions, Integration Services Data Types in Expressions, and Integration Services (SSIS) 
Expressions. 


e Use the cast operator to convert data types. For more information, see Cast (SSIS Expression). 


e Use the Data Conversion transformation to cast the data type of a column from one data type to a 
different data type. For more information, see Data Conversion Transformation. 


e Use the Derived Column transformation to create a copy of a column that has a different data type than 


the original column. For more information, see Derived Column Transformation. 


Converting Between Strings and Date/Time Data Types 


The following table lists the results of casting or converting between date/time data types and strings: 


e When you use the cast operator or the Data Conversion transformation, the date or time type data type 
will be converted to the corresponding string format. For example, the DT_DBTIME data type will be 
converted to a string that has the format, "hh:mm:ss". 


e When you want to convert from a string to a date or time data type, the string must use the string format 
that corresponds to the appropriate date or time data type. For example, to successfully convert some 
date strings to the DT_DBDATE data type, these date strings must be in the format, "yyyy-mm-da". 


DATA TYPE STRING FORMAT 

DT_DBDATE yyyy-mm-dd 

DT_FILETIME yyyy-mm-dd hh:mmiss:fff 

DT_DBTIME hh:mmiss 

DT_DBTIME2 hh:mm:ss. fffffff] 

DT_DBTIMESTAMP yyyy-mm-dd hh:mm:ss. fff] 
DT_DBTIMESTAMP2 yyyy-mm-dd hh:mmiss[. fffffff] 
DT_DBTIMESTAMPOFFSET yyyy-mm-dd hh:mmiss[fffffff] [{+|-} hh:mm] 


In the format for DT_FILETIME and DT_DBTIMESTAMP fff is a value between 0 and 999 that represents fractional 


seconds. 


In the date format for DT_DBTIMESTAMP2, DT_DBTIME2, and DT_DBTIMESTAMPOFFSET, fffffff is a value between 
0 and 9999999 that represents fractional seconds. 


The date format for DT_DBTIMESTAMPOFFSET also includes a time zone element. There is a space between the 


time element and the time zone element. 


Converting Date/Time Data Types 


You can change the data type on a column with date/time data to extract the date or the time part of the data. 
The following tables list the results of changing from one date/time data type to another date/time data type. 


Converting from DT_FILETIME 


CONVERT DT_FILETIME TO RESULT 
DT_FILETIME No change. 


DT_DATE Converts the data type. 


CONVERT DT_FILETIME TO 


DT_DBDATE 


DT_DBTIME 


DT_DBTIME2 


DT_DBTIMESTAMP 


DT_DBTIMESTAMP2 


DT_DBTIMESTAMPOFFSET 


Converting from DT_DATE 


CONVERT DT_DATE TO 


DT_FILETIME 


DT_DATE 


DT_DBDATE 


DT_DBTIME 


DT_DBTIME2 


DT_DBTIMESTAMP 


RESULT 


Removes the time value. 


Removes the date value. 


Removes the fractional second value when its scale is greater 
than the number of fractional digits that the DT_DBTIME 
data type can contain. After removing the fractional second 
value, generates a report about this data truncation. For 
more information, see Error Handling in Data. 


Removes the date value represented by the DT_FILETIME 
data type. 


Removes the fractional second value when its scale is greater 
than the number of fractional second digits that the 
DT_DBTIME2 data type can contain. After removing the 
fractional second value, generates a report about this data 
truncation. For more information, see Error Handling in Data. 


Converts the data type. 


Removes the fractional second value when its scale is greater 
than the number of fractional second digits that the 
DT_DBTIMESTAMP2 data type can contain. After removing 
the fractional second value, generates a report about this 
data truncation. For more information, see Error Handling in 
Data. 


Sets the time zone field in the DT_DBTIMESTAMPOFFSET 
data type to zero. 


Removes the fractional second value when its scale is greater 
than the number of fractional second digits that the 
DT_DBTIMESTAMPOFFSET data type can contain. After 
removing the fractional second value, generates a report 


about this data truncation. For more information, see Error 
Handling in Data. 


RESULT 


Converts the data type. 


No change. 


Removes the time value represented by the DT_DATA data 
type. 


Removes the date value represented by the DT_DATE data 
type. 


Removes the date value represented by the DT_DATE data 
type. 


Converts the data type. 


CONVERT DT_DATE TO 


DT_DBTIMESTAMP2 


DT_DBTIMESTAMPOFFSET 


Converting from DT_DBDATE 


CONVERT DT_DBDATE TO 


DT_FILETIME 


DT_DATE 


DT_DBDATE 


DT_DBTIME 


DT_DBTIME2 


DT_DBTIMESTAMP 


DT_DBTIMESTAMP2 


DT_DBTIMESTAMPOFFSET 


Converting from DT_DBTIME 


CONVERT DT_DBTIME TO 


DT_FILETIME 


DT_DATE 


DT_DBDATE 


DT_DBTIME 


DT_DBTIME2 


DT_DBTIMESTAMP 


DT_DBTIMESTAMP2 


RESULT 


Converts the data type. 


Sets the time zone field in the DT_DBTIMESTAMPOFFSET 
data type to zero. 


RESULT 


Sets the time fields in the DT_FILETIME data type to zero. 


Sets the time fields in the DT_DATE data type to zero. 


No change. 


Sets the time fields in the DT_DBTIME data type to zero. 


Sets the time fields in the DT_DBTIME2 data type to zero. 


Sets the time fields in the DT_DBTIMESTAMP data type to 
zero. 


Sets the time fields in the DT_DBTIMESTAMP data type to 
zero. 


Sets the time fields and the time zone field in the 
DT_DBTIMESTAMPOFFSET data type to zero. 


RESULT 


Sets the date field in the DT_FILETIME data type to the 
current date. 


Sets the date field in the DT_DATE data type to the current 
date. 


Sets the date field in the DT_DBDATE data type to the 
current date. 


No change. 


Converts the data type. 


Sets the date field in the DT_DBTIMESTAMP data type to the 
current date. 


Sets the date field in the DT_DBTIMESTAMP2 data type to 
the current date. 


CONVERT DT_DBTIME TO 


DT_DBTIMESTAMPOFFSET 


Converting from DT_DBTIME2 


CONVERT DT_DBTIME2 TO 


DT_FILETIME 


DT_DATE 


DT_DBDATE 


DT_DBTIME 


DT_DBTIME2 


DT_DBTIMESTAMP 


RESULT 


Sets the date field and the time zone field in the 
DT_DBTIMESTAMPOFFSET data type to the current date and 
to zero, respectively. 


RESULT 


Sets the date field in the DT_FILETIME data type to the 
current date. 


Removes the fractional second value when its scale is greater 
than the number of fractional second digits that the 
DT_FILETIME data type can contain. After removing the 
fractional second value, generates a report about this data 
truncation. For more information, see Error Handling in Data. 


Sets the date field of the DT_DATE data type to the current 
date. 


Removes the fractional second value when its scale is greater 
than the number of fractional second digits that the 
DT_DATE data type can contain. After removing the 
fractional second value, generates a report about this data 
truncation. For more information, see Error Handling in Data. 


Sets the date field of the DT_DBDATE data type to the 
current date. 


Removes the fractional second value when its scale is greater 
than the number of fractional second digits that the 
DT_DBTIME data type can contain. After removing the 
fractional second value, generates a report about this data 
truncation. For more information, see Error Handling in Data. 


Removes the fractional second value when its scale is greater 
than the number of fractional second digits that the 
destination DT_DBTIME2 data type can contain. After 
removing the fractional second value, generates a report 
about this data truncation. For more information, see Error 
Handling in Data. 


Set the date field in the DT_DBTIMESTAMP data type to the 
current date. 


Removes the fractional second value when its scale is greater 
than the number of fractional second digits that the 
DT_DBTIMESTAMP data type can contain. After removing the 
fractional second value, generates a report about this data 
truncation. For more information, see Error Handling in Data. 


CONVERT DT_DBTIME2 TO 


DT_DBTIMESTAMP2 


DT_DBTIMESTAMPOFFSET 


Converting from DT_DBTIMESTAMP 


CONVERT DT_DBTIMESTAMP TO 


DT_FILETIME 


DT_DATE 


DT_DBDATE 


DT_DBTIME 


DT_DBTIME2 


DT_DBTIMESTAMP 


RESULT 


Sets the date field in the DT_DBTIMESTAMP2 data type to 
the current date. 


Removes the fractional second value when its scale is greater 
than the number of fractional second digits that the 
DT_DBTIMESTAMP2 data type can contain. After removing 
the fractional second value, generates a report about this 
data truncation. For more information, see Error Handling in 
Data. 


Sets the date field and the time zone field in the 
DT_DBTIMESTAMPOFFSET data type to the current date and 
to zero, respectively. 


Removes the fractional second value when its scale is greater 
than the number of fractional second digits that the 
DT_DBTIMESTAMPOFFSET data type can contain. After 
removing the fractional second value, generates a report 
about this data truncation. For more information, see Error 
Handling in Data. 


RESULT 


Converts the data type. 


If a value represented by the DT_DBTIMESTAMP data type 
overflows the range of the DT_DATE data type, returns the 
DB_E_ DATAOVERFLOW error. For more information, see 
Error Handling in Data. 


Removes the time value represented by the 
DT_DBTIMESTAMP data type. 


Removes the date value represented by the 
DT_DBTIMESTAMP data type. 


Removes the fractional second value when its scale is greater 
than the number of fractional second digits that the 
DT_DBTIME data type can contain. After removing the 
fractional second value, generates a report about this data 
truncation. For more information, see Error Handling in Data. 


Removes the date value represented by the 
DT_DBTIMESTAMP data type. 


Removes the fractional second value when its scale is greater 
than the number of fractional second digits that the 
DT_DBTIME2 data type can contain. After removing the 
fractional second value, generates a report about this data 
truncation. For more information, see Error Handling in Data. 


No change. 


CONVERT DT_DBTIMESTAMP TO 


DT_DBTIMESTAMP2 


DT_DBTIMESTAMPOFFSET 


Converting from DT_DBTIMESTAMP2 


CONVERT DT_DBTIMESTAMP2 TO 


DT_FILETIME 


DT_DATE 


DT_DBDATE 


DT_DBTIME 


DT_DBTIME2 


RESULT 


Removes the fractional second value when its scale is greater 
than the number of fractional second digits that the 
DT_DBTIMESTAMP2 data type can contain. After removing 
the fractional second value, generates a report about this 
data truncation. For more information, see Error Handling in 
Data. 


Sets the time zone field in the DT_DBTIMESTAMPOFFSET 
data type to zero. 


Removes the fractional second value when its scale is greater 
than the number of fractional second digits that the 
DT_DBTIMESTAMPOFFSET data type can contain. After 
removing the fractional second value, generates a report 
about this data truncation. For more information, see Error 
Handling in Data. 


RESULT 


Removes the fractional second value when its scale is greater 
than the number of fractional second digits that the 
DT_FILETIME data type can contain. After removing the 
fractional second value, generates a report about this data 
truncation. For more information, see Error Handling in Data. 


If a value represented by the DT_DBTIMESTAMP2 data type 
overflows the range of the DT_DATE data type, the 

DB_E_ DATAOVERFLOW error is returned. For more 
information, see Error Handling in Data. 


Removes the fractional second value when its scale is greater 
than the number of fractional second digits that the 
DT_DATE data type can contain. After removing the 
fractional second value, generates a report about this data 
truncation. For more information, see Error Handling in Data. 


Removes the time value represented by the 
DT_DBTIMESTAMP2 data type. 


Removes the date value represented by the 
DT_DBTIMESTAMP2 data type. 


Removes the fractional second value when its scale is greater 
than the number of fractional second digits that the 
DT_DBTIME data type can contain. After removing the 
fractional second value, generates a report about this data 
truncation. For more information, see Error Handling in Data. 


Removes the date value represented by the 
DT_DBTIMESTAMP2 data type. 


Removes the fractional second value when its scale is greater 
than the number of fractional second digits that the 
DT_DBTIME2 data type can contain. After removing the 
fractional second value, generates a report about this data 
truncation. For more information, see Error Handling in Data. 


CONVERT DT_DBTIMESTAMP2 TO 


DT_DBTIMESTAMP 


DT_DBTIMESTAMP2 


DT_DBTIMESTAMPOFFSET 


Converting from DT_DBTIMESTAMPOFFSET 


CONVERT DT_DBTIMESTAMPOFFSET TO 


DT_FILETIME 


RESULT 


If a value represented by the DT_DBTIMESTAMP2 data type 
overflows the range of the DT_DBTIMESTAMP data type, 
returns the DB_E_ DATAOVERFLOW error. 


DT_DBTIMESTAMP2 maps to a SQL Server data type, 
datetime2, with a range of January 1, 1A.D. through 
December 31, 9999. DT_DBTIMESTAMP maps to a SQL 
Server data type, datetime, with smaller a range of January 
1, 1753 through December 31, 9999. 


Removes the fractional second value when its scale is greater 
than the number of fractional second digits that the 
DT_DBTIMESTAMP data type can contain. After removing the 
fractional second value, generates a report about this data 
truncation. 


For more information about errors, see Error Handling in 
Data. 


Removes the fractional second value when its scale is greater 
than the number of fractional second digits that the 
destination DT_DBTIMESTAMP2 data type can contain. After 
removing the fractional second value, generates a report 
about this data truncation. For more information, see Error 
Handling in Data. 


Sets the time zone field in the DT_DBTIMESTAMPOFFSET 
data type to zero. 


Removes the fractional second value when its scale is greater 
than the number of fractional second digits that the 
DT_DBTIMESTAMPOFFSET data type can contain. After 
removing the fractional second value, generates a report 
about this data truncation. For more information, see Error 
Handling in Data. 


RESULT 


Changes the time value represented by the 
DT_DBTIMESTAMPOFFSET data type to Coordinated 
Universal Time (UTC). 


Removes the fractional second value when its scale is greater 
than the number of fractional second digits that the 
DT_FILETIME data type can contain. After removing the 
fractional second value, generates a report about this data 
truncation. For more information, see Error Handling in Data. 


CONVERT DT_DBTIMESTAMPOFFSET TO 


DT_DATE 


DT_DBDATE 


DT_DBTIME 


DT_DBTIME2 


DT_DBTIMESTAMP 


RESULT 


Changes the time value represented by the 
DT_DBTIMESTAMPOFFSET data type to UTC. 


If a value represented by the DT_DBTIMESTAMPOFFSET data 
type overflows the range of the DT_DATE data type, returns 
the DB_E_DATAOVERFLOW error. 


Removes the fractional second value when its scale is greater 
than the number of fractional second digits that the 
DT_DATE data type can contain. After removing the 
fractional second value, generates a report about this data 
truncation. 


For more information, see Error Handling in Data. 


Changes the time value represented by the 
DT_DBTIMESTAMPOFFSET data type to UTC, which can affect 
the date value. The time value is then removed. 


Changes the time value represented by the 
DT_DBTIMESTAMPOFFSET data type to UTC. 


Removes the data value represented by the 
DT_DBTIMESTAMPEOFFSET data type. 


Removes the fractional second value when its scale is greater 
than the number of fractional second digits that the 
DT_DBTIME data type can contain. After removing the 
fractional second value, generates a report about this data 
truncation. For more information, see Error Handling in Data. 


Changes the time value represented by the 
DT_DBTIMESTAMPOFFSET data type to UTC. 


Removes the date value represented by the 
DT_DBTIMESTAMPOFFSET data type. 


Removes the fractional second value when its scale is greater 
than the number of fractional second digits that the 
DT_DBTIME2 data type can contain. After removing the 
fractional second value, generates a report about this data 
truncation. For more information, see Error Handling in Data. 


Changes the time value represented by the 
DT_DBTIMESTAMPOFFSET data type to UTC. 


If a value represented by the DT_DBTIMESTAMPOFFSET data 
type overflows the range of the DT_DBTIMESTAMP data 
type, the DB_E_DATAOVERFLOW error is returned. 


Removes the fractional second value when its scale is greater 
than the number of fractional second digits that the 
DT_DBTIMESTAMP data type can contain. After removing the 
fractional second value, generates a report about this data 
truncation. 


For more information, see Error Handling in Data. 


CONVERT DT_DBTIMESTAMPOFFSET TO RESULT 


DT_DBTIMESTAMP2 


DT_DBTIMESTAMPOFFSET 


Changes the time value represented by the 
DT_DBTIMESTAMPOFFSET data type to UTC. 


Removes the fractional second value when its scale is greater 
than the number of fractional second digits that the 
DT_DBTIMESTAMP2 data type can contain. After removing 
the fractional second value, generates a report about this 
data truncation. For more information, see Error Handling in 
Data. 


Removes the fractional second value when its scale is greater 
than the number of fractional second digits that the 
destination DT_DBTIMESTAMPOFFSET data type can contain. 
After removing the fractional second value, generates a 
report about this data truncation. For more information, see 
Error Handling in Data. 


Mapping of Integration Services Data Types to Database Data Types 


The following table provides guidance on mapping the data types used by certain databases to Integration 


Services data types. These mappings are summarized from the mapping files used by the SQL Server Import 


and Export Wizard when it imports data from these sources. For more information about these mapping files, 


see SQL Server Import and Export Wizard. 


NOTE 


types. 





DATA TYPE 


DT_BOOL 


DT_BYTES 


DT_CY 


DT_DATE 


DT_DBDATE 


IMPORTANT 


SQL SERVER 


(SQLOLEDB; 
SQLNCLI10) 


bit 


binary, 
varbinary, 
timestamp 


smallmoney, 
money 


date 
(Transact- 
SQL) 


These mappings are not intended to represent strict equivalency, but only to provide guidance. In certain situations, you 


may need to use a different data type than the one shown in this table. 


You can use the SQL Server data types to estimate the size of corresponding Integration Services date and time data 


ORACLE 

DB2 DB2 
SQL SERVER (ORACLECLIE 
(SQLCLIENT) JET NT) (DB2OLEDB) (IBMDADB2) 
bit Bit 
binary, BigBinary, RAW 
varbinary, VarBinary 
timestamp 
smallmoney, Currency 
money 
date date date date 
(Transact- 
SQL) 





DATA TYPE 


DT_DBTIME 


DT_DBTIME2 


DT_DBTIMEST 
AMP 


DT_DBTIMEST 
AMP2 


DT_DBTIMEST 
AMPOFFSET 


DT_DECIMAL 


DT_FILETIME 


DT_GUID 


DT_|1 


DT_l2 


DT_l4 


DT_I8 


DT_NUMERIC 


DT_R4 


DT_R8 


DT_STR 


DT_UI1 


DT_UI2 


SQL SERVER 


(SQLOLEDB; 
SQLNCLI10) 


time 
(Transact- 
SQL)(p) 


datetime 
(Transact- 
SQL), 
smalldatetime 
(Transact- 
SQL) 


datetime2 
(Transact- 
SQL) 


datetimeoffse 
t (Transact- 
SQL)(p) 


uniqueidentifi 
er 


smallint 


int 


bigint 


decimal, 
numeric 


real 


float 


char, varchar 


tinyint 


SQL SERVER 
(SQLCLIENT) 


time 
(Transact- 
SQL) (p) 


datetime 
(Transact- 
SQL), 
smalldatetime 
(Transact- 
SQL) 


datetime2 
(Transact- 
SQL) 


datetimeoffse 
t (Transact- 
SQL) (p) 


uniqueidentifi 
er 


smallint 


int 


bigint 


decimal, 
numeric 


real 


float 


tinyint 


ORACLE 
(ORACLECLIE 
JET NT) 


timestamp 


TIMESTAMP 
DATE, 
INTERVAL 


DateTime 


timestamp 


timestampoff 
set 


GUID 


Short 


Long 


Decimal NUMBER, INT 


Single 


Double FLOAT, REAL 


VarChar 


Byte 


DB2 


(DB2OLEDB) 


time 


TIME, 
TIMESTAMP. 
DATE 


timestamp 


timestamp, 


varchar 


SMALLINT 


INTEGER 


BIGINT 


DECIMAL, 
NUMERIC 


REAL 


FLOAT, 
DOUBLE 


CHAR, 
VARCHAR 


DB2 


(IBMDADB2) 


time 


TIME, 
TIMESTAMP 
DATE 


timestamp 


timestamp, 


varchar 


SMALLINT 


INTEGER 


BIGINT 


DECIMAL, 
NUMERIC 


REAL 


FLOAT, 
DOUBLE 


CHAR, 
VARCHAR 


DATA TYPE 


DT_UI4 


DT_UI8 


DT_WSTR 


DT_IMAGE 


DT_NTEXT 


DT_TEXT 


SQL SERVER 


(SQLOLEDB; 
SQLNCLI10) 


nchar, 
nvarchar, 
sql_variant, 
xml 


image 


ntext 


text 


SQL SERVER 
(SQLCLIENT) 


char, varchar, 
nchar, 
nvarchar, 
sql_variant, 
xml 


image 


text, ntext 


JET 


LongTlext 


LongBinary 


ORACLE 


(ORACLECLIE 
NT) 


CHAR, 
ROWID, 
VARCHAR2, 
NVARCHARZ2, 
NCHAR 


LONG RAW, 
BLOB, 
LOBLOCATOR 
, BFILE, 
VARGRAPHIC, 
LONG 
VARGRAPHIC, 
user-defined 


LONG, CLOB, 
NCLOB, 
NVARCHAR, 
TEXT 


DB2 


(DB2OLEDB) 


GRAPHIC, 
VARGRAPHIC 


CHAR () FOR 
BIT DATA, 
VARCHAR () 
FOR BIT DATA 


LONG 
VARCHAR, 
NCHAR, 
NVARCHAR, 
TEXT 


LONG 
VARCHAR 
FOR BIT DATA 


DB2 


(IBMDADB2) 


GRAPHIC, 
VARGRAPHIC 


CHAR () FOR 
BIT DATA, 
VARCHAR () 
FOR BIT 
DATA, BLOB 


LONG 
VARCHAR, 
DBCLOB, 
NCHAR, 
NVARCHAR, 
TEXT 


LONG 
VARCHAR 
FOR BIT 
DATA, CLOB 


For information on mapping data types in the data flow, see Working with Data Types in the Data Flow. 


Related Content 


Blog entry, Performance Comparison between Data Type Conversion Techniques in SSIS 2008, on 


blogs.msdn.com. 


See Also 


Data in Data Flows 


Parsing Data 
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Data flows in packages extract and load data between heterogeneous data stores, which may use a variety of 
standard and custom data types. In a data flow, Integration Services sources do the work of extracting data, 
parsing string data, and converting data to an Integration Services data type. Subsequent transformations may 
parse data to convert it to a different data type, or create column copies with different data types. Expressions 
used in components may also cast arguments and operands to different data types. Finally, when the data is 
loaded into a data store, the destination may parse the data to convert it to a data type that the destination uses. 
For more information, see Integration Services Data Types. 


Two types of parsing 
Integration Services provides two types of parsing for converting data: Fast parse and Standard parse. 


e Fast parse is a fast, simple set of parsing routines that does not support locale-specific data type 
conversions, and supports only the most frequently used date and time formats. 


e Standard parse is a rich set of parsing routines that supports all the data type conversions that are 
provided by the Automation data type conversion APIs available in Oleaut32.dll and Ole2dsip.dll. 


Fast Parse 


Fast parse provides a fast, simple set of routines for parsing data. These routines are not locale-sensitive and 
they support only a subset of date, time, and integer formats. 


Requirements and limitations 


By implementing fast parse, a package forfeits its ability to interpret date, time, and numeric data in locale- 
specific formats and many frequently used ISO 8601 basic and extended formats, but the package enhances its 
performance. For example, fast parse supports only the most commonly used date format representations such 
as YYYYMMDD and YYYY-MM-DD, does not perform locale-specific parsing, does not recognize special 
characters in currency data, and cannot convert hexadecimal or scientific representation of integers. 


Fast parse is available only when you use the Flat File source or the Data Conversion transformation. The 
increase in performance can be significant, and you should consider using fast parse in these data flow 
components if you can. 


If the data flow in the package requires locale-sensitive parsing, standard parse is recommended instead of fast 
parse. For example, fast parse does not recognize locale-sensitive data that includes decimal symbols such as 
the comma, date formats other than year-month-date formats, and currency symbols. 


Truncated representations that imply one or more date parts, such as a century, a year, or a month, are not 
recognized by fast parse. For example, fast parse recognizes neither the '-YYMM' format, which specifies a year 
and month in an implied century, nor '--MM', which specifies a month in an implied year. However, some 
representations with reduced precision are recognized. For example, fast parse recognizes the ‘hhmm;' format, 
which indicates hour and minute only, and 'YYYY’, which indicates year only. 


Fast parse is specified at the column level. In the Flat File source and the Data Conversion transformation, you 
can specify Fast parse on output columns. Inputs and outputs can include both locale-sensitive and locale- 
insensitive columns. 


Numeric data formats (Fast Parse) 


Fast parse provides a fast, simple, locale-insensitive set of routines for parsing data. Fast parse supports only a 
limited set of formats for integer data types. 


Integer data type 


The integer data types that Integration Services provides are DT_I1, DT_UI1, DT_I2, DT_UI2, DT_l4, DT_UI4, DT_I8, 
and DT_UI8. For more information, see Integration Services Data Types. 


Fast parse supports the following formats for integer data types: 


e Zero or more leading and trailing spaces or tab stops. For example, the value " 123 " is valid. A value that 
is all spaces evaluates to zero. 


e A leading plus sign, minus sign, or neither. For example, the values +123, -123, and 123 are valid. 


e One or more Hindu-Arabic numerals (0-9). For example, the value 345 is valid. Other language numerals 
are not supported. 


Non-supported data formats include the following: 


e Special characters. For example, the currency character $ is not supported, and the value $20 cannot be 
parsed. 


e White-space characters such as line feed, carriage returns, and non-breaking spaces. For example, the 
value " 123" cannot be parsed. 


e Hexadecimal representations of integers. For example, the value 2EE cannot be parsed. 

e Scientific notation representation of integers. For example, the value 1E+10 cannot be parsed. 
The following formats are output data formats for integers: 

e Aminus sign for negative numbers and nothing for positive ones. 

e No white spaces. 


e@ Oneor more Hindu-Arabic numerals (0-9). 


Date and time formats (Fast Parse) 


Fast parse provides a fast, simple set of routines for parsing data. Fast parse supports the following formats for 
date and time data types. 


Date data type 


Fast parse supports the following string formats for date data: 
e Date formats that include leading white spaces. For example, the value " 2004- 02-03" is valid. 


e ISO 8601 formats, as listed in the following table: 


FORMAT DESCRIPTION 

YYYYMMDD Basic and extended formats for a four-digit year, a two- 
digit month, and a two-digit day. In the extended format, 

YYYY-MM-DD the date parts are separated by a hyphen (-). 

YYYY-MM Basic and extended reduced precision formats for a four- 


digit year and a two-digit month. In the extended 
format, the date parts are separated by a hyphen (-). 


FORMAT DESCRIPTION 


YYYY Reduced precision format is a four-digit year. 


Fast parse does not support the following formats for date data: 
e Alphabetical month values. For example, the date format Oct-31-2003 is not valid. 


e Ambiguous formats such as DD-MM-YYYY and MM-DD-YYYY. For example, the dates 03-04-1995 and 
04-03-1995 are not valid. 


e Basic and extended truncated formats for a four-digit calendar year and a three-digit day within a year, 
YYYYDDD and YYYY-DDD. 


e Basic and extended formats for a four-digit year, a two-digit number for the week of the year, and a one- 
digit number for the day of the week, YYYYWwwD and YYYY-Www-D 


e Basic and extended truncated formats for a year and week date are a four-digit year and a two-digit 
number for the week, YYYWww and YYYY-Www 


Fast parse outputs the data as DT_DBDATE. Date values in truncated formats are padded. For example, YYYY 
becomes YYYY0101. 


For more information, see Integration Services Data Types. 


Time data type 


Fast parse supports the following string formats for time data: 
e Time formats that include leading white spaces. For example, the value " 10:24" is valid. 
e 24-hour format. Fast parse does not support the AM and PM notation. 


e ISO 8601 time formats, as listed in the following table: 


FORMAT DESCRIPTION 

HHMISS Basic and extended formats for a two-digit hour, a two- 
digit minute, and a two-digit second. In the extended 

HH:MI:SS format, the time parts are separated by a colon (:). 

HHMI Basic and extended truncated format for a two-digit 
hour and a two-digit minute. In the extended format, the 

HH:MI time parts are separated by a colon (). 


HH Truncated format for a two-digit hour. 


FORMAT 


00:00:00 


000000 


0000 


00 


240000 


24:00:00 


2400 


24 


DESCRIPTION 


The format for midnight. 


e Time formats that specify a time zone, as listed in the following table:. 


FORMAT 


+HH:MI 


+HHMI 


-HH:MI 


-HHMI 


+HH 


-HH 


DESCRIPTION 


Basic and extended formats that indicate the number of 
hours and minutes that are added to Coordinated 
Universal Time (UTC) to obtain the local time. 


Basic and extended formats that indicate the number of 
hours and minutes that are subtracted from UTC to 
obtain the local time. 


Truncated format that indicates the number of hours 
that are added to UTC to obtain the local time. 


Truncated format that indicates the number of hours 
that are subtracted from UTC to obtain the local time. 


A value of 0 that indicates the time is represented in 
UTC. 


The formats for all time and date/time data can include a time zone element. However, the system ignores 


the time zone value except when the data is of type DT_DBTIMESTAMPOFFSET. For more information, see 


Integration Services Data Types. 


In formats that include a time zone element, there is no space between the time element and the time 


zone element, as shown in the following example: 


HH:MI:SS[+HH:MI] 


The brackets in the previous example indicate that the time zone value is optional. 


e Time formats that include a decimal fraction, as listed in the following table: 


FORMAT 


HH[Ennnnnnn] 


DESCRIPTION 


n is a value between 0 and 9999999 that represents a 
fraction of hours. The brackets indicate that this value is 
optional. 


For example, the value 12.750 indicates 12:45. 


FORMAT DESCRIPTION 


HHMI[.nnnnnnn] nis a value between 0 and 9999999 that represents a 
fraction of minutes. The brackets indicate that this value 
HH:MI[.nnnnnnn]j is optional. 


For example, the value 1220.500 indicates 12:20:30. 


HHMISS[.nnnnnnnj nis a value between 0 and 9999999 that represents a 
fraction of seconds. The brackets indicate that this value 
HH:MI:SS[.-nnnnnnn] is optional. 


For example, the value 122040.250 indicates 
12:20:40.15. 





NOTE 


The fraction separator for the time formats in the previous table can be a decimal or a comma. 





@ Time values that include a leap second, as shown in the following examples: 
23:59:60[.0000000] 


235960[.0000000] 


Fast parse outputs the strings as DT_DBTIME and DT_DBTIME2. Time values in truncated formats are padded. For 
example, HH:MI becomes HH:MM:00.000. 


For more information, see Integration Services Data Types. 


Date/Time data type 


Fast parse supports the following string formats for date/time data: 
e Formats that include leading white spaces. For example, the value " 2003-01-10T203910" is valid. 


e Combinations of valid date formats and valid time formats separated by an uppercase T, and valid time 
zone formats, such as YYYYMMDDT[HHMISS][+HH:MI]. The time and time zone values are not required. 
For example, "2003-10-14" is valid. 


Fast parse does not support time intervals. For example, a time interval identified by a start and end date and 
time in the format YYYYMMDDThhmmss/YYYYMMDDThhmmss cannot be parsed. 


Fast parse outputs the strings as DI_DATE, DT_DBTIMESTAMP DT_DBTIMESTAMP2, and 
DT_DBTIMESTAMPOFFSET. Date/time values in truncated formats are padded. The following table lists the values 
that are added for missing date and time parts. 


DATE/TIME PART PADDING 
Seconds Add 00. 


Minutes Add 00:00. 


DATE/TIME PART PADDING 


Hour Add 00:00:00. 
Day Add 01 for the day of the month. 
Month Add 01 for the month of the year. 


For more information, see Integration Services Data Types. 


Enable Fast Parse 


The fast parse property must be set for each column of the source or transformation that uses fast parse. To set 
the property, use the Advanced editor of the Flat File source and Data Conversion transformation. 


1. Right-click the Flat File source or Data Conversion transformation, and then click Show Advanced 
Editor. 


2. In the Advanced Editor dialog box, click the Input and Output Properties tab. 
3. In the Inputs and Outputs pane, click the column for which you want to enable fast parse. 


4. In the Properties window, expand the Custom Properties node, and then set the FastParse property to 


True. 


5. Click OK. 


Standard Parse 


Standard parse is a locale-sensitive set of parsing routines that support all the data type conversions provided 
by the Automation data type conversion APIs that are available in Oleaut32.dll and Ole2dsip.dll. Standard parse 
is equivalent to the OLE DB parsing APIs. 


Standard parse provides support for data type conversion of international data, and it should be used if the data 
format is not supported by Fast parse. For more information about the Automation data type conversion API, 
see "Data Type Conversion APIs" in the MSDN Library. 
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String comparisons are an important part of many of the transformations performed by Integration Services, 
and string comparisons are also used in the evaluation of expressions in variables and property expressions. For 
example, the Sort transformation compares values in a dataset to sort data in ascending or descending order. 


Configuring Transformations for String Comparisons 


The Sort, Aggregate, Fuzzy Grouping, and Fuzzy Lookup transformations can be customized to change the way 
strings are compared at the column level. For example, you can specify that a comparison ignores case, which 
means that uppercase and lowercase characters are treated as the same character. 


The following transformations use expressions that can include string comparisons. 


e@ The Conditional Split transformation can use string comparisons in expressions to determine which 
output to send the data row to. For more information, see Conditional Split Transformation. 


e The Derived Column transformation can use string comparisons in expressions to generate new column 
values. For more information, see Derived Column Transformation. 


Variables, variable mappings, and precedence constraints also use expressions, which can include string 
comparisons. For more information about expressions, see Integration Services (SSIS) Expressions. 


Processing during String Comparison 


Depending on the data and the configuration of the transformation, the following processing may occur during 
the comparison of string data: 


e Converting data to Unicode. If the source data is not already Unicode, the data is automatically converted 
to Unicode before the comparison occurs. 


e Using locale to apply locale-specific rules for interpreting date, time, decimal data, and sort order. 


e Applying comparison options at the column level to change the sensitivity of comparisons. 


Converting String Data to Unicode 


Depending on the operations that the transformation performs and the configuration of the transformation, 
string data may be converted to the DT_WSTR data type, which is a Unicode representation of string characters. 


String data that has the DT_STR data type is converted to Unicode using the code page of the column. 
Integration Services supports code pages at the column level, and each column can be converted by using a 
different code page. 


In most cases, Integration Services can identify the correct code page from the data source. For example, in SQL 
Server you can set a collation at the database and column levels. The code page is derived from a SQL Server 
collation, which can be either a Windows or an SQL collation. 


If Integration Services provides an unexpected code page, or if the package accesses a data source by using a 
provider that does not supply sufficient information to determine the correct code page, you can specify a 
default code page in the OLE DB source and the OLE DB destination. The default code pages are used instead of 


the code pages that Integration Services provides. 


Files do not have code pages. Instead, the Flat File and the Multiple Flat Files connection managers that a 
package uses to connect to file data include a property for specifying the code page of the file. The code page 
can be set at the file level only, not at the column level. 


Setting Locale 


Integration Services does not use the code page to infer locale-specific rules for sorting data or interpreting 
date, time, and decimal data. Instead, the transformation reads the locale that is set by the Localeld property on 
the data flow component, Data Flow task, container, or package. By default, the locale of a transformation is 
inherited from its Data Flow task, which in turn inherits from the package. If the Data Flow task is in a container 


such as the For Loop container, it inherits its locale from the container. 


You can also specify a locale for a Flat File connection manager and a Multiple Flat Files connection manager. 


Setting Comparison Options 


The locale provides the basic rules for comparing string data. For example, the locale specifies the sort position 
of each letter in the alphabet. However, these rules may not be sufficient for the comparisons that some 
transformations perform, and Integration Services supports a set of advanced comparison options that go 
beyond the comparison rules of a locale. These comparison options are set at the column level. For example, one 
of the comparison options lets you ignore nonspacing characters. The effect of this option is to ignore diacritics 


such as the accent, which makes "a" and "Aj" identical for comparison purposes. 


The following table describes the comparison options and a sort style. 
COMPARISON OPTION DESCRIPTION 


Ignore case Specifies whether the comparison distinguishes between 
uppercase and lowercase letters. If this option is set, the 
string comparison ignores case. For example, "ABC" becomes 
the same as "abc". 


Ignore kana type Specifies whether the comparison distinguishes between the 
two types of Japanese kana characters: hiragana and 
katakanaa. If this option is set, the string comparison ignores 
kana type. 


Ignore character width Specifies whether the comparison distinguishes between a 
single-byte character and the same character when it is 
represented as a double-byte character. If this option is set, 
the string comparison treats single-byte and double-byte 
representations of the same character as identical. 


Ignore nonspacing characters Specifies whether the comparison distinguishes between 
spacing characters and diacritics. If this option is set, the 
comparison ignores diacritics. For example, "A¥" is equal to 


a. 


Ignore symbols Specifies whether the comparison distinguishes between 
letter characters and symbols such as white-space 
characters, punctuation, currency symbols, and mathematical 
symbols. If this option is set, the string comparison ignores 
symbols. For example, " New York" becomes the same as 
"New York" and "*ABC" is the same as "ABC". 


COMPARISON OPTION DESCRIPTION 


Sort punctuation as symbols Specifies whether the comparison sorts all punctuation 
symbols, except the hyphen and apostrophe, before the 
alphanumeric characters. For example, if this option is set, 
"ABC" sorts before "ABC". 


The Sort, Aggregate, Fuzzy Grouping and Fuzzy Lookup transformations include these options for comparing 
data. 


The FullySensitive comparison flag displays in the Advanced Editor dialog box for the Fuzzy Grouping and 
Fuzzy Lookup transformations. Selecting the FullySensitive comparison flag means that all the comparison 
options apply. 


See Also 


Integration Services Data Types 
Fast Parse 
Standard Parse 


Add or Delete a Component in a Data Flow 
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Data flow components are sources, destinations, and transformations in a data flow. Before you can add 
components to a data flow, the control flow in the package must include a Data Flow task. 


The following procedures describe how to add or delete a component in the data flow of a package. 


To add a component to a data flow 


1. In SQL Server Data Tools (SSDT), open the Integration Services project that contains the package you 
want. 


2. In Solution Explorer, double-click the package to open it. 


3. Click the Control Flow tab, and then double-click the Data Flow task that contains the data flow to which 
you want to add a component. 


4. In the Toolbox, expand Data Flow Sources, Data Flow Transformations, or Data Flow 
Destinations, and then drag a data flow item to the design surface of the Data Flow tab. 


5. To save the updated package, click Save Selected Items on the File menu. 


To delete a component from a data flow 


1. In SQL Server Data Tools (SSDT), open the Integration Services project that contains the package you 
want. 


2. In Solution Explorer, double-click the package to open it. 


3. Click the Control Flow tab, and then double-click the Data Flow task that contains the data flow from 


which you want to delete a component. 
4. Right-click the data flow component, and then click Delete. 
5. Confirm the delete operation. 


6. To save the updated package, click Save Selected Items on the File menu. 


See Also 


Connect Components in a Data Flow 
Debugging Data Flow 
Data Flow 


Set the Properties of a Data Flow Component 
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To set the properties of data flow components, which include sources, destinations, and transformations, use 
one of the following features: 


e The component editors that Integration Services provides. These editors include only the custom 
properties of each data flow component. 


e The Properties window lists the component-level custom properties of each element, as well as the 
properties common to all data flow elements. 


e The Advanced Editor dialog box provides access to custom properties for each component. The 
Advanced Editor dialog box also provides access to the properties common to all data flow 
components-the properties of inputs, outputs, error outputs, columns, and external columns. 


Set the properties of a data flow component with a component editor 


1. In SQL Server Data Tools (SSDT), open the Integration Services project that contains the package you 
want. 


2. In Solution Explorer, double-click the package to open it. 


3. Click the Control Flow tab, and then double-click the Data Flow task that contains the data flow with the 
component whose properties you want to view and modify. 


4. Double-click the data flow component. 
5. In the component editor, view or modify the property values, and then close the editor. 


6. To save the updated package, on the File menu, click Save Selected Items. 


Set the properties of a data flow component in the Properties 
window 


1. In SQL Server Data Tools (SSDT), open the Integration Services project that contains the package you 
want. 


2. In Solution Explorer, double-click the package to open it. 


3. Click the Control Flow tab, and then double-click the Data Flow task that contains the component whose 
properties you want to view and modify. 


4. Right-click the data flow component, and then click Properties. 


5. View or modify the property values, and then close the Properties window. 





NOTE 


Many properties are read-only, and cannot be modified. 





6. To save the updated package, on the File menu, click Save Selected Items. 


Set the properties of a data flow component with the Advanced 
Editor 


1. In SQL Server Data Tools (SSDT), open the Integration Services project that contains the package you 


want. 
2. In Solution Explorer, double-click the package to open it. 


3. Click the Control Flow tab, and then double-click the Data Flow task that contains the component you 
want to view or modify. 


4. In the data flow designer, right-click the data flow component, and then click Show Advanced Editor. 


NOTE 


In SQL Server, data flow components that support multiple inputs cannot use the Advanced Editor. 





5. Inthe Advanced Editor dialog box, do any of the following steps: 


e To view and specify the connection that the component uses, click the Connection Managers tab. 


NOTE 


The Connection Managers tab is available only to data flow components that use connection managers 
to connect to data sources such as files and databases 





@ To view and modify component-level properties, click the Component Properties tab. 


e To view and modify mappings between external columns and the available output, click the 
Column Mappings tab. 





NOTE 


The Column Mappings tab is available only when viewing or editing sources or destinations. 





e To view alist of the available input columns and to update the names of output columns, click the 
Input Columns tab. 


NOTE 


The Input Columns tab is available only when working with transformations or destinations. For more 


information, see Integration Services Transformations. 





e To view and modify the properties of inputs, outputs, and error outputs, and the properties of the 
columns they contain, click the Input and Output Properties tab. 





NOTE 


Sources have no inputs. Destinations have no outputs, except for an optional error output. 





6. View or modify the property values. 


7. Click OK. 


8. To save the updated package, on the File menu, click Save Selected Items. 


Common properties of data flow components 


The data flow objects in the Microsoft SQL Server Integration Services object model have common properties 
and custom properties at the component, input and output, and input column and output column levels. Many 
properties have read-only values that are assigned at run time by the data flow engine. 


This topic lists and describes the common properties of data flow objects. 
e Components 

e Inputs 

e Input columns 

e Outputs 

e Output columns 


Component properties 


In the Integration Services object model, a component in the data flow implements the 
IDTSComponentMetaData1 00 interface. 


The following table describes the properties of the components in a data flow. Some properties have read-only 
values that are assigned at run time by the data flow engine. 


PROPERTY DATA TYPE DESCRIPTION 
ComponentClass|D String The CLSID of the component. 
ContactInfo String Contact information for the developer 


of a component. 


Description String The description of the data flow 
component. The default value of this 
property is the name of the data flow 
component. 


ID Integer A value that uniquely identifies this 
instance of the component. 


IdentificationString String Identifies the component. 


IsDefaultLocale Boolean Indicates whether the component uses 
the locale of the Data Flow task to 
which it belongs. 


LocalelD Integer The locale that the data flow 
component uses when the package 
runs. All Windows locales are available 
for use in data flow components. 


Name String The name of the data flow component. 


PipelineVersion Integer The version of the data flow task 
within which a component is designed 
to execute. 


PROPERTY DATA TYPE DESCRIPTION 


UsesDispositions Boolean Indicates whether a component has an 
error output. 


ValidateExternalMetadata Boolean Indicates whether the metadata of 
external columns is validated. The 
default value of this property is True. 


Version Integer The version of a component. 


Input properties 
In the Integration Services object model, transformations and destinations have inputs. An input of a component 


in the data flow implements the IDTSInput100 interface. 


The following table describes the properties of the inputs of components in a data flow. Some properties have 
read-only values that are assigned at run time by the data flow engine. 


PROPERTY DATA TYPE DESCRIPTION 
Description String The description of the input. 
ErrorOrTruncationOperation String An optional string that specifies the 


types of errors or truncations that can 
occur when processing a row. 


ErrorRowDisposition DTSRowDisposition A value that specifies the handling of 
errors. The values are Fail 
component, Ignore failure, and 
Redirect row. 


HasSideEffects Boolean Indicates whether a component can be 
removed from the execution plan of 
the data flow when it is not attached 
to a downstream component and 
when RunInOptimizedMode is true. 


ID Integer A value that uniquely identifies the 
input. 

IdentificationString String A string that identifies the input. 

IsSorted Boolean Indicates whether the data in the input 
is sorted. 

Name String The name of the input. 

SourceLocale Integer The locale ID (LCID) of the input data. 

TruncationRowDisposition DTSRowDisposition A value that determines how the 


component handles truncations that 
occur when processing rows. . The 
values are Fail component, Ignore 
failure, and Redirect row. 


Destinations and some transformations do not support error outputs, and the ErrorRowDisposition and 


TruncationRowDisposition properties of these components are read-only. 


Input column properties 


In the Integration Services object model, an input contains a collection of input columns. An input column of a 


component in the data flow implements the |IDTSInputColumn100 interface. 


The following table describes the properties of the input columns of components in a data flow. Some 
properties have read-only values that are assigned at run time by the data flow engine. 


PROPERTY DATA TYPE DESCRIPTION 


ComparisonFlags Integer A set of flags that specify the 
comparison of columns that have a 
character data type. For more 
information, see Comparing String 


Data. 
Description String Describes the input column. 
ErrorOrTruncationOperation String An optional string that specifies the 


types of errors or truncations that can 
occur when processing a row. 


ErrorRowDisposition DTSRowDisposition A value that specifies the handling of 
errors. The values are Fail 
component, Ignore failure, and 
Redirect row. 


ExternalMetadataColumnID IDTSExternalMetadataColumn100 The ID of the external metadata 
column assigned to an input column. 


ID Integer A value that uniquely identifies the 
input column. 


IdentificationString String A string that identifies the input 
column. 

LineagelD Integer The ID of the upstream column. 

LineageldentificationString String The identification string which includes 


the name of the upstream column. 


Name String The name of the input column. 


SortKeyPosition Integer A value that indicates whether a 
column is sorted, its sort order, and 
the sequence in which multiple 
columns are sorted. The value 0 
indicates the column is not sorted. For 
more information, see Sort Data for 
the Merge and Merge Join 
Transformations. 


TruncationRowDisposition DTSRowDisposition A value that determines how the 
component handles truncations that 
occur when processing rows. The 
values are Fail component, Ignore 
failure, and Redirect row. 


PROPERTY DATA TYPE DESCRIPTION 


UpstreamComponentName String The name of the upstream component. 


UsageType DTSUsageType A value that determines how an input 
column is used by the component. 


Input columns also have the data type properties described under "Data Type Properties.” 


Output properties 
In the Integration Services object model, sources and transformations have outputs. An output of a component 
in the data flow implements the |DTSOutput100 interface. 


The following table describes the properties of the outputs of components in a data flow. Some properties have 
read-only values that are assigned at run time by the data flow engine. 


PROPERTY DATA TYPE DESCRIPTION 


DeleteOutputOnPathDetached Boolean A value that determines whether the 
data flow engine deletes the output 
when it is detached from a path. 


Description String Describes the output. 


ErrorOrTruncationOperation String An optional string that specifies the 
types of errors or truncations that can 
occur when processing a row. 


ErrorRowDisposition DTSRowDisposition A value that specifies the handling of 
errors. The values are Fail 
component, Ignore failure, and 
Redirect row. 


ExclusionGroup Integer A value that identifies a group of 
mutually exclusive outputs. 


HasSideEffects Boolean A value that indicates whether a 
component can be removed from the 
execution plan of the data flow when it 
is not attached to an upstream 
component and when 
RunInOptimizedMode is true. 


ID Integer A value that uniquely identifies the 
output. 

IdentificationString String A string that identifies the output. 

IsErrorOut Boolean Indicates whether the output is an 


error output. 


PROPERTY 


IsSorted 


Name 


SynchronousInputID 


TruncationRowDisposition 


Output column properties 


DATA TYPE 


Boolean 


String 


Integer 


DTSRowDisposition 


DESCRIPTION 


Indicates whether the output is sorted. 
The default value is False. 


** Important ** Setting the value of 
the IsSorted property to True does 
not sort the data. This property only 
provides a hint to downstream 
components that the data has been 
previously sorted. For more 
information, see Sort Data for the 
Merge and Merge Join 
Transformations. 


The name of the output. 


The ID of an input that is synchronous 
to the output. 


A value that determines how the 
component handles truncations that 
occur when processing rows. The 
values are Fail component, Ignore 
failure, and Redirect row. 


In the Integration Services object model, an output contains a collection of output columns. An output column of 


a component in the data flow implements the IDTSOutputColumn100 interface. 


The following table describes the properties of the output columns of components in a data flow. Some 


properties have read-only values that are assigned at run time by the data flow engine. 


PROPERTY 


ComparisonFlags 


Description 


ErrorOrTruncationOperation 


ErrorRowDisposition 


ExternalMetadataColumnID 


DATA TYPE 


Integer 


String 


String 


DTSRowDisposition 


Integer 


DESCRIPTION 


A set of flags that specify the 
comparison of columns that have a 
character data type. For more 
information, see Comparing String 
Data. 


Describes the output column. 


An optional string that specifies the 
types of errors or truncations that can 
occur when processing a row. 


A value that specifies the handling of 
errors. The values are Fail 
component, Ignore failure, and 
Redirect row. The default value is Fail 
component. 


The ID of the external metadata 
column assigned to an input column. 


PROPERTY 


ID 


IdentificationString 


LineagelD 


LineageldentificationString 


Name 


SortKeyPosition 


SpecialFlags 


TruncationRowDisposition 


Output columns also include a set of data type properties. 


External metadata column properties 


DATA TYPE 


Integer 


String 


Integer 


String 


String 


Integer 


Integer 


DTSRowDisposition 


DESCRIPTION 


A value that uniquely identifies the 
output column. 


A string that identifies the output 
column. 


The ID of the output column. 
Downstream components refer to the 
column by using this value. 


The identification string which includes 
the name of the column. 


The name of the output column. 


A value that indicates whether a 
column is sorted, its sort order, and 
the sequence in which multiple 
columns are sorted. The value 0 
indicates the column is not sorted. For 
more information, see Sort Data for 
the Merge and Merge Join 
Transformations. 


A value that contains the special flags 
of the output column. 


A value that determines how the 
component handles truncations that 
occur when processing rows. The 
values are Fail component, Ignore 
failure, and Redirect row. The 
default value is Fail component. 


In the Integration Services object model, inputs and outputs can contain a collection of external metadata 


columns. An external metadata column of a component in the data flow implements the 
IDTSExternalMetadataColumn100 interface. 


The following table describes the properties of the external metadata columns of components in a data flow. 


Some properties have read-only values that are assigned at run time by the data flow engine. 


PROPERTY 


Description 


ID 


IdentificationString 


Name 


DATA TYPE 


String 


Integer 


String 


String 


DESCRIPTION 


Describes the external column. 


A value that uniquely identifies the 
column. 


A string that identifies the column. 


The name of the external column. 


External metadata columns also include a set of data type properties. 


Data type properties 


Output columns and external metadata columns include a set of data type properties. Depending on the data 
type of the column, properties can be read/write or read-only. 


The following table describes the data type properties of output columns and external metadata columns. 
PROPERTY DATA TYPE DESCRIPTION 


CodePage Integer Specifies the code page for string data 
that is not Unicode. 


DataType Integer (enumeration) The Integration Services data type of 
the column. For more information, see 
Integration Services Data Types. 


Length Integer The length, measured in characters, of 
a column. 

Precision Integer The precision of a numeric column. 

Scale Integer The scale of a numeric column. 


Custom properties of data flow components 
For information about custom properties, see the following topics 
e ADO NET Custom Properties 

e CDC Control Task Custom Properties 

e CDC Source Custom Properties 

e Data Mining Model Training Destination Custom Properties 

e DataReader Destination Custom Properties 

e Dimension Processing Destination Custom Properies 

e Excel Custom Properties 

e Flat File Custom Properties 

e ODBC Destination Custom Properties 

e ODBC Source Custom Properties 

e OLE DB Custom PropertiesOLE DB Custom Properties 

e Partition Processing Destination Custom Properties 

e Raw File Custom Properties 

e Recordset Destination Custom Properties 

e SQL Server Compact Edition Destination Custom Properties 

e SQL Server Destination Custom Properties 


e Transformation Custom Properties 


e XML Source Custom Properties 


Use an expression in a data flow component 


This procedure describes how to add an expression to the Conditional Split transformation or to the Derived 
Column transformation. The Conditional Split transformation uses expressions to define the conditions that 
direct data rows to a transformation output, and the Derived Column transformation uses expressions to define 


values assigned to columns. 


To implement an expression in a transformation, the package must already include at least one Data Flow task 


and a source. 


1. In SQL Server Data Tools (SSDT), open the Integration Services project that contains the package you 


want. 
2. In Solution Explorer, double-click the package to open it. 


3. In SSIS Designer, click the Control Flow tab, and then click the Data Flow task that contains the data flow 


in which you want to implement an expression. 


4. Click the Data Flow tab, and drag either a Conditional Split or Derived Column transformation from the 
Toolbox to the design surface. 


5. Drag the green connector from the source or a transformation to the Conditional Split or Derived 


Column transformation. 
6. Double-click the transformation to open its dialog box. 


7. In the left pane, expand Variables to display system and user-defined variables, and expand Columns to 
display the transformation input columns. 


8. In the right pane, expand Mathematical Functions, String Functions, Date/Time Functions, NULL 
Functions, Type Casts, and Operators to access the functions, the casts, and the operators that the 


expression grammar provides. 
9. Depending on the transformation, do one of the following to build an expression: 


e Inthe Conditional Split Transformation Editor dialog box, drag variables, columns, functions, 
operators, and casts to the Condition column. Alternatively, you can type an expression directly in 


the Condition column. 


e Inthe Derived Column Transformation Editor dialog box, drag variables, columns, functions, 
operators, and casts to the Expression column. Alternatively, you can type an expression directly 
in the Expression column. 





NOTE 


When you remove the focus from the Condition column or the Expression column, the expression text 


might be highlighted to indicate that the expression syntax is incorrect. 








10. Click OK to exit the dialog box. 





NOTE 


If the expression is not valid, an alert appears describing the syntax errors in the expression. 





Data flow properties that you can set with an expression 


The values of certain properties of data flow objects can be specified by using property expressions available on 
the Data Flow task container. 


For information about using property expressions, see Use Property Expressions in Packages. 


You can use property expressions to customize configurations for each deployed instance of a package. You can 
also use property expressions to specify run-time constraints for a package by using the /set option with the 
dtexec command prompt utility. For example, you can constrain the MaximumThreads used by the Sort 
transformation, or the MaxMemoryUsage of the Fuzzy Grouping and Fuzzy Lookup transformations. If 
unconstrained, these transformations may cache large amounts of data in memory. 


To specify a property expression for one of the properties of data flow objects listed in this topic, display the 
Properties window for the Data Flow task by selecting the Data Flow task on the Control Flow surface of the 
designer, or by selecting the Data Flow tab of the designer without selecting any individual component or path. 
Select the Expressions property and click the ellipsis (...) to display the Property Expressions Editor dialog 
box. Drop down the Property list to select a property, then type an expression in the Expression text box, or 
click the ellipsis (...) to display the Expression Builder dialog box. 


The Property list displays available properties for only those data flow objects that you have already placed on 
the Data Flow surface of the designer. Therefore, you cannot use the Property list to view all the possible 
properties of data flow objects that support property expressions. For example, if you have placed an ADO NET 
source on the designer surface, the Property list contains an entry for the [ADO NET Source]. 
[SqlCommand] property. The list also displays many properties of the Data Flow task itself. 


The values of the properties in the following list can be specified by using property expressions. 
Data flow sources 


DATA FLOW OBJECT PROPERTY 


ADO NET source TableOrViewName property 


SqlCommand property 


XML source XMLData property 


XMLSchemaDefinition property 


Data flow transformations 


For more information about these custom properties, see Transformation Custom Properties. 


DATA FLOW OBJECT PROPERTY 

Conditional Split transformation FriendlyExpression property 
Derived Column transformation FriendlyExpression property 
Fuzzy Grouping transformation MaxMemoryUsage property 
Fuzzy Lookup transformation MaxMemoryUsage property 
Lookup transformation SqlCommand property 


SqlCommandParam property 


DATA FLOW OBJECT PROPERTY 


OLE DB Command transformation SqlCommand property 


Percentage Sampling transformation SamplingValue property 


Pivot transformation 


Row Sampling transformation 


Sort transformation 


Unpivot transformation 


Data flow destinations 


DATA FLOW OBJECT 


ADO NET Destination 


Flat File destination 


SQL Server Compact destination 


SQL Server destination 


PivotKeyValue property 


SamplingValue property 


MaximumThreads property 


PivotKeyValue property 


PROPERTY 


TableOrViewName property 
BatchSize property 


CommandTimeout property 


Header property 


TableName property 


BulklnsertTableName property 
BulklnsertFirstRow property 
BulklnsertLastRow property 
BulklnsertOrder property 


Timeout property 


Connect Components in a Data Flow 
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This procedure describes how to connect the output of components in a data flow to other components within 
the same data flow. 

You construct the data flow in a package on the design surface of the Data Flow tab in the SSIS Designer. If a 
data flow contains two data flow components, you can connect them by connecting the output of a source or 
transformation to the input of a transformation or destination. The connector between two data flow 
components is called a path. 


The following diagram shows a simple data flow with a source component, two transformations, a destination 
component, and the paths that connect them. 








Source | 


| 


Transformation | 


Transformation 


| 


Destination | 


























After two components are connected, you can view the metadata of the data that moves through the path and 
the properties of the path in Data Flow Path Editor. For more information, see Integration Services Paths. 


You can also add data viewers to paths. A data viewer makes it possible to view data moving between data flow 
components when the package is run. 


Connect components in a data flow 


1. In SQL Server Data Tools (SSDT), open the Integration Services project that contains the package you 
want. 


2. In Solution Explorer, double-click the package to open it. 


3. Click the Control Flow tab, and then double-click the Data Flow task that contains the data flow in which 
you want to connect components. 


4. On the design surface of the Data Flow tab, select the transformation or source that you want to 
connect. 


5. Drag the green output arrow of a transformation or a source to a transformation or to a destination. 
Some data flow components have error outputs that you can connect in the same way. 


NOTE 


Some data flow components can have multiple outputs and you can connect each output to a different 


transformation or destination. 





6. To save the updated package, click Save Selected Items on the File menu. 


See Also 


Add or Delete a Component in a Data Flow 
Debugging Data Flow Data Flow 


Integration Services Paths 
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A path connects two components in a data flow by connecting the output of one data flow component to the 
input of another component. A path has a source and a destination. For example, if a path connects an OLE DB 
source and a Sort transformation, the OLE DB source is the source of the path, and the Sort transformation is 
the destination of the path. The source is the component where the path starts, and the destination is the 
component where the path ends. 


If you run a package in SSIS Designer, you can view the data in a data flow by attaching data viewers to a path. A 
data viewer can be configured to display data in a grid. A data viewer is a useful debugging tool. For more 
information, see Debugging Data Flow. 


Configure the path 


The SSIS Designer provides the Data Flow Path Editor dialog box for setting path properties, viewing the 
metadata of the data columns that pass through the path, and configuring data viewers. 


The configurable path properties include the name, description, and annotation of the path. You can also 
configure paths programmatically. For more information, see Connecting Data Flow Components 
Programmatically. 


A path annotation displays the name of the path source or the path name on the design surface of the Data 
Flow tab in SSIS Designer. Path annotations are similar to the annotations you can add to data flows, control 
flows, and event handlers. The only difference is that a path annotation is attached to a path, whereas other 
annotations appear on the Data Flow, Control Flow, and Event Handler tabs of SSIS Designer. 


The metadata shows the name, data type, precision, scale, length, code page, and source component of each 
column in the output of the previous component. The source component is the data flow component that 
created the column. This may or may not be the first component in the data flow. For example, the Union All and 
Sort transformations create their own columns, and they are the sources of their output columns. In contrast, a 
Copy Column transformation can pass through columns without changing them or can create new columns by 
copying input columns. The Copy Column transformation is the source component only of the new columns. 


Set the properties of a path with the Data Flow Path Editor 


Paths connect two data flow components. Before you can set path properties, the data flow must contain at least 
two connected data flow components. 


1. In SQL Server Data Tools (SSDT), open the Integration Services project that contains the package you 
want. 


2. In Solution Explorer, double-click the package to open it. 
3. Click the Data Flow tab, and then double-click a path. 


4. In Data Flow Path Editor, click General. You can then edit the default name of the path and provide a 
description of the path. You can also modify the PathAnnotation property. 


5. Click OK. 


6. To save the updated package, click Save Selected Items on the File menu. 


General Page - Data Flow Path Editor 


Use the Data Flow Path Editor dialog box to set path properties, view column metadata, and manage the data 
viewers attached to the path. 


Use the General node of the Data Flow Path Editor dialog box to name and describe the path, and to specify 
the options for path annotation. 


Options 
Name 
Provide a unique name for the path. 


ID 
The lineage identifier of the path. This property is read-only. 


IdentificationString 
The string that identifies the path. Automatically generated from the name entered above. 


Description 
Describe the path. 


PathAnnotation 

Specify the type of annotation to use. Choose Never to disable annotations, AsNeeded to enable annotation on 
demand, SourceName to automatically annotate using the value of the SourceName option, and PathName 
to automatically annotate using the value of the Name property. 


DestinationName 
Displays the input that is the end of the path. 


SourceName 
Displays the output that is the start of the path. 


Metadata Page - Data Flow Path Editor 


Use the Metadata page of the Data Flow Path Editor dialog box to view the metadata of the path columns. 


Options 
Path metadata 
Lists column metadata. Click the column headings to sort column data. 


Name 
Lists the column name. 


Data Type 
Lists the data type of the column. 


Precision 
Lists the number of digits in a numeric value. 


Scale 
List the number of digits to the right of the decimal point in a numeric value. 


Length 
Lists the current length of the column. 


Code Page 
Lists the code page of the column. The value 0 indicates that the column does not use a code page. This occurs 
when data is in Unicode, or has a numeric, date, or time data type. 


Sort Key Position 
Lists the sort key position of the column. The value 0 indicates the column is not sorted. 





NOTE 


A minus (-) prefix indicates the column is sorted in descending order. 





Comparison Flags 


Lists the comparison flags that apply to the column. 


Source Component 
Lists the data flow component that is the source of the column. 


Copy to Clipboard 
Copy the column metadata to the clipboard. By default, all metadata rows are copied as sorted in the order 
currently displayed. 


Data Viewers Page - Data Flow Path Editor 


Use the Data Viewers page of the Data Flow Path Editor dialog box to manage the data viewers that are 
attached to the path. 

Options 

Name 


Lists the data viewers. 


Data Viewer Type 
Lists the type of data viewer. 


Add 
Click to add a data viewer by using the Configure Data Viewer dialog box. 


Delete 
Click to delete the selected data viewer. 


Configure 
Click to configure a selected data viewer by using the Configure Data Viewer dialog box. 


Path properties 


The data flow objects in the Microsoft SQL Server Integration Services object model have common properties 
and custom properties at the level of the component, inputs and outputs, and input columns and output 
columns. Many properties have read-only values that are assigned at run time by the data flow engine. 


This topic lists and describes the custom properties of the paths that connect data flow objects. 


Custom properties of a path 


In the Integration Services object model, a path that connects components in the data flow implements the 
IDTSPath100 interface. 


The following table describes the configurable properties of the paths in a data flow. The data flow engine also 
assigns values to additional read-only properties that are not listed here. 


PROPERTY NAME DATA TYPE DESCRIPTION 


PROPERTY NAME 


PathAnnotation 


DestinationName 


SourceName 


DATA TYPE 


Integer (enumeration) 


IDTSInput100 


|IDTSOutput100 


DESCRIPTION 


A value that indicates whether an 
annotation should be displayed with 
the path on the designer surface. The 
possible values are AsNeeded, 
SourceName, PathName, and 
Never. The default value is 
AsNeeded. 


The input associated with the path. 


The output associated with the path. 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


When an input path is disconnected or if there are any unmapped columns in the path, an error icon is displayed 
beside the corresponding data path. To simplify the resolution of column reference errors, the Resolve 
References editor allows you to link unmapped output columns with unmapped input columns for all paths in 
the execution tree. The Resolve References editor will also highlight the paths to indicate which paths are being 
resolved. 


NOTE 


It is possible to edit a component even when its input path is disconnected 





After all column references have been resolved, if there are no other data path errors, no error icons will be 
displayed beside the data paths. 


Options 
Unmapped Output Columns (Source) 


Columns from the upstream path that are not currently mapped 


Mapped Columns (Source) 
Columns from the upstream path that are mapped to columns from the downstream path 


Mapped Columns (Destination) 
Columns from the upstream path that are mapped to columns from the downstream path 


Unmapped Input Columns (Destination) 
Columns from the downstream path that are not currently mapped 


Delete Unmapped Input Columns 
Check Delete Unmapped Input Columns to ignore unmapped columns at the destination of the data path. The 
Preview Changes button displays a list of the changes that will occur when you press the OK button. 


Data Viewer 
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If a path is configured to use a data viewer, the Data Viewer displays the data buffer by buffer as data moves 
between two data flow components. 


Options 


Green arrow 


Click to display the data in the next buffer. If the data can be moved in a single buffer, this option is not available. 


Detach 
Detach the data viewer. 


Note Detaching a data viewer does not delete the data viewer. If the data viewer has been detached, data 
continues to flow through the path, but the data in the viewer is not updated to match the data in each buffer. 


Attach 
Attach a data viewer. 


Note When the data viewer is attached, it displays information from each buffer in the data flow and then 
pauses. You can advance through the buffers by using the green arrow. 


Copy Data 
Copy data in the current buffer to the Clipboard. 


See Also 


Debugging Data Flow 


Error Handling in Data 
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When a data flow component applies a transformation to column data, extracts data from sources, or loads data 
into destinations, errors can occur. Errors frequently occur because of unexpected data values. For example, a 
data conversion fails because a column contains a string instead of a number, an insertion into a database 
column fails because the data is a date and the column has a numeric data type, or an expression fails to 


evaluate because a column value is zero, resulting in a mathematical operation that is not valid. 
Errors typically fall into one the following categories: 


e Data conversion errors, which occur if a conversion results in loss of significant digits, the loss of 
insignificant digits, and the truncation of strings. Data conversion errors also occur if the requested 
conversion is not supported. 


e Expression evaluation errors, which occur if expressions that are evaluated at run time perform invalid 
operations or become syntactically incorrect because of missing or incorrect data values. 


e Lookup errors, which occur if a lookup operation fails to locate a match in the lookup table. 


For a list of Integration Services errors, warnings, and other messages, see Integration Services Error and 
Message Reference. 


Use error outputs to capture row-level errors 


Many data flow components support error outputs, which let you control how the component handles row-level 
errors in both incoming and outgoing data. You specify how the component behaves when truncation or an 
error occurs by setting options on individual columns in the input or output. For example, you can specify that 
the component should fail if customer name data is truncated, but ignore errors on another column that 
contains less important data. 


The error output can be connected to the input of another transformation or loaded into a different destination 
than the non-error output. For example, the error output can be a connected to a Derived Column 
transformation that provides a string for a column that is blank. 


The following diagram shows a simple data flow including an error output. 
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For more information, see Data Flow and Integration Services Paths. 


Configure Error Output dialog box 


Use the Configure Error Output dialog box to configure error handling options for data flow transformations 
that support an error output. 


To learn more about working with error outputs, see Error Handling in Data. 


Options 
Input or Output 
View the name of the output. 


Column 


View the output columns that you selected in the transformation editor dialog box. 


Error 
If applicable, specify what should happen when an error occurs: ignore the failure, redirect the row, or fail the 
component. 


Related Topics: Error Handling in Data 


Truncation 
If applicable, specify what should happen when a truncation occurs: ignore the failure, redirect the row, or fail 
the component. 


Related Topics: Error Handling in Data 


Description 
View the description of the operation. 


Set this value to selected cells 
Specify what should happen to all the selected cells when an error or truncation occurs: ignore the failure, 
redirect the row, or fail the component. 


Apply 
Apply the error handling option to the selected cells. 


Errors are either failures or truncations 


Errors fall into one of two categories: errors or truncations. 


Errors. An error indicates an unequivocal failure, and generates a NULL result. Such errors can include data 
conversion errors or expression evaluation errors. For example, an attempt to convert a string that contains 
alphabetical characters to a number causes an error. Data conversions, expression evaluations, and assignments 
of expression results to variables, properties, and data columns may fail because of illegal casts and 
incompatible data types. For more information see, Cast (SSIS Expression), Integration Services Data Types in 
Expressions, and Integration Services Data Types. 


Truncations. A truncation is less serious than an error. A truncation generates results that might be usable or 
even desirable. You can elect to treat truncations as errors or as acceptable conditions. For example, if you are 


inserting a 15-character string into a column that is only one character wide, you can elect to truncate the string. 


Select an error handling option 


You can configure how sources, transformations, and destinations handle errors and truncations. The following 
table describes the options. 


OPTION DESCRIPTION 


OPTION DESCRIPTION 


Fail Component The Data Flow task fails when an error or a truncation 
occurs. Failure is the default option for an error and a 
truncation. 

Ignore Failure The error or the truncation is ignored and the data row is 


directed to the output of the transformation or source. 


Redirect Row The error or the truncation data row is directed to the error 
output of the source, transformation, or destination. 


Get more info about the error 


In addition to the data columns, the error output includes the ErrorCode and ErrorColumn columns. The 
ErrorCode column identifies the error and the ErrorColumn contains the lineage identifier of the error 


column. 


Under some circumstances, the value of the ErrorColumn column is set to zero. This occurs when the error 
condition affects the entire row instead of a single column. An example is when a lookup fails in the Lookup 
transformation. 


These two numeric values may be of limited use without the corresponding error description and column name. 
Here are some ways to get the error description and column name. 


e You can see both error descriptions and column names by attaching a Data Viewer to the error output. In 
SSIS Designer, right-click on the red arrow leading to an error output and select Enable Data Viewer. 


e You can find column names by enabling logging and selecting the DiagnosticEx event. This event writes 
a data flow column map to the log. You can then look up the column name from its identifier in this 
column map. Note that the DiagnosticEx event does not preserve whitespace in its XML output to 
reduce the size of the log. To improve readability, copy the log into an XML editor - in Visual Studio, for 
example - that supports XML formatting and syntax highlighting. For more info about logging, see 
Integration Services (SSIS) Logging. 


Here is an example of a data flow column map. 


\<DTS:PipelineColumnMap xmlns:DTS="www.microsoft.com/SqlServer/Dts"> 
\<DTS:Pipeline DTS:Path="\Package\Data Flow Task"> 

\<DTS:Column DTS:ID="11" DTS:IdentificationString="ADO NET Source.Outputs[ADO NET Source 
Output] .Columns[Customer ]"/> 

\<DTS:Column DTS:ID="12" DTS:IdentificationString="ADO NET Source.Outputs[ADO NET Source 
Output] .Columns[Product]"/> 

\<DTS:Column DTS: ID="13" DTS:IdentificationString="ADO NET Source.Outputs[ADO NET Source 
Output].Columns[Price]"/> 

\<DTS:Column DTS: ID="14" DTS:IdentificationString="ADO NET Source.Outputs[ADO NET Source 
Output].Columns[Timestamp]"/> 

\<DTS:Column DTS: ID="20" DTS:IdentificationString="ADO NET Source.Outputs[ADO NET Source 
Error Output].Columns[Customer]"/> 

\<DTS:Column DTS:ID="21" DTS:IdentificationString="ADO NET Source.Outputs[ADO NET Source 
Error Output ].Columns[Product]"/> 

\<DTS:Column DTS: ID="22" DTS:IdentificationString="ADO NET Source.Outputs[ADO NET Source 
Error Output].Columns[Price]"/> 

\<DTS:Column DTS: ID="23" DTS:IdentificationString="ADO NET Source.Outputs[ADO NET Source 
Error Output].Columns[Timestamp]"/> 

\<DTS:Column DTS: ID="24" DTS:IdentificationString="ADO NET Source.Outputs[ADO NET Source 
Error Output].Columns[ErrorCode]"/> 

\<DTS:Column DTS: ID="25" DTS:IdentificationString="ADO NET Source.Outputs[ADO NET Source 
Error Output].Columns[ErrorColumn]"/> 

\<DTS:Column DTS: ID="31" DTS:IdentificationString="Flat File Destination.Inputs[Flat File 
Destination Input].Columns[Customer]"/> 

\<DTS:Column DTS: ID="32" DTS:IdentificationString="Flat File Destination.Inputs[Flat File 
Destination Input].Columns[Product]"/> 

\<DTS:Column DTS: ID="33" DTS:IdentificationString="Flat File Destination.Inputs[Flat File 
Destination Input].Columns[Price]"/> 

\<DTS:Column DTS: ID="34" DTS:IdentificationString="Flat File Destination.Inputs[Flat File 
Destination Input].Columns[Timestamp]"/> 

\</DTS:Pipeline> 

\</DTS:PipelineColumnMap> 








e@ You can also use the Script component to include the error description and the column name in 
additional columns of the error output. For an example, see Enhancing an Error Output with the Script 
Component. 


o Include the error description in an additional column by using a single line of script to call the 
GetErrorDescription method of the IDTSComponentMetaData100 interface. 


o Include the column name in an additional column by using a single line of script to call the 
[Microsoft.SqlServer.Dts.Pipeline.Wrapper.|IDTSComponentMetaData1 00.GetldentificationStringBy! 
D*] (/previous-versions/sql/sql-server-2016/mt657629(v=sql.130)) method of the 
IDTSComponentMetaData1 00 interface. 


You can add the Script component to the error segment of the data flow anywhere downstream from the 
data flow components whose errors you want to capture. Typically you place the Script component 
immediately before the error rows are written to a destination. This way, the script looks up descriptions 
only for error rows that are written. The error segment of the data flow may correct some errors and not 


write those rows to an error destination. 


See Also 


Data Flow 

Transform Data with Transformations 
Connect Components with Paths 
Data Flow Task 

Data Flow 
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This topic provides suggestions about how to design Integration Services packages to avoid common 
performance issues. This topic also provides information about features and tools that you can use to 
troubleshoot the performance of packages. 


Configuring the Data Flow 


To configure the Data Flow task for better performance, you can configure the task's properties, adjust buffer 
size, and configure the package for parallel execution. 


Configure the Properties of the Data Flow Task 





NOTE 


The properties discussed in this section must be set separately for each Data Flow task in a package. 





You can configure the following properties of the Data Flow task, all of which affect performance: 


e Specify the locations for temporary storage of buffer data (BuffertempStoragePath property) and of 
columns that contain binary large object (BLOB) data (BLOBTempStoragePath property). By default, these 
properties contain the values of the TEMP and TMP environment variables. You might want to specify 
other folders to put the temporary files on a different or faster hard disk drive, or to spread them across 
multiple drives. You can specify multiple directories by delimiting the directory names with semicolons. 


e Define the default size of the buffer that the task uses, by setting the DefaultBufferSize property, and 
define the maximum number of rows in each buffer, by setting the DefaultBufferMaxRows property. Set 
the AutoAdjustBufferSize property to indicate whether the default size of the buffer is calculated 
automatically from the value of the DefaultBufferMaxRows property. The default buffer size is 10 
megabytes, with a maximum buffer size of 2*31-1 bytes. The default maximum number of rows is 
10,000. 


e Set the number of threads that the task can use during execution, by setting the EngineThreads property. 
This property provides a suggestion to the data flow engine about the number of threads to use. The 
default is 10, with a minimum value of 3. However, the engine will not use more threads than it needs, 
regardless of the value of this property. The engine may also use more threads than specified in this 
property, if necessary to avoid concurrency issues. 


e Indicate whether the Data Flow task runs in optimized mode (RunInOptimizedMode property). Optimized 
mode improves performance by removing unused columns, outputs, and components from the data 
flow. 





NOTE 


A property with the same name, RunInOptimizedMode, can be set at the project level in SQL Server Data Tools 
(SSDT) to indicate that the Data Flow task runs in optimized mode during debugging. This project property 


overrides the RunInOptimizedMode property of Data Flow tasks at design time. 








Adjust the Sizing of Buffers 


The data flow engine begins the task of sizing its buffers by calculating the estimated size of a single row of data. 
Then it multiplies the estimated size of a row by the value of DefaultBufferMaxRows to obtain a preliminary 


working value for the buffer size. 


e If AutoAdjustBufferSize is set to true, the engine data flow engine uses the calculated value as the buffer 


size, and the value of DefaultBufferSize is ignored. 


e If AutoAdjustBufferSize is set to false, the engine data flow engine uses the following rules to determine 
the buffer size. 


o If the result is more than the value of DefaultBufferSize, the engine reduces the number of rows. 


o If the result is less than the internally-calculated minimum buffer size, the engine increases the 
number of rows. 


o If the result falls between the minimum buffer size and the value of DefaultBufferSize, the engine 
sizes the buffer as close as possible to the estimated row size times the value of 
DefaultBufferMaxRows. 


When you begin testing the performance of your data flow tasks, use the default values for DefaultBufferSize 
and DefaultBufferMaxRows. Enable logging on the data flow task, and select the BufferSizeTuning event to see 


how many rows are contained in each buffer. 


Before you begin adjusting the sizing of the buffers, the most important improvement that you can make is to 
reduce the size of each row of data by removing unneeded columns and by configuring data types 
appropriately. 


To determine the optimum number of buffers and their size, experiment with the values of DefaultBufferSize and 
DefaultBufferMaxRows while monitoring performance and the information reported by the BufferSizeTuning 
event. 


Do not increase buffer size to the point where paging to disk starts to occur. Paging to disk hinders performance 
more than a buffer size that has not been optimized. To determine whether paging is occurring, monitor the 
"Buffers spooled" performance counter in the Performance snap-in of the Microsoft Management Console 
(MMC). 


Configure the Package for Parallel Execution 


Parallel execution improves performance on computers that have multiple physical or logical processors. To 
support parallel execution of different tasks in the package, Integration Services uses two properties: 
MaxConcurrentExecutables and EngineThreads. 


The MaxConcurrentExcecutables Property 

The MaxConcurrentExecutables property is a property of the package itself. This property defines how many 
tasks can run simultaneously. The default value is -1, which means the number of physical or logical processors 
plus 2. 


To understand how this property works, consider a sample package that has three Data Flow tasks. If you set 
MaxConcurrentExecutables to 3, all three Data Flow tasks can run simultaneously. However, assume that each 
Data Flow task has 10 source-to-destination execution trees. Setting MaxConcurrentExecutables to 3 does 
not ensure that the execution trees inside each Data Flow task run in parallel. 


The EngineThreads Property 

The EngineThreads property is a property of each Data Flow task. This property defines how many threads the 
data flow engine can create and run in parallel. The EngineThreads property applies equally to both the source 
threads that the data flow engine creates for sources and the worker threads that the engine creates for 
transformations and destinations. Therefore, setting EngineThreads to 10 means that the engine can create up 
to ten source threads and up to ten worker threads. 


To understand how this property works, consider the sample package with three Data Flow tasks. Each of Data 
Flow task contains ten source-to-destination execution trees. If you set EngineThreads to 10 on each Data Flow 


task, all 30 execution trees can potentially run simultaneously. 


NOTE 
A discussion of threading is beyond the scope of this topic. However, the general rule is not to run more threads in 
parallel than the number of available processors. Running more threads than the number of available processors can 


hinder performance because of the frequent context-switching between threads. 











Configuring Individual Data Flow Components 


To configure individual data flow components for better performance, there are some general guidelines that 
you can follow. There are also specific guidelines for each type of data flow component: source, transformation, 
and destination. 


General Guidelines 


Regardless of the data flow component, there are two general guidelines that you should follow to improve 


performance: optimize queries and avoid unnecessary strings. 


Optimize Queries 

A number of data flow components use queries, either when they extract data from sources, or in lookup 
operations to create reference tables. The default query uses the SELECT * FROM <tableName> syntax. This type 
of query returns all the columns in the source table. Having all the columns available at design time makes it 
possible to choose any column as a lookup, pass-through, or source column. However, after you have selected 
the columns to be used, you should revise the query to include only those selected columns. Removing 
superfluous columns makes the data flow in a package more efficient because fewer columns create a smaller 
row. A smaller row means that more rows can fit into one buffer, and the less work it is to process all the rows in 
the dataset. 


To construct a query, you can type the query or use Query Builder. 





NOTE 
When you run a package in SQL Server Data Tools (SSDT), the Progress tab of SSIS Designer lists warnings. These 


warnings include identifying any data column that a source makes available to the data flow, but is not subsequently used 
by downstream data flow components. You can use the RunInOptimizedMode property to remove these columns 


automatically. 











Avoid Unnecessary Sorting 
Sorting is inherently a slow operation, and avoiding unnecessary sorting can enhance the performance of the 
package data flow. 


Sometimes the source data has already been sorted before being used by a downstream component. Such pre- 
sorting can occur when the SELECT query used an ORDER BY clause or when the data was inserted into the 
source in sorted order. For such pre-sorted source data, you can provide a hint that the data is sorted, and 
thereby avoid the use of a Sort transformation to satisfy the sorting requirements of certain downstream 
transformations. (For example, the Merge and Merge Join transformations require sorted inputs.) To provide a 
hint that the data is sorted, you have to do the following tasks: 


e Set the IsSorted property on the output of an upstream data flow component to True. 
e Specify the sort key columns on which the data is sorted. 


For more information, see Sort Data for the Merge and Merge Join Transformations. 


If you have to sort the data in the data flow, you can improve performance by designing the data flow to use as 
few sort operations as possible. For example, the data flow uses a Multicast transformation to copy the dataset. 
Sort the dataset once before the Multicast transformation runs, instead of sorting multiple outputs after the 
transformation. 


For more information, see Sort Transformation, Merge Transformation, Merge Join Transformation, and 
Multicast Transformation. 


Sources 

OLE DB Source 

When you use an OLE DB source to retrieve data from a view, select "SQL commana" as the data access mode 
and enter a SELECT statement. Accessing data by using a SELECT statement performs better than selecting 
"Table or view" as the data access mode. 


Transformations 


Use the suggestions in this section to improve the performance of the Aggregate, Fuzzy Lookup, Fuzzy 
Grouping, Lookup, Merge Join, and Slowly Changing Dimension transformations. 


Aggregate Transformation 

The Aggregate transformation includes the Keys, KeysScale, CountDistinctKeys, and CountDistinctScale 
properties. These properties improve performance by enabling the transformation to preallocate the amount of 
memory that the transformation needs for the data that the transformation caches. If you know the exact or 
approximate number of groups that are expected to result from a Group by operation, set the Keys and 
KeysScale properties, respectively. If you know the exact or approximate number of distinct values that are 
expected to result from a Distinct count operation, set the CountDistinctKeys and CountDistinctScale 
properties, respectively. 


If you have to create multiple aggregations in a data flow, consider creating multiple aggregations that use one 
Aggregate transformation instead of creating multiple transformations. This approach improves performance 
when one aggregation is a subset of another aggregation because the transformation can optimize internal 
storage and scan incoming data only once. For example, if an aggregation uses a GROUP BY clause and an AVG 
aggregation, combining them into one transformation can improve performance. However, performing multiple 
aggregations within one Aggregate transformation serializes the aggregation operations, and therefore might 
not improve performance when multiple aggregations must be computed independently. 


Fuzzy Lookup and Fuzzy Grouping Transformations 
For information about optimizing the performance of the Fuzzy Lookup and Fuzzy Grouping transformations, 
see the white paper, Fuzzy Lookup and Fuzzy Grouping in SQL Server Integration Services 2005. 


Lookup Transformation 

Minimize the size of the reference data in memory by entering a SELECT statement that looks up only the 
columns that you need. This option performs better than selecting an entire table or view, which returns a large 
amount of unnecessary data. 


Merge Join Transformation 
You no longer have to configure the value of the MaxBuffersPerlnput property because Microsoft has made 
changes that reduce the risk that the Merge Join transformation will consume excessive memory. This problem 


sometimes occurred when the multiple inputs of the Merge Join produced data at uneven rates. 


Slowly Changing Dimension Transformation 

The Slowly Changing Dimension Wizard and the Slowly Changing Dimension transformation are general- 
purpose tools that meet the needs of most users. However, the data flow that the wizard generates is not 
optimized for performance. 


Typically, the slowest components in the Slowly Changing Dimension transformation are the OLE DB Command 
transformations that perform UPDATEs against a single row at a time. Therefore, the most effective way to 
improve the performance of the Slowly Changing Dimension transformation is to replace the OLE DB Command 


transformations. You can replace these transformations with destination components that save all rows to be 
updated to a staging table. Then, you can add an Execute SQL task that performs a single set-based Transact-SQL 
UPDATE against all rows at the same time. 


Advanced users can design a custom data flow for slowly changing dimension processing that is optimized for 
large dimensions. For a discussion and example of this approach, see the section, "Unique dimension scenario," 
in the white paper, Project REAL: Business Intelligence ETL Design Practices. 

Destinations 

To achieve better performance with destinations, consider using a SQL Server destination and testing the 


destination's performance. 


SQL Server Destination 
When a package loads data to an instance of SQL Server on the same computer, use a SQL Server destination. 
This destination is optimized for high-speed bulk loads. 


Testing the Performance of Destinations 

You may find that saving data to destinations takes more time than expected. To identify whether the slowness is 
caused by the inability of the destination to process data quickly enough, you can temporarily replace the 
destination with a Row Count transformation. If the throughput improves significantly, it is likely that the 
destination that is loading the data is causing the slowdown. 


Review the Information on the Progress Tab 


SSIS Designer provides information about both control flow and data flow when you run a package in SQL 
Server Data Tools (SSDT). The Progress tab lists tasks and containers in order of execution and includes start 
and finish times, warnings, and error messages for each task and container, including the package itself. It also 
lists data flow components in order of execution and includes information about progress, displayed as 


percentage complete, and the number of rows processed. 


To enable or disable the display of messages on the Progress tab, toggle the Debug Progress Reporting 
option on the SSIS menu. Disabling progress reporting can help improve performance while running a complex 
package in SQL Server Data Tools. 


Related Tasks 


e Sort Data for the Merge and Merge Join Transformations 


Related Content 


Articles and Blog Posts 


e Technical article, SQL Server 2005 Integration Services: A Strategy for Performance, on 
technet.microsoft.com 


@ Technical article, Integration Services: Performance Tuning Techniques, on technet.microsoft.com 


e Technical article, Increasing Throughput of Pipelines by Splitting Synchronous Transformations into 
Multiple Tasks, in SQLCAT's Guide to BI and Analytics 


e Technical article, The Data Loading Performance Guide, on msdn.microsoft.com. 

@ Technical article, We Loaded 1TB in 30 Minutes with SSIS, and So Can You, on msdn.microsoft.com. 
e Technical article, Top 10 SQL Server Integration Services Best Practices, on sqlcat.com. 

e Technical article and sample, The "Balanced Data Distributor" for SSIS, on sqlcat.com. 


e Blog post, Troubleshooting SSIS Package Performance Issues, on blogs.msdn.com 


Videos 


e Video series, Designing and Tuning for Performance your SSIS packages in the Enterprise (SQL Video 


Series) 


e Video, Tuning Your SSIS Package Data Flow in the Enterprise (SQL Server Video), on 


technet.microsoft.com 
e Video, Understanding SSIS Data Flow Buffers (SQL Server Video), on technet.microsoft.com 
e Video, Microsoft SQL Server Integration Services Performance Design Patterns, on channel9.msdn.com. 


e Presentation, How Microsoft IT Leverages SQL Server 2008 SSIS Dataflow Engine Enhancements, on 


sqlcat.com. 


e Video, Balanced Data Distributor, on technet.microsoft.com. 


See Also 


Troubleshooting Tools for Package Development 
Troubleshooting Tools for Package Execution 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


The Source Assistant component helps create a source component and connection manager. The component is 
located in the Favorites section of the SSIS Toolbox. 





NOTE 


Source Assistant replaces the Integration Services Connections project and the corresponding wizard. 











Add a source with Source Assistant 


This section provides steps to add a new source using the Source Assistant and also lists the options that are 
available on the Add New Source dialog, which you will see when you drag-drop the Source Assistant to the 
SSIS Designer. 


1. In SQL Server Data Tools (SSDT), open the Integration Services package that you want to add a source 
component to. 


2. Drag the Source Assistant component from the SSIS Toolbox to the Data Flow tab. You should see the 
Add New Source dialog box. The next section provides you details about the options available in the 
dialog box. 


3. Select the type of the destination in the Types list. 


4. Select an existing connection manager in the Connection Managers list or select <New> to create a 
new connection manager. 


5. If you select an existing connection manager, click OK to close the Add New Destination dialog box. 
You should see the destination and connection managers added to the data flow. 


6. If you click <New> to create a new connection manager, you should see a Connection Manager dialog 
box, which lets you specify parameters for the connection. After you are done with creating the new 
connection manager, you will see the destination and the connection manager in SSIS Designer. 


Add New Source dialog box 


The following table lists options available in the Add New Source dialog box. 


OPTION DESCRIPTION 
Types Select the type of source you want to connect to. 
Connection Managers Select an existing connection manager or click <New> to 


create a new connection manager. 


Show installed only Specify whether to view only installed sources. 


OK Click to save your changes and open any subsequent dialog 
boxes to configure additional options. 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


The Destination Assistant component helps create a destination component and connection manager. The 
component is located in the Favorites section of the SSIS Toolbox. 





NOTE 


Destination Assistant replaces the Integration Services Connections project and the corresponding wizard. 











Add a destination with Destination Assistant 


This topic provides steps to add a new destination using the Destination Assistant and also lists the options that 
are available on the Add New Destination dialog, which you will see when you drag-drop the Destination 
Assistant to the SSIS Designer. 


1. In SQL Server Data Tools (SSDT), open the Integration Services package that you want to adda 
destination component to. 


2. Drag the Destination Assistant component from the SSIS Toolbox to the Data Flow tab. You should 
see the Add New Destination dialog box. The next section provides you details about the options 
available in the dialog box. 


3. Select the type of the destination in the Types list. 


4. Select an existing connection manager in the Connection Managers list or select <New> to create a 
new connection manager. 


5. If you select an existing connection manager, click OK to close the Add New Destination dialog box. 
You should see the destination and connection managers added to the data flow. 


6. If you click <New> to create a new connection manager, you should see a Connection Manager dialog 
box, which lets you specify parameters for the connection. After you are done with creating the new 
connection manager, you will see the destination and the connection manager in SSIS Designer. 


Add New Destination dialog box 


The following table lists the options available on the Add New Destination dialog box. 


OPTION DESCRIPTION 
Types Select the type of destination you want to connect to. 
Connection Managers Select an existing connection manager or click <New> to 


create a new connection manager. 


Show installed only Specify whether to view only installed destinations. 


OK Click to save your changes and open any subsequent dialog 
boxes to configure additional options. 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 
The ADO NET source consumes data from a .NET provider and makes the data available to the data flow. 


You can use the ADO NET source to connect to Microsoft Azure SQL Database. Connecting to SQL Database by 
using OLE DB is not supported. For more information about SQL Database, see General Guidelines and 
Limitations (Azure SQL Database). 


Data Type Support 


The source converts any data type that does not map to a specific Integration Services data type to the 
DT_NTEXT Integration Services data type. This conversion occurs even if the data type is System.Object. 


You can change the DT_NTEXT data type to the DT_WSTR data type, or the change DT_WSTR to DT_NTEXT. You 
change data types by setting the DataType property in the Advanced Editor dialog box of the ADO NET 
source. For more information, see Common Properties. 


The DT_NTEXT data type can also be converted to the DI_BYTES or DT_STR data type by using a Data Conversion 
transformation after the ADO NET source. For more information, see Data Conversion Transformation. 


In Integration Services, the date data types, DT_DBDATE, DT_DBTIME2, DT_DBTIMESTAMP2, and 
DT_DBTIMESTAMPOFFSET, map to certain date data types in SQL Server. You can configure the ADO NET source 
to convert the date data types from those that SQL Server uses to those that Integration Services uses. To 
configure the ADO NET source to convert these date data types, set the Type System Version property of the 
ADO.NET connection manager to Latest. (The Type System Version property is on the All page of the 
Connection Manager dialog box. To open the Connection Manager dialog box, right-click the ADO.NET 
connection manager, and then click Edit.) 


NOTE 


If the Type System Version property for the ADO.NET connection manager is set to SQL Server 2005, the system 
converts the SQL Server date data types to DT_WSTR. 





The system converts user-defined data types (UDTs) to Integration Services binary large objects (BLOB) when 
the ADO.NET connection manager specifies the provider as the NET Data Provider for SQL Server (SqlClient). 
The system applies the following rules when it converts the UDT data type: 


e Ifthe data is anon-large UDT, the system converts the data to DT_BYTES. 


e If the data is a non-large UDT, and the Length property of the column on the database is set to -1 ora 
value greater than 8,000 bytes, the system converts the data to DT_IMAGE. 


e If the data is a large UDT, the system converts the data to DT_IMAGE. 





NOTE 


If the ADO NET source is not configured to use error output, the system streams the data to the DT_IMAGE 
column in chunks of 8,000 bytes. If the ADO NET source is configured to use error output, the system passes the 
whole array of bytes to the DT_IMAGE column. For more information about how to configure components to use 


error output, see Error Handling in Data. 








For more information about the Integration Services data types, supported data type conversions, and data type 
mapping across certain databases including SQL Server, see Integration Services Data Types. 


For information about mapping Integration Services data types to managed data types, see Working with Data 
Types in the Data Flow. 


ADO NET Source Troubleshooting 


You can log the calls that the ADO NET source makes to external data providers. You can use this logging 
capability to troubleshoot the loading of data from external data sources that the ADO NET source performs. To 
log the calls that the ADO NET source makes to external data providers, enable package logging and select the 
Diagnostic event at the package level. For more information, see Troubleshooting Tools for Package Execution. 


ADO NET Source Configuration 


You configure the ADO NET source by providing the SQL statement that defines the result set. For example, an 
ADO NET source that connects to the AdventureWorks2012 database and uses the SQL statement 
SELECT * FROM Production.Product extracts all the rows from the Production.Product table and provides the 


dataset to a downstream component. 





NOTE 


When you use an SQL statement to invoke a stored procedure that returns results from a temporary table, use the WITH 
RESULT SETS option to define metadata for the result set. 








NOTE 


If you use an SQL statement to execute a stored procedure and the package fails with the following error, you may be 
able to resolve the error by adding the SET FMTONLY OFF statement before the exec statement. 


Column <column_name> cannot be found at the datasource. 





The ADO NET source uses an ADO.NET connection manager to connect to a data source, and the connection 
manager specifies the .NET provider. For more information, see ADO.NET Connection Manager. 


The ADO NET source has one regular output and one error output. 
You can set properties through SSIS Designer or programmatically. 


For more information about the properties that you can set in the Advanced Editor dialog box or 
programmatically, click one of the following topics: 


© Common Properties 
e ADO NET Custom Properties 


For more information about how to set properties, see Set the Properties of a Data Flow Component. 





ADO NET Source Editor (Connection Manager Page) 


Use the Connection Manager page of the ADO NET Source Editor dialog box to select the ADO.NET 
connection manager for the source. This page also lets you select a table or view from the database. 


To learn more about the ADO NET source, see ADO NET Source. 

To open the Connection Manager page 

1. In SQL Server Data Tools (SSDT), open the Integration Services package that has the ADO NET source. 
2. On the Data Flow tab, double-click the ADO NET source. 

3. Inthe ADO NET Source Editor, click Connection Manager. 


Static Options 


ADO.NET connection manager 


Select an existing connection manager from the list, or create a new connection by clicking New. 


New 
Create a new connection manager by using the Configure ADO.NET Connection Manager dialog box. 


Data access mode 
Specify the method for selecting data from the source. 


OPTION DESCRIPTION 
Table or view Retrieve data from a table or view in the ADO.NET data 
source. 
SQL command Retrieve data from the ADO.NET data source by using a SQL 
query. 
Preview 


Preview results by using the Data View dialog box. Preview can display up to 200 rows. 





NOTE 
When you preview data, columns with a CLR user-defined type do not contain data. Instead the values <value too big to 
display> or System.Byte[] display. The former displays when the data source is accessed by using the ADO.NET provider, 


the latter when using the SQL Server Native Client provider. 





Data Access Mode Dynamic Options 

Data access mode = Table or view 

Name of the table or the view 

Select the name of the table or view from a list of those available in the data source. 


Data access mode = SQL command 

SQL command text 

Enter the text of a SQL query, build the query by clicking Build Query, or locate the file that contains the query 
text by clicking Browse. 


Build query 
Use the Query Builder dialog box to construct the SQL query visually. 


Browse 


Use the Open dialog box to locate the file that contains the text of the SQL query. 





ADO NET Source Editor (Columns Page) 


Use the Columns page of the ADO NET Source Editor dialog box to map an output column to each external 
(source) column. 


To learn more about the ADO NET source, see ADO NET Source. 

To open the Columns page 

1. In SQL Server Data Tools (SSDT), open the Integration Services package that has the ADO NET source. 
2. On the Data Flow tab, double-click the ADO NET source. 

3. Inthe ADO NET Source Editor, click Columns. 


Options 
Available External Columns 
View the list of available external columns in the data source. You cannot use this table to add or delete columns. 


External Column 
View external (source) columns in the order in which you will see them when configuring components that 


consume data from this source. 


Output Column 

Provide a unique name for each output column. The default is the name of the selected external (source) 
column; however, you can choose any unique, descriptive name. The name provided will be displayed within the 
SSIS Designer. 


ADO NET Source Editor (Error Output Page) 


Use the Error Output page of the ADO NET Source Editor dialog box to select error handling options and to 


set properties on error output columns. 

To learn more about the ADO NET source, see ADO NET Source. 

To open the Error Output page 

1. In SQL Server Data Tools (SSDT), open the Integration Services package that has the ADO NET source. 
2. On the Data Flow tab, double-click the ADO NET source. 

3. Inthe ADO NET Source Editor, click Error Output. 


Options 


Input/Output 
View the name of the data source. 


Column 
View the external (source) columns that you selected on the Connection Manager page of the ADO NET 
Source Editor dialog box. 


Error 
Specify what should happen when an error occurs: ignore the failure, redirect the row, or fail the component. 


Related Topics: Error Handling in Data 


Truncation 


Specify what should happen when a truncation occurs: ignore the failure, redirect the row, or fail the component. 


Description 


View the description of the error. 


Set this value to selected cells 
Specify what should happen to all the selected cells when an error or truncation occurs: ignore the failure, 
redirect the row, or fail the component. 


Apply 
Apply the error handling option to the selected cells. 


See Also 


DataReader Destination 
ADO NET Destination 
Data Flow 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


The ADO NET destination loads data into a variety of ADO.NET-compliant databases that use a database table or 
view. You have the option of loading this data into an existing table or view, or you can create a new table and 
load the data into the new table. 


You can use the ADO NET destination to connect to Microsoft Azure SQL Database. Connecting to SQL Database 
by using OLE DB is not supported. For more information about SQL Database, see General Guidelines and 
Limitations (Azure SQL Database). 


Troubleshooting the ADO NET Destination 


You can log the calls that the ADO NET destination makes to external data providers. You can use this logging 
capability to troubleshoot the saving of data to external data sources that the ADO NET destination performs. To 
log the calls that the ADO NET destination makes to external data providers, enable package logging and select 
the Diagnostic event at the package level. For more information, see Troubleshooting Tools for Package 
Execution. 


Configuring the ADO NET Destination 


This destination uses an ADO.NET connection manager to connect to a data source and the connection manager 
specifies the ADO.NET provider to use. For more information, see ADO.NET Connection Manager. 


An ADO NET destination includes mappings between input columns and columns in the destination data source. 
You do not have to map input columns to all destination columns. However, the properties of some destination 
columns can require the mapping of input columns. Otherwise, errors might occur. For example, if a destination 
column does not allow for null values, you must map an input column to that destination column. In addition, 
the data types of mapped columns must be compatible. For example, you cannot map an input column with a 
string data type to a destination column with a numeric data type if the ADO.NET provider does not support this 


mapping. 


NOTE 


SQL Server does not support inserting text into columns whose data type is set to image. For more information about 
SQL Server data types, see Data Types (Transact-SQL). 


NOTE 
The ADO NET destination does not support mapping an input column whose type is set to DT_DBTIME to a database 
column whose type is set to datetime. For more information about Integration Services data types, see Integration 


Services Data Types. 








The ADO NET destination has one regular input and one error output. 
You can set properties through SSIS Designer or programmatically. 


The Advanced Editor dialog box reflects the properties that can be set programmatically. For more 


information about the properties that you can set in the Advanced Editor dialog box or programmatically, click 
one of the following topics: 


e Common Properties 


e@ ADO NET Custom Properties 


For more information about how to set properties, see Set the Properties of a Data Flow Component. 


ADO NET Destination Editor (Connection Manager Page) 


Use the Connection Manager page of the ADO NET Destination Editor dialog box to select the ADO.NET 
connection for the destination. This page also lets you select a table or view from the database. 


To open the Connection Manager page 


1. In SQL Server Data Tools (SSDT), open the Integration Services package that has the ADO NET 
destination. 


2. On the Data Flow tab, double-click the ADO NET destination. 
3. Inthe ADO NET Destination Editor, click Connection Manager. 


Static Options 


Connection manager 


Select an existing connection manager from the list, or create a new connection by clicking New. 


New 
Create a new connection manager by using the Configure ADO.NET Connection Manager dialog box. 


Use a table or view 


Select an existing table or view from the list, or create a new table by clicking New.. 


New 
Create a new table or view by using the Create Table dialog box. 


NOTE 


When you click New, Integration Services generates a default CREATE TABLE statement based on the connected data 
source. This default CREATE TABLE statement will not include the FILESTREAM attribute even if the source table includes a 
column with the FILESTREAM attribute declared. To run an Integration Services component with the FILESTREAM 
attribute, first implement FILESTREAM storage on the destination database. Then, add the FILESTREAM attribute to the 
CREATE TABLE statement in the Create Table dialog box. For more information, see Binary Large Object (Blob) Data (SQL 
Server). 





Preview 


Preview results by using the Preview Query Results dialog box. Preview can display up to 200 rows. 


Use bulk insert when available 
Specify whether to use the SqIBulkCopy interface to improve the performance of bulk insert operations. 


Only ADO.NET providers that return a SqiConnection object support the use of the SqiBulkCopy interface. The 
.NET Data Provider for SQL Server (Sq!Client) returns a SqiConnection object, and a custom provider may return 
a SqlConnection object. 


You can use the .NET Data Provider for SQL Server (SqlClient) to connect to Microsoft Azure SQL Database. 


If you select Use bulk insert when available, and set the Error option to Redirect the row, the batch of 
data that the destination redirects to the error output may include good rows.For more information about 





handling errors in bulk operations, see Error Handling in Data. For more information about the Error option, see 
ADO NET Destination Editor (Error Output Page). 


NOTE 

If a SQL Server or Sybase source table includes an identity column, you must use Execute SQL tasks to enable 
IDENTITY_INSERT before the ADO NET destination and to disable it again afterward. (The identity column property 
specifies an incremental value for the column. The SET IDENTITY_INSERT statement lets explicit values from the source 


table be inserted into the identity column in the destination table.) 


To run the SET IDENTITY_INSERT statements and the data loading successfully, you have to do the following things. 

1. Use the same ADO.NET connection manager for the Execute SQL tasks and for the ADO.NET destination. 

2. On the connection manager, set the RetainSameConnection property and the MultipleActiveResultSets property 
to True. 

3. On the ADO.NET destination, set the UseBulkInsertWhenPossible property to False. 


For more information, see SET IDENTITY_INSERT (Transact-SQL) and IDENTITY (Property) (Transact-SQL). 











External Resources 


Technical article, Loading data to Azure SQL Database the fast way, on sqicat.com 


ADO NET Destination Editor (Mappings Page) 


Use the Mappings page of the ADO NET Destination Editor dialog box to map input columns to destination 


columns. 
To open the Mappings page 


1. In SQL Server Data Tools (SSDT), open the Integration Services package that has the ADO NET 
destination. 


2. On the Data Flow tab, double-click the ADO NET destination. 
3. Inthe ADO NET Destination Editor, click Mappings. 


Options 
Available Input Columns 
View the list of available input columns. Use a drag-and-drop operation to map available input columns in the 


table to destination columns. 


Available Destination Columns 
View the list of available destination columns. Use a drag-and-drop operation to map available destination 
columns in the table to input columns. 


Input Column 
View the input columns that you selected. You can remove mappings by selecting <ignore> to exclude 
columns from the output. 


Destination Column 


View each available destination column, regardless of whether it is mapped or not. 


ADO NET Destination Editor (Error Output Page) 


Use the Error Output page of the ADO NET Destination Editor dialog box to specify error handling options. 


To open the Error Output page 


1. In SQL Server Data Tools (SSDT), open the Integration Services package that has the ADO NET 
destination. 


2. On the Data Flow tab, double-click the ADO NET destination. 
3. In the ADO NET Destination Editor, click Error Output. 


Options 
Input or Output 
View the name of the input. 


Column 
Not used. 


Error 
Specify what should happen when an error occurs: ignore the failure, redirect the row, or fail the component. 


Related Topics: Error Handling in Data 


Truncation 
Not used. 


Description 
View the description of the operation. 


Set this value to selected cells 
Specify what should happen to all the selected cells when an error or truncation occurs: ignore the failure, 
redirect the row, or fail the component. 


Apply 
Apply the error handling option to the selected cells. 


ADO NET Custom Properties 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 
Source Custom Properties 
The ADO NET source has both custom properties and the properties common to all data flow components. 


The following table describes the custom properties of the ADO NET source. All properties are read/write. 


PROPERTY NAME DATA TYPE DESCRIPTION 


CommandTimeout String A value that specifies the number of 
seconds before the SQL command 
times out. A value of 0 indicates that 
the command never times out. 


SqlCommand String The SQL statement that the ADO NET 
source uses to extract data. 


When the package loads, you can 
dynamically update this property with 
the SQL statement that the ADO NET 
source will use. For more information, 
see Integration Services (SSIS) 
Expressions and Use Property 
Expressions in Packages. 


AllowlmplicitStringConversion Boolean A value that indicates whether the 
following occurs: 


-No generation of a validation error if 
there is a mismatch between external 
metadata types and output column 
types that are strings (DT_WSTR or 
DT_NTEXT). 

-Implicit conversion of external 


metadata types to the string data type 
that the output column uses. 


The default value is TRUE. 


For more information, see ADO NET 
Source. 


The output and the output columns of the ADO NET source have no custom properties. 

For more information, see ADO NET Source. 

Destination Custom Properties 

The ADO.NET destination has both custom properties and the properties common to all data flow components. 


The following table describes the custom properties of the ADO.NET destination. All properties are read/write. 


These properties are not available in the ADO NET Destination Editor, but can be set by using the Advanced 


Editor. 


PROPERTY 


BatchSize 


CommandTimeOut 


TableOrViewName 


DATA TYPE 


Integer 


Integer 


String 


For more information, see ADO NET Destination. 


See Also 


Common Properties 


DESCRIPTION 


The number of rows in a batch that is 
sent to the server. A value of 0 
indicates that the batch size matches 
the internal buffer size. The default 
value of this property is 0. 


The maximum number of seconds that 
the SQL command can run before 
timing out. A value of 0 indicates an 
infinite time. The default value of this 
property is 0. 


The name of the destination table or 
view. 


Azure Blob Source 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


The Azure Blob Source component enables an SSIS package to read data from an Azure blob. The supported 
file formats are: CSV and AVRO. 


To see the editor for the Azure Blob Source, drag and drop Azure Blob Source on the data flow designer and 
double-click it to open the editor). 


The Azure Blob Source is a component of the SQL Server Integration Services (SSIS) Feature Pack for Azure. 


1. For the Azure storage connection manager field, specify an existing Azure Storage Connection 
Manager or create a new one that refers to an Azure Storage Account. 


2. For the Blob container name field, specify the name of the blob container that contains source files. 
3. For the Blob name field, specify the path for the blob. 
4. For the Blob file format field, select the blob format you want to use, Text or Avro. 


5. If the file format is Text, you must specify the Column delimiter character value. (Multi-character 
delimiters are not supported.) 


Also select Column names in the first data row if the first row in the file contains column names. 
6. If the file is compressed, select Decompress the file. 


7. If the file is compressed, select the Compression type: GZIP, DEFLATE, or BZIP2. Note that the Zip 
format is not supported. 


8. After you specify the connection information, switch to the Columns page to map source columns to 
destination columns for the SSIS data flow. 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


The Azure Blob Destination component enables an SSIS package to write data to an Azure blob. The 
supported file formats are: CSV and AVRO. 


Drag-drop Azure Blob Destination to the data flow designer and double-click it to see the editor). 


The Azure Blob Destination is a component of the SQL Server Integration Services (SSIS) Feature Pack for 
Azure. 


1. For the Azure storage connection manager field, specify an existing Azure Storage Connection 
Manager or create a new one that refers to an Azure Storage Account. 


2. For the Blob container name field, specify the name of the blob container that contains source files. 
3. For the Blob name field, specify the path for the blob. 
4. For the Blob file format field, specify the blob format you want to use. 


5. If the file format is CSV, you must specify the Column delimiter character value. Also select Column 
names in the first data row if the first row in the file contains column names. 


6. After specifying the connection information, switch to the Columns page to map source columns to 
destination columns for the SSIS data flow. 


Azure Data Lake Store Source 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


The Azure Data Lake Store Source component enables an SSIS package to read data from an Azure Data 
Lake Store. The supported file formats are: Text and Avro. 


The Azure Data Lake Store Source is a component of the SQL Server Integration Services (SSIS) Feature 
Pack for Azure. 





NOTE 


To ensure that the Azure Data Lake Store Connection Manager and the components that use it - that is, the Azure Data 
Lake Store Source and the Azure Data Lake Store Destination - can connect to services, make sure you download the 
latest version of the Azure Feature Pack here. 











Configure the Azure Data Lake Store Source 


1. To see the editor for the Azure Data Lake Store Source, drag and drop Azure Data Lake Store Source 
on the data flow designer and double-click it to open the editor). 


2. For the Azure Data Lake Store connection manager field, specify an existing Azure Data Lake Store 
Connection Manager or create a new one that refers to an Azure Data Lake Store service. 


a. For the File Path field, specify the file path of the source file in Azure Data Lake Store. 
b. For the File format field, specify the file format of the source file. 


If the file format is Text, you must specify the Column delimiter character value. Also select 


Column names in the first data row if the first row in the file contains column names. 


3. After specifying the connection information, switch to the Columns page to map source columns to 
destination columns for the SSIS data flow. 


Text qualifier 


The Azure Data Lake Store Source does not support a text qualifier. If you have to specify a text qualifier to 
process your files correctly, consider downloading the files to your local computer and processing the files with 
the Flat File Source. The Flat File Source lets you specify a text qualifier. For more info, see Flat File Source. 


Azure Data Lake Store Destination 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


The Azure Data Lake Store Destination component enables an SSIS package to write data to an Azure Data 
Lake Store. The supported file formats are: Text, Avro, and ORC. 


The Azure Data Lake Store Destination is a component of the SQL Server Integration Services (SSIS) 
Feature Pack for Azure. 





NOTE 


To ensure that the Azure Data Lake Store Connection Manager and the components that use it - that is, the Azure Data 
Lake Store Source and the Azure Data Lake Store Destination - can connect to services, make sure you download the 
latest version of the Azure Feature Pack here. 











Configure the Azure Data Lake Store Destination 


1. Drag-drop Azure Data Lake Store Destination to the data flow designer and double-click it to see the 
editor. 


2. For the Azure Data Lake Store connection manager field, specify an existing Azure Data Lake Store 
Connection Manager or create a new one that refers to an Azure Data Lake Store service. 


a. For the File Path field, specify the file name you want to write data to. If this file already exists, its 
contents are overwritten. 


b. For the File format field, specify the file format you want to use. 


If the file format is Text, you must specify the Column delimiter character value. Also select Column 
names in the first data row if the first row in the file contains column names. 


If the file format is ORC, Java is required. See here for details. 


3. After specifying the connection information, switch to the Columns page to map source columns to 
destination columns for the SSIS data flow. 


Flexible File Source 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


The Flexible File Source component enables an SSIS package to read data from various supported storage 
services. Currently supported storage services are 


e Azure Blob Storage 
e Azure Data Lake Storage Gen2 


To see the editor for the Flexible File Source, drag and drop Flexible File Source on the data flow designer and 
double-click it to open the editor. 


The Flexible File Source is a component of the SQL Server Integration Services (SSIS) Feature Pack for Azure. 
Following properties are available on the Flexible File Source Editor. 


e File Connection Manager Type: Specifies the source connection manager type. Then choose an existing 
one of the specified type or create a new one. 


e Folder Path: Specifies the source folder path. 
e File Name: Specifies the source file name. 


e File Format: Specifies the source file format. Supported formats are Text, Avro, ORC, Parquet. Java is 
required for ORC/Parquet. See here for details. 


e Column delimiter character: Specifies the character used as column delimiter (multi-character delimiters 
are not supported). 


e First row as the column name: Specifies whether to treat first row as column names. 
e Decompress the file: Specifies whether to decompress the source file. 


e Compression Type: Specifies the source file compression format. Supported formats are GZIP, DEFLATE, 
BZIP2. 


Following properties are available on the Advanced Editor. 


e rowDelimiter: The character used to separate rows in a file. Only one character is allowed. The default 
value is \r\n. 


escapeChar: The special character used to escape a column delimiter in the content of input file. You cannot 
specify both escapeChar and quoteChar for a table. Only one character is allowed. No default value. 


quoteChar: The character used to quote a string value. The column and row delimiters inside the quote 

characters would be treated as part of the string value. This property is applicable to both input and output 

datasets. You cannot specify both escapeChar and quoteChar for a table. Only one character is allowed. No 
default value. 

e nullValue: One or more characters used to represent a null value. The default value is \N. 

e encodingName: Specify the encoding name. See Encoding.EncodingName Property. 

e skipLineCount: Indicates the number of non-empty rows to skip when reading data from input files. If both 
skipLineCount and firstRowAsHeader are specified, the lines are skipped first and then the header 
information is read from the input file. 

e treatEmptyAsNull: Specifies whether to treat null or empty string as a null value when reading data from 

an input file. The default value is True. 


After you specify the connection information, switch to the Columns page to map source columns to 


destination columns for the SSIS data flow. 
Notes on Service Principal Permission Configuration 


For Test Connection to work (either blob storage or Data Lake Storage Gen2), the service principal should be 
assigned at least Storage Blob Data Reader role to the storage account. This is done with RBAC. 


For blob storage, read permission is granted by assigning at least Storage Blob Data Reader role. 


For Data Lake Storage Gen2, permission is determined by both RBAC and ACLs. Pay attention that ACLs are 
configured using the Object ID (OID) of the service principal for the app registration as detailed here. This is 
different from the Application (client) ID that is used with RBAC configuration. When a security principal is 
granted RBAC data permissions through a built-in role, or through a custom role, these permissions are 
evaluated first upon authorization of a request. If the requested operation is authorized by the security 
principal's RBAC assignments, then authorization is immediately resolved and no additional ACL checks are 
performed. Alternatively, if the security principal does not have an RBAC assignment, or the request's operation 
does not match the assigned permission, then ACL checks are performed to determine if the security principal is 
authorized to perform the requested operation. For read permission, grant at least Execute permission starting 
from the source file system, along with Read permission for the files to read. Alternatively, grant at least the 
Storage Blob Data Reader role with RBAC. See this article for details. 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


The Flexible File Destination component enables an SSIS package to write data to various supported storage 
services. 


Currently supported storage services are 


e Azure Blob Storage 


e Azure Data Lake Storage Gen2 


Drag-drop Flexible File Destination to the data flow designer and double-click it to see the editor. 


The Flexible File Destination is a component of the SQL Server Integration Services (SSIS) Feature Pack for 
Azure. 


Following properties are available on the Flexible File Destination Editor. 


e File Connection Manager Type: Specifies the source connection manager type. Then choose an existing 
one of the specified type or create a new one. 


e Folder Path: Specifies the destination folder path. 
e File Name: Specifies the destination file name. 


e File Format: Specifies the destination file format. Supported formats are Text, Avro, ORC, Parquet. Java is 
required for ORC/Parquet. See here for details. 


e Column delimiter character: Specifies the character to use as column delimiter (multi-character 
delimiters are not supported). 


e First row as the column name: Specifies whether to write column names to first row. 
e Compress the file: Specifies whether to compress the file. 


e Compression Type: Specifies the compression format to use. Supported formats are GZIP, DEFLATE, 
BZIP2. 


e Compression Level: Specifies the compression level to use. 
Following properties are available on the Advanced Editor. 


e rowDelimiter: The character used to separate rows in a file. Only one character is allowed. The default 
value is \r\n. 


escapeChar: The special character used to escape a column delimiter in the content of input file. You cannot 
specify both escapeChar and quoteChar for a table. Only one character is allowed. No default value. 


quoteChar: The character used to quote a string value. The column and row delimiters inside the quote 
characters would be treated as part of the string value. This property is applicable to both input and output 
datasets. You cannot specify both escapeChar and quoteChar for a table. Only one character is allowed. No 
default value. 

e nullValue: One or more characters used to represent a null value. The default value is \N. 

e encodingName: Specify the encoding name. See Encoding.EncodingName Property. 

e skipLineCount: Indicates the number of non-empty rows to skip when reading data from input files. If both 
skipLineCount and firstRowAsHeader are specified, the lines are skipped first and then the header 


information is read from the input file. 


e treatEmptyAsNull: Specifies whether to treat null or empty string as a null value when reading data from 


an input file. The default value is True. 


After specifying the connection information, switch to the Columns page to map source columns to destination 


columns for the SSIS data flow. 
Notes on Service Principal Permission Configuration 


For Test Connection to work (either blob storage or Data Lake Storage Gen2), the service principal should be 
assigned at least Storage Blob Data Reader role to the storage account. This is done with RBAC. 


For blob storage, write permission is granted by assigning at least Storage Blob Data Contributor role. 


For Data Lake Storage Gen2, permission is determined by both RBAC and ACLs. Pay attention that ACLs are 
configured using the Object ID (OID) of the service principal for the app registration as detailed here. This is 
different from the Application (client) ID that is used with RBAC configuration. When a security principal is 
granted RBAC data permissions through a built-in role, or through a custom role, these permissions are 
evaluated first upon authorization of a request. If the requested operation is authorized by the security 
principal's RBAC assignments, then authorization is immediately resolved and no additional ACL checks are 
performed. Alternatively, if the security principal does not have an RBAC assignment, or the request's operation 
does not match the assigned permission, then ACL checks are performed to determine if the security principal is 
authorized to perform the requested operation. For write permission, grant at least Execute permission starting 
from the sink file system, along with Write permission for the sink folder. Alternatively, grant at least the 
Storage Blob Data Contributor role with RBAC. See this article for details. 


CDC Flow Components 
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Applies to: Q sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


The Change Data Capture Components by Attunity for Microsoft SQL Server 2019 Integration Services (SSIS) 
help SSIS developers work with CDC and reduce the complexity of CDC packages. 


The SSIS CDC components are designed to work with the SQL Server CDC feature where the source tables are 
either the same SQL Server database or an Oracle database (when using the Oracle CDC Service for SQL 
Server). Partitioned tables are supported. 


The components include Control and Data Flow components that streamline the experience of reading and 
processing change data in SSIS packages. The components can be added to the component library in Microsoft 
SQL Server, but are installed separately. 


The following are the Change Data Capture Components by Attunity: 
CDC Control Flow Component: 

CDC Control Task 

CDC Data Flow Components: 

CDC Source 


CDC Splitter 


Installation 


This section describes the installation procedures for the CDC Components for Microsoft SQL Server 2019 
Integration Services (SSIS). 


The CDC Components for SSIS are packaged with the MicrosoftA®) Change Data Capture Designer and Service 
for Oracle by Attunity for Microsoft SQL ServerAQ@). This download is part of the SQL Server Feature Pack. 
Download components of the Feature Pack from the SQL Server 2016 Feature Pack web page. 


Version Support 

SQL Server version support 

The CDC components for SSIS are supported on all the supported versions of Microsoft SQL Server. Currently, 
the supported versions of SQL Server include SQL Server 2012 through SQL Server 2017. 

Operating system version support 


The CDC components for SSIS are supported on the following operating systems and platforms: 


e Windows 8 and 8.1 

e Windows 10 

e Windows Server 2012 and 2012 R2 
e Windows Server 2016 


Running the Installation Program 


Before you run the installation wizard, be sure that the SQL ServerSQL Server Data Tools is closed. Then follow 
the directions in the installation wizard. 


Restart SSIS Service 


After you install the CDC components, you must restart the SSIS service to be sure that the components work 
correctly when developing packages in the SQL SQL Server Data Tools. 


A message is displayed after you install the components. Click Yes when prompted. 


Uninstalling the Microsoft CDC Components 


You uninstall the CDC source, CDC splitter, or CDC Control task, by using the uninstall wizard. If you are using 
the SQL ServerSQL Server Data Tools for package development, make sure the SQL Server Data Tools is closed 
before running the uninstall wizard. 


Benefits 


The CDC Components for SQL ServerIntegration Services components allow SSIS developers to easily build 
SSIS packages that process change data. These components enhance the ability of SSIS developers to deal with 
CDC and reduce the complexity of CDC packages. 


The SSIS CDC components are used to provide the change data in a way that is easy to further process it for 
replication, loading a data warehouse, updating slowly changing dimensions for OLAP auditing changes, or for 
additional possible uses. The type of further processing used is determined by the SSIS developer. 


The SSIS CDC components are designed to work with the SQL Server CDC feature with change tables that are in 
the same SQL Server database. 


Getting Started with the Change Data Capture Components 


A typical CDC package processes changes to a group of tables. The basic control flow part of this type of CDC 
package is shown in the following figure. This package is called a trickle-feed processing package. 
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This SQL Serverlntegration Services Control Flow contains two CDC Control Tasks and the Data Flow task. The 
first task called Get CDC Processing Range establishes the LSN range for the changes that are processed in 
the data-flow task called Process Changes. This range is established based on what was processed during the 
last package run and was saved in a persistent store. 


For more information about using the CDC Control Task, see CDC Control Task and CDC Control Task Editor. 


The following figure shows the Process Changes data flow, which conceptually shows how the changes are 
processes. 
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The steps illustrated in this figure are: 





e Changes for Table X is a CDC source that reads changes made to table X that were made in the CDC 
processing range determined in the parent control flow. 


e CDC Splitter X is used to split the changes into inserts, deletes, and updates. In this scenario, it is 
assumed that the CDC Source is configured to produce Net changes so that different change types can be 
processed in parallel. 


e The specific changes are then further processed downstream. In this illustration, the changes are inserted 
into tables using multiple ODBC Destinations but in actual cases the processing may be different. 


For more information about the CDC Source, see: 
CDC Source 

CDC Source Editor (Connection Manager Page) 
CDC Source Editor (Columns Page) 

CDC Source Editor (Error Output Page) 

For more information about the CDC Splitter, see: 
CDC Splitter 


One of the basic issues that require attention when building CDC packages is how the change processing 
interacts with the initial loading (or initial processing) of the data. 


The CDC components support three distinct initial loading and change processing scenarios: 


e Initial loading done with a database snapshot. In this case, change processing starts with the LSN of the 
snapshot event. 


e Initial loading from a quiescent database. In this case, no changes are made during initial loading so the 
current LSN is sampled at sometime during the initial load and change processing starts with that LSN. 


@ Initial loading from an active database. In this case, as the initial load is in progress, changes are made to 
the database and there is no single LSN from which change processing can be precisely started. In this 
case, the initial load package developer can sample the source database current LSN before and after the 
initial load. Then, when processing changes, care should be taken when processing changes made in 
parallel to the initial load as some of the processed changes are already seen in the initial load (for 
example, an Insert change may fail with a duplicate key error because the inserted row was read by the 


initial load process). 


The following figure shows an SSIS package that could handle the first two scenarios: 
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The following figure shows an SSIS package that could handle the third scenario: 
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Following the initial load package, a trickle-feed update package is run repeatedly according to a schedule to 
process changes as they become available for consumption. 


Passing the state of the CDC processing from the initial load package to the trickle feed package and between 
different tasks within each package occurs by means of a special SSIS package string variable. The value of this 
variable is referred to as the CDC State, which reflects the current state of CDC processing for the groups of 
tables being handled by the initial load and trickle-feed packages. 


The value of the CDC State variable needs to be maintained in persistent storage. It should be read before 
starting CDC processing and should be saved with the current state after processing completed. The task of 
loading and storing of the CDC state can be handled by the SSIS developer but the CDC Control component can 
automate this task by maintaining the CDC State value in a database table. 


Security Considerations 


This section lists some security considerations related to the use of the CDC components in SSIS. 


Access Authorization to Change Data 


Trickle-feed update packages need access to SQL Server CDC functions. Such access is granted, by default, to 
members of the db_owner fixed database role. Because the db_owner is a powerful role, when defining 
capture instances within SQL Server it is recommended to associate a gating security role to each capture 


instance that allows the SSIS CDC package to use a much more restricted user for processing the changes. 


Access to CDC Database Current LSN 


The CDC Control task operations for marking the start LSN for change processing must be able to find the CDC 
Database current LSN. The components find the LSN by using the procedure sp_replincrementisn from the 
master database. Execute permission on this procedure must be given to the login used for connecting to the 
SQL Server CDC database. 


Access to CDC States Table 


The CDC States table is used for automatically persisting CDC States that need to be updatable by the login used 
for connecting to the SQL Server CDC database. As this table is created by the SSIS developer, set the SQL 
Server system administrator as a user who is authorized to create SQL Server databases and perform 
administrative and maintenance tasks. In addition, a SQL Server system administrator who works with CDC 


enabled databases must be knowledgeable about SQL Server CDC technology and implementation. 


Grouping Tables for CDC Processing 


Database projects range in size from several tables to many thousands of tables. When designing initial load 
and CDC packages, it is beneficial to group tables in much smaller groups for easier management and efficiency. 
This section lists various considerations that impact the sorting of tables into small groups, where the tables in 
each are initially loaded and then updated as a group. 


The CDC patterns supported by the CDC components assume that this grouping is already determined. Each 
group defines a separate CDC context that is maintained separately from other groups. For each group, initial- 
load and trickle-feed update packages are created. Trickle-feed updates are scheduled for periodic runs based on 
the rate of change processing constraints (for example, CPU and IO consumption, impact on other systems) and 
the desired latency. 


Tables are grouped based on the following considerations: 


1. According to the target database. All tables that are written to different target databases or undergo 
different processing should be assigned to different CDC groups. 


2. Tables that are related with referential integrity constraints should be assigned to the same group to 
avoid referential integrity problems at the target. 


3. Tables for which higher latency can be tolerated can be grouped so they can be processed less frequently 
and reduce overall system load. 


4. Tables for which there is a higher rate of change should be in smaller groups, and tables with a low rate 
of change can be grouped in larger groups. 


The following two packages are created for each CDC group: 


e An Initial Load package, which reads the entire range of data from the source tables and applies it to the 
target tables. 


e Atrickle-feed update package that reads changes made to the source tables and applies the changes to 
the target tables. This package should be executed on a regularly scheduled basis. 


CDC State 


Each CDC group has a state associated with it, which is represented by a string with a specific format. For more 
information, see CDC Control Task. The following table shows the possible CDC state values. 


STATE DESCRIPTION 


0-(INITIAL) The state that exists before any packages are run on the 
current CDC group. This is also the state when the CDC 
state is empty. 


For more information about CDC Control task operations, 
see CDC Control Task. 


STATE 


1-ILSTART (Initial-Load-Started) 


2- ILEND (Initial-Load-Ended) 


3-ILUPDATE (Initial Load Update) 


4-TFEND (Trickle-Feed-Update-Ended) 


5-TFSTART (Trickle-Feed-Update-Started) 


6-TFREDO (Reprocessing-Trickle-Feed-Updates) 


7-ERROR 


DESCRIPTION 


This is the state that exists when the initial load package 
starts. This occurs after the MarkInitialLoadStart 
operation call to the CDC Control task. 


For more information about CDC Control task operations, 
see CDC Control Task. 


This is the state that exists when the initial load package 
ends successfully. This occurs after the MarklnitialLoadEnd 
operation call to the CDC Control task. 


For more information about CDC Control task operations, 
see CDC Control Task. 


This is the state that exists after the first run of the Update 
package after the initial load while still processing the initial 
processing range. This occurs after the 
GetProcessingRange operation call to the CDC control 
task. 


If using the _$reprocessing column, it is set to 1 to 
indicate that the package may be reprocessing rows already 
at the target. 


For more information about CDC Control task operations, 
see CDC Control Task. 


This is the state expected for regular CDC runs. It indicates 
that the previous run completed successfully and that a new 
run with a new processing range can be started. 


This is the state that exists on subsequent runs of the 
Update package after the GetProcessingRange operation 
call to the CDC control task. 


This indicates that a regular CDC run is started, but is not 
finished or has not yet finished, cleanly 
(MarkProcessedRange). 


For more information about CDC Control task operations, 
see CDC Control Task. 


This is the state on a GetProcessingRange that occurs 
after TFSTART. This indicates that the previous run did not 
complete successfully. 


If using the __$reprocessing column, it is set to 1 to indicate 


that the package may be reprocessing rows already at the 
target. 


The CDC group is in an ERROR state. 


Here is the state diagram for the CDC components. An ERROR state is reached when a state is reached that is 


not expected. The expected states are illustrated in the following diagram. However the diagram does not show 


the ERROR state. 


For example, at the end of an initial load package, when trying to set the state to ILEND, if the state is TFSTART 


then the CDC group is in an error state and the Trickle-Feed Update package does not run (the Initial Load 


package does run). 


State Diagram from a CDC Group 
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Once the Initial Load package runs successfully, the Trickle-Feed Update package runs repeatedly under a 
predetermined schedule to process changes to the source tables. Each run of the Trickle-Feed Update package is 
a CDC run. 


In This Section 


e CDC Source 


e CDC Splitter 


Related Tasks 
e Direct the CDC Stream According to the Type of Change 


e Define a State Variable 


Related Content 
e Blog entry, CDC in SSIS for SQL Server 2012, on mattmasson.com. 
e Blog entry on setting up the CDC service, CDC for Oracle in SQL Server 2012, on blogs.msdn.com. 


e Technical article, Installing Microsoft SQL Server 2012 Change Data Capture for Oracle by Attunity, on 
social.technet.microsoft.com. 


@ Technical article, Troubleshoot Configuration Issues in Microsoft Change Data Capture for Oracle by 
Attunity, on social.technet.microsoft.com. 


@ Technical article, Troubleshoot CDC Instance Errors in Microsoft Change Data Capture for Oracle by 
Attunity, on social.technet.microsoft.com. 


e Video, CDC for Oracle Databases using SQL Server Integration Services 2012 (SQL Server Video), on 
technet.microsoft.com. 


See Also 


CDC Control Task 
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The CDC source reads a range of change data from SQL Server change tables and delivers the changes 
downstream to other SSIS components. 


The range of change data read by the CDC source is called the CDC Processing Range and is determine by the 
CDC Control task that is executed before the current data flow starts. The CDC Processing Range is derived from 
the value of a package variable that maintains the state of the CDC processing for a group of tables. 


The CDC source extracts data from a SQL Server database by using a database table, a view, or an SQL 
statement. 


The CDC source uses the following configurations: 


e ASQL Server ADO.NET connection manager to access the SQL Server CDC database. For more 
information about configuring the CDC source connection, see CDC Source Editor (Connection Manager 
Page). 


e A table enabled for CDC. 
@ The name of the capture instance of the selected table (if more-than-one exists). 
e The change processing mode. 


@ The name of the CDC state package variable based on which the CDC Processing range is determined. 
The CDC source does not modify that variable. 


The data returned by the CDC Source is the same as that returned by the SQL Server CDC functions 
cdc.fn_cdc_get_all_changes_<capture-instance-name> or cdc.fn_cdc_get_net_changes_<capture- 
instance-name> (when available). The only optional addition is the column, __$initial_processing that 
indicates whether the current processing range can overlap with an initial load of the table. For more 
information about initial processing, see CDC Control Task. 


The CDC source has one regular output and one error output. 


Error Handling 

The CDC source has an error output. The component error output includes the following output columns: 
e Error Code: The value is always -1. 

e Error Column: The source column causing the error (for conversion errors). 


e Error Row Columns: The record data that causes the error. 


Depending on the error behavior setting, the CDC source supports returning errors (data conversion, 
truncation) that occur during the extraction process in the error output. 


Data Type Support 


The CDC source component for Microsoft supports all SQL Server data types, which are mapped to the correct 
SSIS data types. 


Troubleshooting the CDC Source 


The following contains information on troubleshooting the CDC source. 


Use this script to isolate problems and reproduce them in SQL Server Management Studio 


The CDC source operation is governed by the operation of the CDC Control task executed before invoking the 
CDC source. The CDC Control task prepares the value of the CDC state package variable to contain the start and 
end LSNs. It performs function equivalent to the following script: 


use <cdc-enabled-database-name> 
declare @start_lsn binary(1@), @end_lsn binary(10) 
set @start_Isn = sys.fn_cdc_increment_lsn( 
convert(binary(10),'@x' + '<value-from-state-cs>', 1)) 
set @end_lsn = 
convert(binary(10),'@x' + '<value-from-state-ce>', 1) 
select * from cdc.fn_cdc_get_net_changes_dbo_Table1(@start_lsn, 
@end_lsn, '<mode>') 





where: 
e <cdc-enabled-database-name> is the name of the SQL Server database containing the change tables. 


e <value-from-state-cs> is the value that appears in the CDC state variable as CS/<value-from-state-cs>/ 
(CS stands for Current-processing-range-Start). 


e <value-from-state-ce> is the value that appears in the CDC state variable as CE/<value-from-state-cs>/ 
(CE stands for Current-processing-range-End). 


@ <mode> are the CDC processing modes. The processing modes have one of the following values All, All 
with Old Values, Net, Net with Update Mask, Net with Merge. 


This script helps isolate problems by reproducing them in the SQL Server Management Studio, where it is easy 
to reproduce and identify errors. 


SQL Server Error Message 


The following message may be returned by SQL Server: 


An insufficient number of arguments were supplied for the procedure or function 
cdc.fn_cdc_get_net_changes_<..>. 


This error does not indicate that an argument is missing. It means that the start or end LSN values in the CDC 
state variable are invalid. 


Configuring the CDC Source 


You can configure the CDC source programmatically or through the SSIS Designer. 

For more information, see one of the following topics: 

e CDC Source Editor (Connection Manager Page) 

e CDC Source Editor (Columns Page) 

e CDC Source Editor (Error Output Page) 

The Advanced Editor dialog box contains the properties that can be set programmatically. 
To open the Advanced Editor dialog box: 


e Inthe Data Flow screen of your SQL Server 2019 Integration Services (SSIS) project, right click the CDC 


source and select Show Advanced Editor. 


For more information about the properties that you can set in the Advanced Editor dialog box, see CDC 
Source Custom Properties. 


In This Section 


e CDC Source Custom Properties 


e Extract Change Data Using the CDC Source 


CDC Source Editor (Connection Manager Page) 


Use the Connection Manager page of the CDC Source Editor dialog box to select the ADO.NET connection 
manager for the SQL Server database that the CDC source reads change rows from (the CDC database). Once 
the CDC database is selected you need to select a captured table in the database. 


For more information about the CDC source, see CDC Source. 


Task List 


To open the CDC Source Editor Connection Manager Page 


1. In SQL Server Data Tools, open the SQL Server 2019 Integration Services (SSIS) package that has the 
CDC source. 


2. On the Data Flow tab, double-click the CDC source. 
3. Inthe CDC Source Editor, click Connection Manager. 


Options 
ADO.NET connection manager 


Select an existing connection manager from the list, or click New to create a new connection. The connection 
must be to a SQL Server database that is enabled for CDC and where the selected change table is located. 


New 
Click New. The Configure ADO.NET Connection Manager Editor dialog box opens where you can create a 


new connection manager 


CDC Table 
Select the CDC source table that contains the captured changes that you want read and feed to downstream 
SSIS components for processing. 


Capture instance 
Select or type in the name of the CDC capture instance with the CDC table to be read. 


A captured source table can have one or two captured instances to handle seamless transitioning of table 
definition through schema changes. If more than one capture instance is defined for the source table being 
captured, select the capture instance you want to use here. The default capture instance name for a table 
[schema].[table] is <schema>_<table> but that actual capture instance names in use may be different. The 
actual table that is read from is the CDC table cdc .<capture-instance>_CT. 


CDC Processing Mode 
Select the processing mode that best handles your processing needs. The possible options are: 


e All: Returns the changes in the current CDC range without the Before Update values. 


e All with old values: Returns the changes in the current CDC processing range including the old values 
(Before Update). For each Update operation, there will be two rows, one with the before-update values 
and one with the after-update value. 


e Net: Returns only one change row per source row modified in the current CDC processing range. If a 
source row was updated multiple times, the combined change is produced (for example, insert+ update is 
produced as a single update and update+delete is produced as a single delete). When working in Net 
change processing mode, it is possible to split the changes to Delete, Insert and Update outputs and 
handle them in parallel because the single source row appears in more than one output. 


e Net with update mask: This mode is similar to the regular Net mode but it also adds boolean columns 
with the name pattern__$<column-name>__Changed that indicate changed columns in the current 


change row. 


e Net with merge: This mode is similar to the regular Net mode but with Insert and Update operations 
merged into a single Merge operation (UPSERT). 





NOTE 


For all Net change options, the source table must have a primary key or unique index. For tables without a primary key or 


unique indes, you must yse the All option. 





Variable containing the CDC state 
Select the SSIS string package variable that maintains the CDC state for the current CDC context. For more 
information about the CDC state variable, see Define a State Variable. 


Include reprocessing indicator column 
Select this check box to create a special output column called__$reprocessing. 


This column has a value of true when the CDC processing range overlaps with the initial processing range (the 
range of LSNs corresponding to the period of initial load) or when a CDC processing range is reprocessed 
following an error in a previous run. This indicator column lets the SSIS developer handle errors differently 
when reprocessing changes (for example, actions such as a delete of a non-existing row and an insert that failed 
on a duplicate key can be ignored). 


For more information, see CDC Source Custom Properties. 


CDC Source Editor (Columns Page) 


Use the Columns page of the CDC Source Editor dialog box to map an output column to each external 
(source) column. 

Task List 

To open the CDC Source Editor Columns Page 


1. In SQL Server Data Tools, open the SQL Server 2019 Integration Services (SSIS) package that has the 
CDC source. 


2. On the Data Flow tab, double-click the CDC source. 
3. Inthe CDC Source Editor, click Columns. 


Options 

Available External Columns 

A list of available external columns in the data source. You cannot use this table to add or delete columns. Select 
the columns to use in the source. The selected columns are added to the External Column list in the order they 
are selected. 


External Column 
A view of the external (source) columns in the order that you see them when configuring components that 





consume data from the CDC source. To change this order, first clear the selected columns in the Available 
External Columns list, and then select external columns from the list in a different order. The selected columns 


are added to the External Column list in the order you select them. 


Output Column 
Enter a unique name for each output column. The default is the name of the selected external (source) column, 
however you can choose any unique, descriptive name. The name entered is displayed in the SSIS Designer. 


CDC Source Editor (Error Output Page) 


Use the Error Output page of the CDC Source Editor dialog box to select error handling options. 


Task List 
To open the CDC Source Editor Error Output Page 


1. In SQL Server Data Tools, open the SQL Server 2019 Integration Services (SSIS) package that has the 
CDC source. 


2. On the Data Flow tab, double-click the CDC source. 
3. In the CDC Source Editor, click Error Output. 


Options 


Input/Output 
View the name of the data source. 


Column 
View the external (source) columns that you selected on the Connection Manager page of the CDC Source 
Editor dialog box. 


Error 
Select how the CDC source should handle errors in a flow: ignore the failure, redirect the row, or fail the 


component. 


Truncation 
Select how the CDC source should handle truncation in a flow: ignore the failure, redirect the row, or fail the 


component. 


Description 
Not used. 


Set this value to selected cells 
Select how the CDC source handles all selected cells when an error or truncation occurs: ignore the failure, 


redirect the row, or fail the component. 


Apply 
Apply the error handling options to the selected cells. 


Error Handling Options 


You use the following options to configure how the CDC source handles errors and truncations. 


Fail Component 
The Data Flow task fails when an error or a truncation occurs. This is the default behavior. 


Ignore Failure 
The error or the truncation is ignored and the data row is directed to the CDC source output. 


Redirect Flow 
The error or the truncation data row is directed to the error output of the CDC source. In this case the CDC 


source error handling is used. For more information, see CDC Source. 


Related Content 


e Blog entry, Processing Modes for the CDC Source, on mattmasson.com. 
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The following table describes the custom properties of the CDC source. All properties are read/write. 


PROPERTY NAME DATA TYPE DESCRIPTION 


Connection ADO.Net Connection An ADO.NET connection to the SQL 
Server CDC database for access to the 
change tables. 


StateVariable String An SSIS string package variable that 
maintains the CDC state of the current 
CDC run. 

CdcProcessingMode Integer (enumeration) This mode determines how processing 


is handled. The possible options are 
All, All with old values, Net, Net 
with update mask, and Net with 
merge. 


Modes that start with All return all 
changes and modes that start with 
Net return net changes only. 


Tables without a primary key can take 
the ALL values only. 


Net with Update Mask adds 
boolean columns with the name 
pattern __$<column- 
name>__Changed that indicate 
changed columns in the current 
change row. 


For additional information about the 
values for this property, see CDC 
Source Editor (Connection Manager 
Page). 


PROPERTY NAME DATA TYPE 


Capturelnstance String 
ReprocessingIndicator Boolean 
CommandTimeout Integer 


For more information about the CDC source, see CDC Source. 


DESCRIPTION 


The name of the CDC capture instance 
with the CDC table to be read. A 
captured source table can have one or 
two captured instances to handle 
seamless transitioning of table 
definition through schema changes. If 
more than one capture instance is 
defined for the source table being 
captured, select the capture instance 
you want to use here. The default 
capture instance name for a table 
[schema].[table] is <schema>_<table> 
but that actual capture instance names 
in use may be different. The actual 
table that is read from is the CDC table 
cdc .<capture-instance>_CT. 


A value that specifies whether to add 
the ___$reprocessing column. This 
special output column lets the SSIS 
developer handle consistency errors 
differently when working on the Initial 
Processing Range. 


If true, the__$reprocessing column 
is added. 


This column value is true when the 
CDC processing range overlaps with 
the initial processing range (the range 
of LSNs corresponding to the period of 
initial load) or when a CDC processing 
range is reprocessed following an error 
in a previous run. This indicator 
column lets the SSIS developer handle 
errors differently when reprocessing 
changes (for example, actions such as a 
delete of a non-existing row and an 
insert that failed on a duplicate key 
can be ignored). 


The default value is false. 


This value indicates the timeout (in 
seconds) to use when communicating 
with the SQL Server database. This 
value is used where the response time 
from the database is very slow and the 
default value(30 seconds) is not 
enough. 


Extract Change Data Using the CDC Source 
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To add and configure a CDC source, the package must already include at least one Data Flow task and a CDC 
Control task. 


For more information about the CDC Control task, see CDC Control Task. 
For more information about the CDC source, see CDC Source. 


To extract change data using a CDC source 


1. In SQL Server Data Tools, open the SQL Server 2019 Integration Services (SSIS) project that contains the 
package you want. 


2. In the Solution Explorer, double-click the package to open it. 
3. Click the Data Flow tab, and then from the Toolbox, drag the CDC source to the design surface. 
4. Double-click the CDC source. 


5. In the CDC Source Editor dialog box, on the Connection Manager page, select an existing ADO.NET 
connection manager from the list, or click New to create a new connection. The connection should be to a 
SQL Server database that contains the change tables to read. 


6. Select the CDC table where you want to process changes. 
7. Select or type in the name of the CDC capture instance with the CDC table to be read. 


A captured source table can have one or two captured instances to handle seamless transitioning of table 
definition through schema changes. If more than one capture instance is defined for the source table 
being captured, select the capture instance you want to use here. The default capture instance name for a 
table [schema].[table] is <schema>_<table> but that actual capture instance names in use may be 
different. The actual table that is read from is the CDC table cdc .<capture-instance>_CT. 


8. Select the processing mode that best handles your processing needs. The possible options are: 
e All: Returns the changes in the current CDC range without the Before Update values. 


e All with old values: Returns the changes in the current CDC processing range including the old 
values (Before Update). For each Update operation, there will be two rows, one with the before- 
update values and one with the after-update value. 


e Net: Returns only one change row per source row modified in the current CDC processing range. 
If a source row was updated multiple times, the combined change is produced (for example, 
insert+update is produced as a single update and update+delete is produced as a single delete). 
When working in Net change processing mode, it is possible to split the changes to Delete, Insert 
and Update outputs and handle them in parallel because the single source row appears in more 
than one output. 


e Net with update mask: This mode is similar to the regular Net mode but it also adds boolean 
columns with the name pattern __$<column-name>__Changed that indicate changed columns 
in the current change row. 


e Net with merge: This mode is similar to the regular Net mode but with Insert and Update 


9. 


10. 
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operations merged into a single Merge operation (UPSERT). 


Select the SSIS string package variable that maintains the CDC state for the current CDC context. For 
more information about the CDC state variable, see Define a State Variable. 


Select the Include reprocessing indicator column check box to create a special output column called 
__$reprocessing. This column has a value of true when the CDC processing range overlaps with the 
initial processing range (the range of LSNs corresponding to the period of initial load) or when a CDC 
processing range is reprocessed following an error in a previous run. This indicator column lets the SSIS 
developer handle errors differently when reprocessing changes (for example, actions such as a delete of a 
non-existing row and an insert that failed on a duplicate key can be ignored). 


For more information, see CDC Source Custom Properties. 


To update the mapping between external and output columns, click Columns and select different 
columns in the External Column list. 


Optionally update the values of the output columns by deleting values in the Output Column list. 
To configure the error output, click Error Output. 
You can click Preview to view up to 200 rows of data extracted by the CDC source. 


Click OK. 


See Also 


CDC Source Editor (Connection Manager Page) 


CDC Source Editor (Columns Page) 
CDC Source Editor (Error Output Page) 


CDC Splitter 


11/23/2021 * 2 minutes to read « Edit Online 





Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


The CDC splitter splits a single flow of change rows from a CDC source data flow into different data flows for 
Insert, Update and Delete operations. The data flow is split based on the required column _ $operation and its 
standard values in SQL Server change tables. 


VALUE OF OPERATION OUTPUT DESCRIPTION 
1 Delete Deleted Row 
2 Insert Inserted row (not available when using 


Net with Merge CDC mode) 


3 Update Before-update row (available only 
when using All with Old Values CDC 
mode) 

4 Update After-update row (follows the Before- 
update) 

5 Update Merge row (available only when using 


Net with Merge CDC mode) 


Other Error 


You can use the splitter to connect to pre-defined INSERT, DELETE, and UPDATE outputs for further processing. 


The CDC Splitter transformation has one regular input and one error output. 


Error Handling 


The CDC Splitter transformation has an error output. Input rows with an invalid value of the $operation column 
are considered erroneous and are handled according to the ErrorRowDisposition property of the input. 


The component error output includes the following output columns: 
e Error Code: Set to 1. 
e Error Column: The source column causing the error (for conversion errors). 


e Error Row Columns: The input columns of the row that caused the error. 


Configuring the CDC Splitter 


There are no configurable properties for the CDC splitter. 


For more information about using the CDC splitter, see CDC Components for Microsoft SQL Server Integration 
Services. 


The Advanced Editor dialog box contains the properties that can be set programmatically. 


To open the Advanced Editor dialog box: 


e Inthe Data Flow screen of your SQL Server 2019 Integration Services (SSIS) project, right click the CDC 
splitter and select Show Advanced Editor. 


See Also 


Direct the CDC Stream According to the Type of Change 


Direct the CDC Stream According to the Type of 


Change 
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To add and configure a CDC splitter Transformation, the package must contain at least one Data Flow task anda 
CDC source. 


The CDC source added to the package must have a NetCDC processing mode selected. For more information on 
selecting processing modes, see CDC Source Editor (Connection Manager Page). 


To direct the CDC stream according to the type of change 


1. In SQL Server Data Tools, open the SQL Server 2019 Integration Services (SSIS) project that contains the 
package you want. 


2. In the Solution Explorer, double-click the package to open it. 
3. Click the Data Flow tab, and then from the Toolbox, drag the CDC splitter to the design surface. 
4. Connect the CDC source that is included in the package to the CDC Splitter. 
5. Connect the CDC splitter to one or more destinations. You can connect up to three different outputs. 
6. Select one of the following outputs: 
e Delete output: The output where DELETE change rows are directed. 
e Insert output: The output where INSERT change rows are directed. 


e Update output: The output where before/after UPDATE change rows and Merge change rows are 
directed. 


7. Optionally, you can configure the advanced properties using the Advanced Editor dialog box. 
The Advanced Editor dialog box contains the properties that can be set programmatically. 
To open the Advanced Editor dialog box: 


e Inthe Data Flow screen of your SQL Server 2019 Integration Services (SSIS) project, right click the 
CDC splitter and select Show Advanced Editor. 


For more information about using the CDC splitter see CDC Components for Microsoft SQL Server 
Integration Services. 


See Also 


CDC Splitter 
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This procedure describes how to define a package variable where the CDC state is stored. 


The CDC state variable is loaded, initialized, and updated by the CDC Control task and is used by the CDC Source 
data flow component to determine the current processing range for change records. The CDC state variable can 
be defined on any container common to the CDC Control task and the CDC source. This may be at the package 
level but may also be on other containers such as a loop container. 


Manually modifying the CDC state variable value is not recommended, however it can be useful to understand 
its contents. 


The following table provides a high-level description of the components of the CDC state variable value. 


COMPONENT DESCRIPTION 

<state-name> This is the name of the current CDC state. 

cs This marks the current processing range start point (Current 
Start). 

<cs-Isn> This is the last (Log Sequence Number) LSN processed in the 


previous CDC run. 


CE This marks the current processing range end point (Current 
End). The presence of the CE component in the CDC state is 
an indication that either a CDC package is currently 
processing or that a CDC package failed before fully 
processing its CDC processing range. 


<ce-Isn> This is the last LSN to be processed in the current CDC Run. 
It is always assumed that the last sequence number to be 
processed is the maximum (OxFFF...). 


IR This marks the initial processing range. 

<ir-start> This is an LSN of a change just before the initial load began. 
<ir-end> This is an LSN of a change just after the initial load ended. 
TS This marks the timestamp for the last CDC state update. 
<timestamp> This is a decimal representation of the 64-bit, 


System.DateTime.UtcNow property. 


ER This appears when the last operation failed and includes a 
short description of the cause of the error. If this component 
is present, it will always appear last. 


COMPONENT 


<short-error-text> 


DESCRIPTION 


This is the short error description. 


The LSNs and sequence numbers are each encoded as a hexadecimal string of up to 20 digits representing the 


LSN value of Binary(10). 


The following table describes the possible CDC state values. 


STATE 


(INITIAL) 


ILSTART (Initial Load Started) 


ILEND (Initial Load Ended) 


ILUPDATE (Initial Load Update) 


TFEND (Trickle-Feed Update Ended) 


TFSTART 


TFREDO (Reprocessing Trickle-Feed Updates) 


ERROR 


The following are examples of CDC state variable values. 


DESCRIPTION 


This is the initial state before the any package was run on 
the current CDC group. This is also the state when the CDC 
state is empty. 


This is the state when the initial load package starts, after 
the MarkInitialLoadStart operation call to the CDC 
Control task. 


This is the state when the initial load package ends 
successfully, after the MarkInitialLoadEnd operation call to 
the CDC Control task. 


This is the state on the runs of the trickle feed update 
package following the initial load, while still processing the 
initial processing range. This is after the 
GetProcessingRange operation call to the CDC Control 
task. 


If using the __$reprocessing column, it is set to 1 to indicate 
that the package may be re-processing rows already at the 
target. 


This is the state expected for regular CDC runs. It indicates 
that the previous run completed successfully and that a new 
run with a new processing range can be started. 


This is the state on a non-initial run of the trickle feed 
update package, after the GetProcessingRange operation 
call to the CDC Control task. 


This indicates that a regular CDC run is started but has not 
finished or has not yet finished, cleanly 
(MarkProcessedRange). 


This is the state on a GetProcessingRange that occurs 
after TFSTART. This indicates that the previous run did not 
complete successfully. 


If using the __$reprocessing column, it is set to 1 to indicate 


that the package may be re-processing rows already at the 
target. 


The CDC group is in an ERROR state. 


e@ ILSTART/IR/Ox0000162B158700000000//TS/201 1-08-07T17:10:43.0031645/ 


e |ILSTART/IR/Ox0000162B158700000000//TS/201 1-08-07T17:10:43.0031645/ 


e TFEND/CS/0x0000025B000001BC0003/TS/2011-07-17T12:05:58.1001145/ 


TFSTART/CS/0x0000030D000000AE0003/CE/0x0000159D1E0F01000000/TS/2011-08- 
09T05:30:43.9344900/ 


e TFREDO/CS/0x0000030D000000AE0003/CE/0x0000159D1E0F01000000/TS/201 1 -08- 
09T05:30:59.5544900/ 


To define a CDC state variable 


1. In SQL Server Data Tools, open the SQL Server 2019 Integration Services (SSIS) package that has the 
CDC flow where you need to define the variable. 


2. Click the Package Explorer tab, and add a new variable. 

3. Give the variable a name that you can recognize as your state variable. 

4. Give the variable a String data type. 

Do not give the variable a value as part of its definition. The value must be set by the CDC Control task. 


If you plan to use the CDC Control task with Automatic State Persistence, the CDC State variable will be read 
from the database state table you specify and will be updated back to that same table when its value changes. 
For more information about the State table, see CDC Control Taskand CDC Control Task Editor. 


If you are not using the CDC Control task with Automatic State Persistence then you must load the variable value 
from persistent storage where its value was saved the last time the package ran and to write it back to the 
persistent storage when the processing of the current processing range was completed. 


See Also 


CDC Control Task 
CDC Control Task Editor 


Data Mining Model Training Destination 
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The Data Mining Model Training destination trains data mining models by passing the data that the destination 
receives through the data mining model algorithms. Multiple data mining models can be trained by one 
destination if the models are built on the same data mining structure. For more information, see Mining 
Structure Columns and Mining Model Columns. 


Configuration of the Data Mining Model Training Destination 


If a case level column of the target structure and the models built on the structure has the content type KEY TIME 
or KEY SEQUENCE, the input data must be sorted on that column. For example, models built using the Microsoft 
Time Series algorithm use the content type KEY TIME. If input data is not sorted, the processing of the model 
may fail. If the data requires sorting, you can use a Sort transformation earlier in the data flow to sort the data. 
This requirement does not apply to columns with the KEY content type. For more information, see Content Types 
(Data Mining) and Sort Transformation. 


NOTE 


The input to the Data Mining Model training destination must be sorted. To sort the data, you can include a Sort 
destination upstream from the Data Mining Model Training destination in the data flow. For more information, see Sort 
Transformation. 











This destination has one input and no output. 


The Data Mining Model Training destination uses an SQL Server Analysis Services connection manager to 
connect to the Analysis Services project or the instance of Analysis Services that contains the mining structure 
and mining models that the destination trains. For more information, see Analysis Services Connection 
Manager. 


You can set properties through SSIS Designer or programmatically. 


The Advanced Editor dialog box reflects the properties that can be set programmatically. For more 
information about the properties that you can set in the Advanced Editor dialog box or programmatically, click 
one of the following topics: 


@ Common Properties 
e Data Mining Model Training Destination Custom Properties 


For more information about how to set properties, see Set the Properties of a Data Flow Component. 


Data Mining Model Training Editor (Connection Tab) 


Use the Connection page of the Data Mining Model Training Editor dialog box to select a mining model to 
train. 
Options 


Connection manager 


Select from the list of existing Analysis Services connections, or create a new Analysis Services connection by 


using the New button described as follows. 


New 
Create a new connection by using the Add Analysis Services Connection Manager dialog box. 


Mining structure 
Select from the list of available mining structures, or create a new structure by clicking New. 


New 
Create a new mining structure and mining model by using the Data Mining Wizard. 


Mining models 
View the list of mining models associated with the selected mining structure. 


Data Mining Model Training Editor (Columns Tab) 


Use the Columns page of the Data Mining Model Training Editor dialog box to map input columns to 
columns in the mining structure. 


Options 


Available Input Columns 
View the list of available input columns. Drag input columns to map them to mining structure columns. 


Mining Structure Columns 
View the list of mining structure columns. Drag mining structure columns to map them to available input 


columns. 


Input Column 
View input columns selected from the table above. To change or remove a mapping selection, use the list of 
Available Input Columns. 


Mining Structure Columns 
View each available destination column, whether mapped or not. 
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The Data Mining Model Training destination has both custom properties and the properties common to all data 
flow components. 


The following table describes the custom properties of the Data Mining Model Training destination. All 
properties are read/write. 


PROPERTY DATA TYPE DESCRIPTION 

ASConnectionld String The unique identifier of the connection 
manager. 

ASConnectionString String The connection string to an instance of 


Analysis Services or to an Analysis 
Services project. 


ObjectRef String An XML tag that identifies the data 
mining structure that the 
transformation uses. 


The input and the input columns of the Data Mining Model Training destination have no custom properties. 


For more information, see Data Mining Model Training Destination. 


See Also 


Common Properties 


Data Streaming Destination 
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The Data Streaming Destination is a SQL Server Integration Services (SSIS) destination component that lets 
the OLE DB Provider for SSIS consume output of an SSIS package as a tabular result set. You can create a 
linked server that uses the OLE DB Provider for SSIS and then run a SQL query on the linked server to display 
data returned by the SSIS package. 


In the following example example, the following query returns output from the Package.dtsx package in the 
SSISPackagePublishing project in the Power BI folder of the SSIS Catalog. This query uses the linked server 
named [Default Linked Server for Integration Services] that in turn uses the new OLE DB Provider for SSIS. The 
query includes folder name, project name, and package name in the SSIS catalog. The OLE DB Provider for SSIS 
runs the package you specified in the query and returns the tabular result set. 


SELECT * FROM OPENQUERY([Default Linked Server for Integration Services], N'Folder=Power 
BI; Project=SSISPackagePublishing; Package=Package.dtsx') 


Data Feed Publishing Components 


The Data Feed Publishing Components include the following components: OLE DB Provider for SSIS, Data 
Streaming Destination, and SSIS Package Publish Wizard. The wizard lets you publish an SSIS package as a SQL 
view in a SQL Server database instance. The wizard helps you with creating a linked server that uses the OLE DB 
Provider for SSIS and a SQL view that represents a query on the linked server. You run the view to query results 
from the SSIS package as a tabular data set. 


To confirm that the SSISOLEDB provider is installed, in SQL Server Management Studio, expand Server 
Objects, Linked Servers, Providers, and confirm that you see the SSISOLEDB provider. Double-click 
SSISOLEDB, enable Allow Inprocess if it is not enabled, and click OK. 


Publish an SSIS package as a SQL view 
The following procedure describes the steps to publish an SSIS package as a SQL view. 


1. Create an SSIS package with a Data Streaming Destination component and deploy the package to the 
SSIS Catalog. 


2. Run the SSIS Package Publish Wizard by running ISDataFeedPublishingWizard.exe from C:\Program 
Files\Microsoft SQL Server\130\DTS\Binn or by running the Data Feed Publishing Wizard from the Start 
menu. 


The wizard creates a linked server using the OLE DB Provider for SSIS (SSISOLEDB) and then creates a 
SQL view that consists of a query on the linked server. This query includes folder name, project name, 
and package name in the SSIS catalog. 


3. Execute the SQL view in SQL Server Management Studio and review the results from the SSIS package. 
The view sends a query to the OLE DB Provider for SSIS via the linked server you created. The OLE DB 
Provider for SSIS executes the package you specified in the query and returns the tabular result set. 





IMPORTANT 
For detailed steps, see Walkthrough: Publish an SSIS Package as a SQL View. 





Configure Data Streaming Destination 


Configure the Data Streaming Destination by using the Advanced Editor for Data Streaming Destination 
dialog box. Open this dialog box by double clicking the component or by right-clicking the component in the 
data flow designer and then clicking Edit. 


This dialog box has three tabs: Component Properties, Input Columns, and Input and Output Properties. 


Component Properties tab 


This tab has the following editable fields: 


FIELD DESCRIPTION 

Name Name of the data streaming destination component in the 
package. 

ValidateExternalMetadata Indicates whether the component is validated using external 


data sources at design time. If set to false, validation against 
external data sources is delayed until runtime. 


IDColumnName The view generated by the Data Feed Publish Wizard has 
this additional ID column. The ID column serves as the 
EntityKey for the output data from the data flow when the 
data is consumed as an OData feed by other applications. 


The default name for this column is _ID. You can specify a 
different name for the ID column. 


Input Columns tab 


In the top pane of this tab, you see all the available input columns. Select the columns that you want to include 
in the output of this component. The selected columns are displayed in a list in the bottom pane. You can change 
the name of the output column by entering the new name for the Output Alias field in the list. 


Input Output Properties tab 


Similar to the Input Columns tab, you can change names of output columns in this tab. In the tree view to the 
left, expand Data Streaming Destination Input and then expand Input Columns. Click the input column 
name and change the name of the output column name in the right pane. 


Walkthrough: Publish an SSIS Package as a SQL 


WATS 
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This walkthrough provides detailed steps to publish an SSIS package as a SQL view in a SQL Server database. 


Prerequisites 
You must have the following software installed on your computer to perform this walkthrough. 
1. SQL Server with SQL Server Integration Services. 


2. SQL Server Data Tools. 


Step 1: Build and Deploy SSIS Project to the SSIS Catalog 


In this step, you create an SSIS package that extracts data from an SSIS supported data source - in this example, 
we use a SQL Server database - and outputs the data using a Data Streaming Destination component. Then you 
build and deploy the SSIS project to the SSIS catalog. 


1. Launch SQL Server Data Tools. On the Start menu, point to All Programs, point to Microsoft SQL 
Server, and click SQL Server Data Tools. 


2. Create a new Integration Services project. 
a. Click File on the menu bar, point to New, and click Project. 
b. Expand Business Intelligence in the left pane and click Integration Services in the tree view. 
c. Select Integration Services Project if it is not already selected. 
d. Specify SSISPackagePublishing for the project name. 
e. Specify a location for the project. 
f. Click OK to close the New Project dialog box. 
3. Drag the Data Flow component from SSIS Toolbox to the design surface of the Control Flow tab. 
4. Double-click Data Flow component in the Control Flow to open Data Flow Designer. 


5. Drag asource component from the toolbox to the Data Flow Designer and configure it to extract 
data from a data source. 


a. For the purpose of the walkthrough, create a test database: TestDB with a table: Employee. Create 
the table with three columns, ID, FirstName and LastName. 


b. Set ID as a primary key. 


c. Insert two records with the following data. 


ID FIRSTNAME LASTNAME 


1 John Doe 
2 Jane Doe 


d. Drag the OLE DB Source component from the SSIS Toolbox on to the Data Flow Designer. 


e. Configure the component to extract data from the Employee table in the TestDB database. Select 
(local).TestDB for OLE DB connection manager, Table or view for Data access mode, and 
[dbo].[Employee] for Name of the table or the view. 


OLE DB connection manager: 


(local).TestDB v 


Data access mode: 


Table or view v 


Name of the table or the view: 


FB [dbo].[Employee] v 


6. Now, drag the Data Streaming Destination from the toolbox to the data flow. You should find this 
component in the Common section of the toolbox. 


7. Connect the OLE DB Source component in the data flow to the Data Streaming Destination 
component. 


8. Build and deploy the SSIS project to SSIS Catalog. 
a. Click Project on the menu bar and click Deploy. 


b. Follow the instructions on the wizard to deploy the project to the SSIS Catalog in the local 
database server. The following example uses Power BI as the folder name and 


SSISPackagePublishing as the project name in the SSIS catalog. 


Step 2: Use the SSIS Data Feed Publishing Wizard to Publish SSIS 
Package as a SQL View 


In this step, you will use the SQL Server Integration Services (SSIS) Data Feed Publishing Wizard to publish the 
SSIS package as a view in a SQL Server database. The output data of the package can be consumed by querying 


this view. 


The SSIS Data Feed Publishing Wizard creates a linked server using the OLE DB Provider for SSIS (SSISOLEDB) 
and then creates a SQL view that consists of a query on the linked server. This query includes folder name, 
project name, and package name in the SSIS catalog. 


At runtime, the view sends the query to the OLE DB Provider for SSIS via the linked server you created. The OLE 
DB Provider for SSIS executes the package you specified in the query and returns the tabular result set to the 


query. 


1. Launch SSIS Data Feed Publishing Wizard by running ISDataFeedPublishingWizard.exe from 
C:\Program Files\Microsoft SQL Server\130\DTS\Binn or by clicking Microsoft SQL Server 2016\SQL 
Server 2016 Data Feed Publishing Wizard under Start\All Programs. 


2. Click Next on the Introduction page. 


8 o Introduction 


Package Settings 
Publish Settings 
Validation 
Summary 


Finish 


@ Help 
Welcome to SQL Server Integration Services Data Feed Publishing Wizard 


SQL Server Integration Services (SSIS) Data Feed Publishing Wizard publishes the output of an SSIS 
package as a view in a SQL Server database. The output data of the package can be consumed by 
There are five steps to complete this wizard: 

1. Select the SSIS Package that you want to publish as a view in a SQL Server database. 

2. Specify the view to which the SSIS Package will be published. 

3. Validate the settings. 

4. Review the settings. 

5. Publish the package. 


Click Next to continue. 


[_] Do not show this page again 


< Previous Publish 








3. On the Package Settings page, perform the following tasks: 


a. Type the name of the SQL Server instance that contains the SSIS catalog or click Browse to select 


the server. 


~ 
Au Package Settings 


Introduction @ Help 
Select Package 
Publish Settings 


Validation Specify the SSIS package that you want to publish as a view in a SQL Server database. Windows 
authentication is used to connect to the SQL Server. 


Summary 

Finish Server: 
rteneaee 

Path: 

/SSISDB/Power BI/SS|SPackagePublishing/Package.dtsx 
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b. Click Browse next to Path field, browse the SSIS catalog, select the SSIS package you want to 
publish (for example: SSISDB->SSISPackagePublishing->Package.dtsx), and click OK. 


Select the SSIS package that you want to publish as a view: 


Gy SSISDB 
aay Power Bl 
)-.j8, SSISPackagePublishing 























c. Using the Package Parameters, Project Parameters, and Connection Managers tabs at the bottom 
of the page, enter values for any package parameters, project parameters, or connection manager 
settings for the package. You can also indicate an environment reference to be used for the 
package execution and bind project/package parameters to environment variables. 


We recommend that you bind sensitive parameters to environment variables. This is to ensure that 


the value of a sensitive parameter is not stored in the plain text format in the SQL view created by 
the wizard. 


d. Click Next to switch the Publish Settings page. 
4. On the Publish Settings page, perform the following tasks: 


a. Select the database for the view to be created. 


Publish Settings 
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rans Specify the view to which the SSIS package will be published and configure the settings for the 
Validation iii. 


Summary 
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SS|SPackageView 








LinkedServer 
Use32BitRuntime 
Timeout 











The linked server that the view uses to query the SSIS package. 





b. Type aname for the view. You can also select an existing view from the drop-down list. 


c. In the Settings list, specify aname of the linked server to be associated with the view. If linked 
server does not already exist, the wizard will create the linked server before creating the view. You 
can also set values for User32BitRuntime and Timeout values here. 


d. Click the Advanced button. You should see the Advanced Settings dialog box. 
e. On the Advanced Settings dialog box, do the following: 
a. Specify the database schema in which you want the view to be created (Schema field). 


b. Specify whether data should be encrypted before sending it over the network (Encrypt 
field). See Using Encryption Without Validation topic for more details about this setting and 
the TrustServerCertificate setting. 


c. Specify whether a self-signed server certificate can be used when the encryption setting is 
enabled (TrustServerCertificate field). 


d. Click OK to close the Advanced Settings dialog box. 
f. Click Next to switch to the Validation page. 


5. On the Validation page, review the results from the validating the values for all the settings. In the 
following example, you see a warning on the existence of linked server because the linked server does 


not exist on the selected SQL Server instance. If you see Error for Result, hover the mouse over Error 
and you will see the details about the error. For example, if you had not enabled the Allow inprocess 
option for the SSISOLEDB provider, you will get an error on the Configuration of Linked Server action. 


Validation 
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Summary 

Finish Connecting to SGL Server. 

Installation of the OLE DB Provider for SQL Server Integration Services. 
Existence of the linked server. 

Configuration of the linked server. 

Validating package. 

Existence of the view. 










































































. To save this report as an XML file, click Save Report. 
. Click Next on the Validation page to switch to the Summary page. 


. Review your selection in the Summary page and click Publish to start the publishing process, which will 
create the linked server if it does not exist already on the server and then create the view using the linked 
server. 
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The output data of the package can now be queried by executing the following SQL statement against the 
TestDB database: SELECT * FROM [SSISPackageView]. 


9. To save this report as an XML file, click Save Report. 


10. Review the results from the publishing process and click Finish to close the wizard. 





NOTE 


The following data types are not supported : text, ntext, image, nvarchar(max), varchar(max), and varbinary(max). 





Step 3: Test the SQL view 

In this, you will run the SQL view created by the SSIS Data Feed Publishing Wizard. 

1. Launch SQL Server Management Studio. 

2. Expand <machine name>, Databases, <database you selected in the wizard>, and Views. 

3. Right-click the <view created by the wizard> created by the wizard and click Select top 1000 rows. 


4. Confirm that you see results from the SSIS package. 


Step 4: Verify the SSIS Package Execution 


In this step, you will verify that the SSIS package was executed. 


1. In SQL Server Management Studio, expand Integration Services Catalogs, expand SSISDB, expand 
folder in which your SSIS project exists, expand Projects, expand your project node, and expand 
Packages. 


2. Right-click on the SSIS package, and click point to Reports, point to Standard Reports, and click All 
Executions. 


3. You should see the SSIS package execution in the report. 





NOTE 


On a Windows Vista Service Pack 2 computer, you may see two SSIS package executions in the report, a successful 


one and a failed one. Ignore the failed one as it is caused by a known issue in this release. 








More info 


The Data Feed Publish Wizard performs the following important steps: 
1. Creates a linked server and configures it to use the OLE DB Provider for SSIS. 


2. Creates a SQL view in the specified database, which queries the linked server with catalog information for 
the selected package. 


This section has procedures for creating a linked server and a SQL view without using the Data Feed Publish 
Wizard. It also has additional information about using the OPENQUERY function with the OLE DB Provider for 
SSIS. 


Create a Linked Server using the OLE DB Provider for SSIS 


Create a linked server using the OLE DB Provider for SSIS (SSISOLEDB) by running the following query in SQL 
Server Management Studio. 


USE [master] 
GO 


EXEC sp_addlinkedserver 
@server = N'SSISFeedServer', 
@srvproduct = N'Microsoft', 
@provider = N'SSISOLEDB', 
@datasrc = N'.' 

GO 


Create a View using Linked Server and SSIS Catalog Information 


In this step, you will create a SQL view that runs a query on the linked server you created in the previous 
section. The query will include folder name, project name, and package name in the SSIS Catalog. 


At runtime, when the view is executed, the linked server query that is defined in the view starts the SSIS package 
specified in the query and receives the package output as a tabular result set. 


1. Before creating the view, type and run the following query in the new query window. OPENQUERY is a 
rowset function supported by SQL Server. It executes the specified pass-through query on the specified 
linked server using the OLE DB Provider associated with the linked server. OPENQUERY can be 
referenced in the FROM clause of a query as if it were a table name. See OPENQUERY documentation on 
MSDN Library for more information. 


SELECT * FROM 


OPENQUERY (SSISFeedServer,N'Folder=Eldorado;Project=SSISPackagePublishing; Package=Package.dtsx' ) 
GO 





IMPORTANT 


Update folder name, project name, and package name if needed. If the OPENQUERY function fails, in the SQL 
Server Management Studio, expand Server Objects, expand Linked Servers, expand Providers, and 
double click SSISOLEDB provider, and ensure that the Allow inprocess option is enabled. 








2. Create a view in the database TestDB for the purpose of this walkthrough) by running the following 
query. 


USE [TestDB] 
GO 


CREATE VIEW SSISPackageView AS 
SELECT * FROM OPENQUERY(SSISFeedServer, 


"Folder=Eldorado;Project=SSISPackagePublishing; Package=Package.dtsx' ) 
GO 


3. Test the view by running the following query. 


SELECT * FROM SSISPackageView 


OPENQUERY Function 
The syntax for OPENQUERY function is: 


SELECT * FROM OPENQUERY(<LinkedServer Name>, N'Folder=<Folder Name from SSIS Catalog>; Project=<SSIS Project 
Name>; Package=<SSIS Package Name>; Use32BitRuntime=[True | False];Parameters="<parameter_name_1>=<value1>; 
parameter_name_2=<value2>";Timeout=<Number of Seconds>;') 


Folder, Project, and Package parameters are mandatory. Use32BitRuntime, Timeout and Parameters are optional. 


The value of Use32BitRuntime can be 0, 1, true, or false. It indicates whether the package should run with 32-bit 
runtime (1 or true) when the platform of SQL Server is 64-bit. 


Timeout indicates the number of seconds that the OLE DB provider for SSIS can wait before new data arrives 
from the SSIS package. By default, the timeout is 60 seconds. You can specify an integer value for the timeout 
between 20 and 32000. 


Parameters contain the value of both package parameters and project parameters. The rules for parameters are 
same as parameters in DITExec. 


The following list specifies the special characters allowed in the query clause: 


e Single Quote (') - This is supported by the standard OPENQUERY. If you want to use the single quote in 
the query clause, use two single quotes ('’). 


e Double-Quote (") - The parameters part of the query is enclosed in double-quotes. If a parameter value 
itself contains a double-quote, use the escape character. For example: ". 


e Left and right square brackets ([ and ]) - These characters are used to indicate leading/rear spaces. For 


example, "[ some spaces ]" represents the string " some spaces " with one leading space and one trailing 
space. If these characters themselves are used in the query clause, they must be escaped. For example: \[ 
and \]. 


e Forward Slash (\) - Every \ used in the query clause must use escape character. For example, \\ is 


evaluated as \ in the query clause. 


See Also 


Data Streaming Destination 
Configure Data Streaming Destination 
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The DataReader destination exposes the data in a data flow by using the ADO.NET DataReader interface. The 
data can then be consumed by other applications. For example, you can configure the data source of a Reporting 
Services report to use the result of running a Microsoft SQL Server Integration Services package. To do this, you 
create a data flow that implements the DataReader destination. 


For information about accessing and reading values in the DataReader destination programmatically, see 
Loading the Output of a Local Package. 


Configuration of the DataReader Destination 


You can specify a time-out value for the DataReader destination and indicate whether the destination should fail 
if a time-out occurs. A time-out occurs if the application does not ask for data within the specified time. 


The DataReader destination has one input. It does not support an error output. 
You can set properties through SSIS Designer or programmatically. 


For more information about the properties that you can set in the Advanced Editor dialog box or 
programmatically, click one of the following topics: 


e Common Properties 


e DataReader Destination Custom Properties 


For more information about how to set properties, see Set the Properties of a Data Flow Component. 


DataReader Destination Custom Properties 
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The DataReader destination has both custom properties and the properties common to all data flow 
components. 


The following table describes the custom properties of the DataReader destination. All properties except for 
DataReader are read/write. 


PROPERTY NAME DATA TYPE DESCRIPTION 

DataReader String The class name of the DataReader 
destination. 

FailOnTimeout Boolean Indicates whether to fail when a 


ReadTimeout occurs. The default 
value of this property is False. 


ReadTimeout Integer The number of milliseconds before a 
time-out occurs. The default value of 
this property is 30000 (30 seconds). 


The input and the input columns of the DataReader destination have no custom properties. 


For more information, see DataReader Destination. 


See Also 


Common Properties 
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The Dimension Processing destination loads and processes an SQL Server Analysis Services dimension. For 
more information about dimensions, see Dimensions (Analysis Services - Multidimensional Data). 


The Dimension Processing destination includes the following features: 
@ Options to perform incremental, full, or update processing. 


e Error configuration, to specify whether dimension processing ignores errors or stops after a specified 
number of errors. 


e Mapping of input columns to columns in dimension tables. 


For more information about processing Analysis Services objects, see Processing Options and Settings (Analysis 
Services). 


Configuration of the Dimension Processing Destination 


The Dimension Processing destination uses an Analysis Services connection manager to connect to the Analysis 
Services project or the instance of Analysis Services that contains the dimensions the destination processes. For 
more information, see Analysis Services Connection Manager. 


This destination has one input. It does not support an error output. 
You can set properties through SSIS Designer or programmatically. 


The Advanced Editor dialog box reflects the properties that can be set programmatically. For more 
information about the properties that you can set in the Advanced Editor dialog box or programmatically, click 
one of the following topic: 


e Common Properties 


For more information about how to set the properties, see Set the Properties of a Data Flow Component. 


Dimension Processing Destination Editor (Connection Manager Page) 


Use the Connection Manager page of the Dimension Processing Destination Editor dialog box to specify 
a connection to a SQL Server Analysis Services project or to an instance of Analysis Services. 

Options 

Connection manager 


Select an existing connection manager from the list, or click New to create a new connection manager. 


New 
Create a new connection by using the Add Analysis Services Connection Manager dialog box. 


List of available dimensions 
Select the dimension to process. 


Processing method 
Select the processing method to apply to the dimension selected in the list. The default value of this option is 


Full. 


VALUE DESCRIPTION 

Add (incremental) Perform an incremental processing of the dimension. 
Full Perform full processing of the dimension. 

Update Perform an update processing of the dimension. 


Dimension Processing Destination Editor (Mappings Page) 


Use the Mappings page of the Dimension Processing Destination Editor dialog box to map input columns 


to dimension columns. 


Options 
Available Input Columns 
View the list of available input columns. Use a drag-and-drop operation to map available input columns in the 


table to destination columns. 


Available Destination Columns 
View the list of available destination columns. Use a drag-and-drop operation to map available destination 


columns in the table to input columns. 


Input Column 
View input columns selected from the table above. You can change the mappings by using the list of Available 
Input Columns. 


Destination Column 
View each available destination column, and whether it is mapped or not. 


Dimension Processing Destination Editor (Advanced Page) 


Use the Advanced page of the Dimension Processing Destination Editor dialog box to configure error 
handling. 


Options 
Use default error configuration. 
Specify whether to use the default Analysis Services error handling. By default, this value is True. 


Key error action 
Specify how to handle records that have unacceptable key values. 


VALUE DESCRIPTION 


ConvertToUnknown Convert the unacceptable key value to the 
UnknownMember value. 


DiscardRecord Discard the record. 


Ignore errors 
Specify that errors should be ignored. 


Stop on error 
Specify that processing should stop when an error occurs. 


Number of errors 
Specify the error threshold at which processing should stop, if you have selected Stop on errors. 


On error action 


Specify the action to take when the error threshold is reached, if you have selected Stop on errors. 


VALUE DESCRIPTION 
StopProcessing Stop processing. 
StopLogging Stop logging errors. 


Key not found 
Specify the action to take for a key not found error. By default, this value is ReportAndContinue. 


VALUE DESCRIPTION 

IgnoreError Ignore the error and continue processing. 
ReportAndContinue Report the error and continue processing. 
ReportAndStop Report the error and stop processing. 


Duplicate key 
Specify the action to take for a duplicate key error. By default, this value is IgnoreError. 


VALUE DESCRIPTION 

IgnoreError Ignore the error and continue processing. 
ReportAndContinue Report the error and continue processing. 
ReportAndStop Report the error and stop processing. 


Null key converted to unknown 
Specify the action to take when a null key has been converted to the UnknownMember value. By default, this 
value is IgnoreError. 


VALUE DESCRIPTION 

IgnoreError Ignore the error and continue processing. 
ReportAndContinue Report the error and continue processing. 
ReportAndStop Report the error and stop processing. 


Null key not allowed 
Specify the action to take when null keys are not allowed and a null key is encountered. By default, this value is 
ReportAndContinue. 


VALUE DESCRIPTION 


IgnoreError Ignore the error and continue processing. 


VALUE DESCRIPTION 
ReportAndContinue Report the error and continue processing. 
ReportAndStop Report the error and stop processing. 


Error log path 
Type the path of the error log, or click the browse(...) button to select a destination. 


Browse (...) 
Select a path for the error log. 


See Also 


Data Flow 


Integration Services Transformations 


Dimension Processing Destination Custom Properies 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


The Dimension Processing destination has both custom properties and the properties common to all data flow 


components. 


The following table describes the custom properties of the Dimension Processing destination. All properties are 


read/write. 


PROPERTY 


ASConnectionString 


KeyDuplicate 


KeyErrorAction 


KeyErrorLimit 


KeyErrorLimitAction 


KeyErrorLogFile 


DATA TYPE 


String 


Integer (enumeration) 


Integer (enumeration) 


Integer 


Integer (enumeration) 


String 


DESCRIPTION 


The connection string to an instance of 
Analysis Services or to an Analysis 
Services project. 


When UseDefaultConfiguration is 
False, a value that indicates how to 
handle duplicate key errors. The 
possible values are |gnoreError (0), 
ReportAndContinue (1), and 
ReportAndStop (2). The default value 
of this property is IgnoreError (0). 


When UseDefaultConfiguration is 
False, a value that indicates how to 
handle key error. The possible values 
are ConvertToUnknown (0) and 
DiscardRecord (1). The default value 
of this property is 
ConvertToUnknown (0). 


When UseDefaultConfiguration is 
False, the upper limit of key errors 
that are enabled. 


When UseDefaultConfiguration is 
False, a value that indicates the action 
to take when KeyErrorLimit is 
reached. The possible values are 
StopLogging (1) and 
StopProcessing (0). The default value 
of this property is StopProcessing 
(0). 


When UseDefaultConfiguration is 
False, the path and file name of the 
error log file. 


PROPERTY 


KeyNotFound 


NullkeyConvertedToUnknown 


NullkeyNotAllowed 


ProcessType 


UseDefaultConfiguration 


DATA TYPE 


Integer (enumeration) 


Integer (enumeration) 


Integer (enumeration) 


Integer (enumeration) 


Boolean 


DESCRIPTION 


When UseDefaultConfiguration is 
False, a value that indicates how to 
handle missing key errors. The possible 
values are IgnoreError (0), 
ReportAndContinue (1), and 
ReportAndStop (2). The default value 
of this property is IgnoreError (0). 


When UseDefaultConfiguration is 
False, a value that indicates how to 
handle null keys converted to the 
unknown value. The possible values 
are IgnoreError (0), 
ReportAndContinue (1), and 
ReportAndStop (2). The default value 
of this property is IgnoreError (0). 


When UseDefaultConfiguration is 
False, a value that indicates how to 
handle disallowed nulls. The possible 
values are IgnoreError (0), 
ReportAndContinue (1), and 
ReportAndStop (2). The default value 
of this property is IgnoreError (0). 


The type of dimension processing the 
transformation uses. The values are 
ProcessAdd (1) (incremental), 
ProcessFull (0), and ProcessUpdate 
(2). 


A value that specifies whether the 
transformation uses the default error 
configuration. If this property is False, 
the transformation includes 
information about error processing. 


The input and the input columns of the Dimension Processing destination have no custom properties. 


For more information, see Dimension Processing Destination. 


See Also 


Common Properties 


Excel Source 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


The Excel source extracts data from worksheets or ranges in Microsoft Excel workbooks. 


IMPORTANT 


For detailed info about connecting to Excel files, and about limitations and known issues for loading data from or to Excel 


files, see Load data from or to Excel with SQL Server Integration Services (SSIS). 











Access Modes 

The Excel source provides four different data access modes for extracting data: 
e A table or view. 

e A table or view specified in a variable. 

e@ The results of an SQL statement. The query can be a parameterized query. 


e The results of an SQL statement stored in a variable. 


The Excel source uses an Excel connection manager to connect to a data source, and the connection manager 
specifies the workbook file to use. For more information, see Excel Connection Manager. 


The Excel source has one regular output and one error output. 


Excel Source Configuration 
You can set properties through SSIS Designer or programmatically. 


The Advanced Editor dialog box reflects all the properties that can be set programmatically. For more 
information about the properties that you can set in the Advanced Editor dialog box or programmatically, click 
one of the following topics: 


e Common Properties 
e Excel Custom Properties 


For information about looping through a group of Excel files, see Loop through Excel Files and Tables by Using a 
Foreach Loop Container. 


Excel Source Editor (Connection Manager Page) 


Use the Connection Manager node of the Excel Source Editor dialog box to select the Microsoft Excel 
workbook for the source to use. The Excel source reads data from a worksheet or named range in an existing 
workbook. 





NOTE 
The CommandTimeout property of the Excel source is not available in the Excel Source Editor, but can be set by 
using the Advanced Editor. For more information on this property, see the Excel Source section of Excel Custom 


Properties. 





Static Options 


OLE DB connection manager 


Select an existing Excel connection manager from the list, or create a new connection by clicking New. 


New 
Create a new connection manager by using the Excel Connection Manager dialog box. 


Data access mode 
Specify the method for selecting data from the source. 


VALUE DESCRIPTION 

Table or view Retrieve data from a worksheet or named range in the Excel 
file. 

Table name or view name variable Specify the worksheet or range name in a variable. 


Related information: Use Variables in Packages 


SQL command Retrieve data from the Excel file by using a SQL query. 
SQL command from variable Specify the SQL query text in a variable. 
Preview 


Preview results by using the Data View dialog box. Preview can display up to 200 rows. 


Data Access Mode Dynamic Options 

Data access mode = Table or view 

Name of the Excel sheet 

Select the name of the worksheet or named range from a list of those available in the Excel workbook. 


Data access mode = Table name or view name variable 
Variable name 
Select the variable that contains the name of the worksheet or named range. 


Data access mode = SQL command 

SQL command text 

Enter the text of a SQL query, build the query by clicking Build Query, or browse to the file that contains the 
query text by clicking Browse. 


Parameters 
If you have entered a parameterized query by using ? as a parameter placeholder in the query text, use the Set 
Query Parameters dialog box to map query input parameters to package variables. 


Build query 
Use the Query Builder dialog box to construct the SQL query visually. 


Browse 


Use the Open dialog box to locate the file that contains the text of the SQL query. 





Parse query 
Verify the syntax of the query text. 


Data access mode = SQL command from variable 


Variable name 
Select the variable that contains the text of the SQL query. 


Excel Source Editor (Columns Page) 


Use the Columns page of the Excel Source Editor dialog box to map an output column to each external 


(source) column. 


Options 
Available External Columns 
View the list of available external columns in the data source. You cannot use this table to add or delete columns. 


External Column 

View external (source) columns in the order in which the task will read them. You can change this order by first 
clearing the selected columns in the table discussed above, and then selecting external columns from the list in a 
different order. 


Output Column 

Provide a unique name for each output column. The default is the name of the selected external (source) 
column; however, you can choose any unique, descriptive name. The name provided will be displayed within 
SSIS Designer. 


Excel Source Editor (Error Output Page) 


Use the Error Output page of the Excel Source Editor dialog box to select error handling options and to set 


properties on error output columns. 


Options 
Input or Output 
View the name of the data source. 


Column 
View the external (source) columns that you selected on the Connection Manager page of the Excel Source 
Editordialog box. 


Error 
Specify what should happen when an error occurs: ignore the failure, redirect the row, or fail the component. 


Related Topics: Error Handling in Data 


Truncation 
Specify what should happen when a truncation occurs: ignore the failure, redirect the row, or fail the component. 


Description 
View the description of the error. 


Set this value to selected cells 
Specify what should happen to all the selected cells when an error or truncation occurs: ignore the failure, 
redirect the row, or fail the component. 


Apply 
Apply the error handling option to the selected cells. 


Related Content 


Load data from or to Excel with SQL Server Integration Services (SSIS) 
Excel Destination 
Excel Connection Manager 


Excel Destination 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


The Excel destination loads data into worksheets or ranges in Microsoft Excel workbooks. 


IMPORTANT 


For detailed info about connecting to Excel files, and about limitations and known issues for loading data from or to Excel 


files, see Load data from or to Excel with SQL Server Integration Services (SSIS). 











Access Modes 

The Excel destination provides three different data access modes for loading data: 
e A table or view. 

e A table or view specified in a variable. 


e@ The results of an SQL statement. The query can be a parameterized query. 


Configure the Excel Destination 


The Excel destination uses an Excel connection manager to connect to a data source, and the connection 
manager specifies the workbook file to use. For more information, see Excel Connection Manager. 


The Excel destination has one regular input and one error output. 
You can set properties through SSIS Designer or programmatically. 


The Advanced Editor dialog box reflects all the properties that can be set programmatically. For more 
information about the properties that you can set in the Advanced Editor dialog box or programmatically, click 
one of the following topics: 


e Common Properties 
e Excel Custom Properties 


For more information about how to set properties, see Set the Properties of a Data Flow Component. 


Excel Destination Editor (Connection Manager Page) 


Use the Connection Manager page of the Excel Destination Editor dialog box to specify data source 
information, and to preview the results. The Excel destination loads data into a worksheet or anamed range ina 
Microsoft Excel workbook. 


NOTE 
The CommandTimeout property of the Excel destination is not available in the Excel Destination Editor, but can be 
set by using the Advanced Editor. In addition, certain Fast Load options are available only in the Advanced Editor. For 


more information on these properties, see the Excel Destination section of Excel Custom Properties. 











Static Options 


Excel connection manager 


Select an existing Excel connection manager from the list, or create a new connection by clicking New. 


New 


Create a new connection manager by using the Excel Connection Manager dialog box. 


Data access mode 
Specify the method for selecting data from the source. 


OPTION DESCRIPTION 


Table or view Loads data into a worksheet or named range in the Excel 


data source. 


Table name or view name variable Specify the worksheet or range name in a variable. 


Related information: Use Variables in Packages 


SQL command Load data into the Excel destination by using an SQL query. 


Name of the Excel sheet 
Select the excel destination from the drop-down list. If the list is empty, click New. 


New 


Click New to launch the Create Table dialog box. When you click OK, the dialog box creates the excel file that 


the Excel Connection Manager points to. 


View Existing Data 
Preview results by using the Preview Query Results dialog box. Preview can display up to 200 rows. 


Data Access Mode Dynamic Options 
Data access mode = Table or view 
Name of the Excel sheet 


Select the name of the worksheet or named range from a list of those available in the data source. 


Data access mode = Table name or view name variable 
Variable name 
Select the variable that contains the name of the worksheet or named range. 


Data access mode = SQL command 

SQL command text 

Enter the text of an SQL query, build the query by clicking Build Query, or locate the file that contains the 
query text by clicking Browse. 


Build Query 
Use the Query Builder dialog box to construct the SQL query visually. 


Browse 


Use the Open dialog box to locate the file that contains the text of the SQL query. 


Parse Query 
Verify the syntax of the query text. 


Excel Destination Editor (Mappings Page) 


Use the Mappings page of the Excel Destination Editor dialog box to map input columns to destination 


columns. 


Options 

Available Input Columns 

View the list of available input columns. Use a drag-and-drop operation to map available input columns in the 
table to destination columns. 


Available Destination Columns 
View the list of available destination columns. Use a drag-and-drop operation to map available destination 


columns in the table to input columns. 


Input Column 
View input columns selected from the table above. You can change the mappings by using the list of Available 
Input Columns. 


Destination Column 
View each available destination column, whether it is mapped or not. 


Excel Destination Editor (Error Output Page) 


Use the Advanced page of the Excel Destination Editor dialog box to specify options for error handling. 


Options 


Input or Output 
View the name of the data source. 


Column 
View the external (source) columns that you selected in the Connection Manager node of the Excel Source 
Editordialog box. 


Error 


Specify what should happen when an error occurs: ignore the failure, redirect the row, or fail the component. 
Related Topics: Error Handling in Data 


Truncation 
Specify what should happen when a truncation occurs: ignore the failure, redirect the row, or fail the component. 


Description 
View the description of the error. 


Set this value to selected cells 
Specify what should happen to all the selected cells when an error or truncation occurs: ignore the failure, 
redirect the row, or fail the component. 


Apply 
Apply the error handling option to the selected cells. 


See Also 


Load data from or to Excel with SQL Server Integration Services (SSIS) 
Excel Source 
Excel Connection Manager 


Excel Custom Properties 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 
Source Custom Properties 
The Excel source has both custom properties and the properties common to all data flow components. 


The following table describes the custom properties of the Excel source. All properties are read/write. 


PROPERTY NAME DATA TYPE DESCRIPTION 


AccessMode Integer The mode used to access the database. 
The possible values are Open Rowset, 
Open Rowset from Variable, SQL 
Command, and SQL Command 
from Variable. The default value is 
Open Rowset. 


CommandTimeout Integer The number of seconds before a 
command times out. A value of 0 
indicates an infinite time-out. 

Note This property is not available in 


the Excel Source Editor, but can be 
set by using the Advanced Editor. 


OpenRowset String The name of the database object that 
is used to open a rowset. 


OpenRowsetVariable String The variable that contains the name of 
the database object that is used to 
open a rowset. 


ParameterMapping String The mapping from parameters in the 
SQL command to variables. 


SqlCommand String The SQL command to be executed. 


SqlCommandVariable String The variable that contains the SQL 
command to be executed. 


The output and the output columns of the Excel source have no custom properties. 

For more information, see Excel Source. 

Destination Custom Properties 

The Excel destination has both custom properties and the properties common to all data flow components. 


The following table describes the custom properties of the Excel destination. All properties are read/write. 


PROPERTY NAME 


AccessMode 


CommandTimeout 


FastLoadKeepldentity 


FastLoadKeepNulls 


FastLoadMaxInsertCommitSize 


DATA TYPE 


Integer (enumeration) 


Integer 


Boolean 


Boolean 


Integer 


DESCRIPTION 


A value that specifies how the 
destination accesses its destination 
database. 


This property can have one of the 
following values: 


OpenRowset (0)-You provide the 
name of a table or view. 


OpenRowset from Variable (1)-You 
provide the name of a variable that 
contains the name of a table or view. 


OpenRowset Using Fastload (3)- 
You provide the name of a table or 
view. 


OpenRowset Using Fastload from 
Variable (4)-You provide the name of 
a variable that contains the name of a 
table or view. 


SQL Command (2)-You provide a 
SQL statement. 


The maximum number of seconds that 
the SQL command can run before 
timing out. A value of 0 indicates an 
infinite time. The default value of this 
property is 0. 


Note: This property is not available in 
the Excel Destination Editor, but 
can be set by using the Advanced 
Editor. 


A value that specifies whether to copy 
identity values when data is loaded. 
This property is available only when 
using one of the fast load options. The 
default value of this property is False. 


A value that specifies whether to copy 
Null values when data is loaded. This 
property is available only with one of 
the fast load options. The default value 
of this property is False. 


A value that specifies the batch size 
that the Excel destination tries to 
commit during fast load operations. 
The default value is 2147483647.A 
value of 0 indicates a single commit 
operation after all rows are processed. 


PROPERTY NAME DATA TYPE DESCRIPTION 


FastLoadOptions String A collection of fast load options. The 
fast load options include the locking of 
tables and the checking of constraints. 
You can specify one, both, or neither. 


Note: Some options for this property 
are not available in the Excel 
Destination Editor, but can be set 
by using the Advanced Editor. 


OpenRowset String When AccessMode is OpenRowset, 
the name of the table or view that the 
Excel destination accesses. 


OpenRowsetVariable String When AccessMode is OpenRowset 
from Variable, the name of the 
variable that contains the name of the 
table or view that the Excel destination 
accesses. 


SqlCommand String When AccessMode is SQL 
Command, the Transact-SQL 
statement that the Excel destination 
uses to specify the destination 
columns for the data. 


The input and the input columns of the Excel destination have no custom properties. 


For more information, see Excel Destination. 


See Also 


Common Properties 


Load data from or to Excel with SQL Server Integration Services (SSIS) 


Flat File Source 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 
The Flat File source reads data from a text file. The text file can be in delimited, fixed width, or mixed format. 
e Delimited format uses column and row delimiters to define columns and rows. 


e Fixed width format uses width to define columns and rows. This format also includes a character for 
padding fields to their maximum width. 


e Ragged right format uses width to define all columns, except for the last column, which is delimited by 
the row delimiter. 


You can configure the Flat File source in the following ways: 


e Adda column to the transformation output that contains the name of the text file from which the Flat File 
source extracts data. 


e@ Specify whether the Flat File source interprets zero-length strings in columns as null values. 





NOTE 


The Flat File connection manager that the Flat File source uses must be configured to use a delimited format to 
interpret zero-length strings as nulls. If the connection manager uses the fixed width or ragged right formats, data 
that consists of spaces cannot be interpreted as null values. 








The output columns in the output of the Flat File source include the FastParse property. FastParse indicates 
whether the column uses the quicker, but locale-insensitive, fast parsing routines that Integration Services 
provides or the locale-sensitive standard parsing routines. For more information, see Fast Parse and Standard 
Parse. 


Output columns also include the UseBinaryFormat property. You use this property to implement support for 
binary data, such as data with the packed decimal format, in files. By default UseBinaryFormat is set to false. If 
you want to use a binary format, set UseBinaryFormat to true and the data type on the output column to 
DT_BYTES. When you do this, the Flat File source skips the data conversion and passes the data to the output 
column as is. You can then use a transformation such as the Derived Column or Data Conversion to cast the 
DT_BYTES data to a different data type, or you can write custom script in a Script transformation to interpret the 
data. You can also write a custom data flow component to interpret the data. For more information about which 
data types you can cast DT_BYTES to, see Cast (SSIS Expression). 


This source uses a Flat File connection manager to access the text file. By setting properties on the Flat File 
connection manager, you can provide information about the file and each column in it, and specify how the Flat 
File source should handle the data in the text file. For example, you can specify the characters that delimit 
columns and rows in the file, and the data type and the length of each column. For more information, see Flat 
File Connection Manager. 


This source has one output and one error output. 


Configuration of the Flat File Source 


You can set properties through SSIS Designer or programmatically. 


The Advanced Editor dialog box reflects the properties that can be set programmatically. For more 
information about the properties that you can set in the Advanced Editor dialog box or programmatically, click 
one of the following topics: 


@ Common Properties 


e Flat File Custom Properties 


Related Tasks 


For details about how to set properties of a data flow component, see Set the Properties of a Data Flow 
Component. 


Flat File Source Editor (Connection Manager Page) 


Use the Connection Manager page of the Flat File Source Editor dialog box to select the connection 
manager that the Flat File source will use. The Flat File source reads data from a text file, which can be in a 
delimited, fixed width, or mixed format. 


A Flat File source can use one of the following types of connection managers: 


e A Flat File connection manager if the source is a single flat file. For more information, see Flat File 
Connection Manager. 


e A Multiple Flat Files connection manager if the source is multiple flat files and the Data Flow task is inside 
a loop container, such as the For Loop container. On each loop of the container, the Flat File source loads 
data from the next file name that the Multiple Flat Files connection manager provides. For more 
information, see Multiple Flat Files Connection Manager. 


Options 
Flat file connection manager 


Select an existing connection manager from the list, or create a new connection manager by clicking New. 


New 
Create a new connection manager by using the Flat File Connection Manager Editor dialog box. 


Retain null values from the source as null values in the data flow 

Specify whether to keep null values when data is extracted. The default value of this property is false. When this 
value is false, the Flat File source replaces null values from the source data with appropriate default values for 
each column, such as empty strings for string columns and zero for numeric columns. 


Preview 


Preview results by using the Data View dialog box. Preview can display up to 200 rows. 


Flat File Source Editor (Columns Page) 


Use the Columns node of the Flat File Source Editor dialog box to map an output column to each external 
(source) column. 


NOTE 


The FileNameColumnName property of the Flat File source and the FastParse property of its output columns are not 
available in the Flat File Source Editor, but can be set by using the Advanced Editor. For more information on these 
properties, see the Flat File Source section of Flat File Custom Properties. 











Options 


Available External Columns 
View the list of available external columns in the data source. You cannot use this table to add or delete columns. 


External Column 
View external (source) columns in the order in which the task will read them. You can change this order by first 
clearing the selected columns in the table, and then selecting external columns from the list in a different order. 


Output Column 

Provide a unique name for each output column. The default is the name of the selected external (source) 
column; however, you can choose any unique, descriptive name. The name provided will be displayed within 
SSIS Designer. 


Flat File Source Editor (Error Output Page) 


Use the Error Output page of the Flat File Source Editor dialog box to select error-handling options and to 
set properties on error output columns.\ 


Options 
Input/Output 


View the name of the data source. 


Column 
View the external (source) columns that you selected on the Connection Manager page of the Flat File 
Source Editordialog box. 


Error 


Specify what should happen when an error occurs: ignore the failure, redirect the row, or fail the component. 
Related Topics: Error Handling in Data 


Truncation 


Specify what should happen when a truncation occurs: ignore the failure, redirect the row, or fail the component. 


Description 
View the description of the error. 


Set this value to selected cells 
Specify what should happen to all the selected cells when an error or truncation occurs: ignore the failure, 
redirect the row, or fail the component. 


Apply 


Apply the error handling option to the selected cells. 


See Also 


Flat File Destination 
Data Flow 


mela nll (om DYosiularcinlela 


11/23/2021 * 3 minutes to read « Edit Online 





Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


The Flat File destination writes data to a text file. The text file can be in delimited, fixed width, fixed width with 
row delimiter, or ragged right format. 


You can configure the Flat File destination in the following ways: 


e Provide a block of text that is inserted in the file before any data is written. The text can provide 
information such as column headings. 


e@ Specify whether to overwrite a data in a destination file that has the same name. 


This destination uses a Flat File connection manager to access the text file. By setting properties on the Flat File 
connection manager that the Flat File destination uses, you can specify how the Flat File destination formats and 
writes the text file. When you configure the Flat File connection manager, you specify information about the file 
and about each column in the file. For example, you specify the characters that delimit columns and rows in the 
file, and you specify the data type and the length of each column. For more information, see Flat File Connection 
Manager. 


The Flat File destination includes the Header custom property. This property can be updated by a property 
expression when the package is loaded. For more information, see Integration Services (SSIS) Expressions, Use 
Property Expressions in Packages, and Flat File Custom Properties. 


This destination has one output. It does not support an error output. 


Configuration of the Flat File Destination 


You can set properties through SSIS Designer or programmatically. 


The Advanced Editor dialog box reflects the properties that can be set programmatically. For more 
information about the properties that you can set in the Advanced Editor dialog box or programmatically, click 
one of the following topics: 


@ Common Properties 


e Flat File Custom Properties 


Related Tasks 


For information about how to set the properties of a data flow component, see Set the Properties of a Data Flow 
Component. 


Flat File Destination Editor (Connection Manager Page) 


Use the Connection Manager page of the Flat File Destination Editor dialog box to select the flat file 
connection for the destination, and to specify whether to overwrite or append to the existing destination file. The 
flat file destination writes data to a text file. This text file can be in delimited, fixed width, fixed width with row 
delimiter, or ragged right format. 


Options 


Flat File connection manager 


Select an existing connection manager by using the list box, or create a new connection by clicking New. 


New 
Create a new connection by using the Flat File Format and Flat File Connection Manager Editor dialog 
boxes. 


In addition to the standard flat file formats of delimited, fixed width, and ragged right, the Flat File Format 
dialog box has a fourth option, Fixed width with row delimiters. This option represents a special case of the 
ragged-right format in which Integration Services adds a dummy column as the final column of data. This 


dummy column ensures that the final column has a fixed width. 


The Fixed width with row delimiters option is not available in the Flat File Connection Manager Editor. 
If necessary, you can emulate this option in the editor. To emulate this option, on the General page of the Flat 
File Connection Manager Editor, for Format, select Ragged right. Then on the Advanced page of the 


editor, add a new dummy column as the final column of data. 


Overwrite data in the file 
Indicate whether to overwrite an existing file, or to append data to it. 


Header 
Type a block of text to insert into the file before any data is written. Use this option to include additional 


information, such as column headings. 


Preview 


Preview results by using the Data View dialog box. Preview can display up to 200 rows. 


Flat File Destination Editor (Mappings Page) 


Use the Mappings page of the Flat File Destination Editor dialog box to map input columns to destination 


columns. 


Options 
Available Input Columns 


View the list of available input columns. Use a drag-and-drop operation to map available input columns to 
destination columns. 


Available Destination Columns 
View the list of available destination columns. Use a drag-and-drop operation to map available destination 


columns to input columns. 


Input Column 
View input columns selected earlier in this topic. You can change the mappings by using the list of Available 
Input Columns. Select <ignore> to exclude the column from the output. 


Destination Column 
View each available destination column, whether it is mapped or not. 


See Also 


Flat File Source 
Data Flow 


HDFS File Source 
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The HDFS File Source component enables an SSIS package to read data from a HDFS file. The supported file 
formats are Text and Avro. (ORC sources are not supported.) 


To configure the HDFS File Source, drag and drop the HDFS File Source on the data flow designer and double- 
click the component to open the editor. 


a 'HOFS File Source Editor - om 








Configure the properties used to read data from the HDFS file. 


Columns 


Specify a Hadoop connection manager and file path. Click New to create a connection manager. 
Error Output 


Hadoop connection manager: 


[ Hadoop Connection Manager text v New... 


Location 


File Pathe 


Format 
File format: 


Tet ¥ 


Column delimiter character: 


C) Column names in the first data row 





Options 
Configure the following options on the General tab of the Hadoop File Source Editor dialog box. 
FIELD DESCRIPTION 


Hadoop Connection Specify an existing Hadoop Connection Manager or create a 


new one. This connection manager indicates where the HDFS 
files are hosted. 


File Path Specify the name of the HDFS file. 


File format Specify the format for the HDFS file. The available options 
are Text and Avro. (ORC sources are not supported.) 


FIELD DESCRIPTION 


Column delimiter character If you select Text format, specify the column delimiter 
character. 
Column names in the first data row If you select Text format, specify whether the first row in the 


file contains column names. 


After you configure these options, select the Columns tab to map source columns to destination columns in the 
data flow. 


See Also 


Hadoop Connection Manager 
HDFS File Destination 


HDFS File Destination 
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The HDFS File Destination component enables an SSIS package to write data to a HDFS file. The supported file 
formats are Text, Avro, and ORC. 


To configure the HDFS File Destination, drag and drop the HDFS File Source on the data flow designer and 
double-click the component to open the editor. 








a HDFS File Destination Editor - 3 


Configure the properties used to insert data into the HOFS file. if the file exists, its content will be overwritten. 


Mappings Specify a Hadoop connection manager, file path, and upload mode. Click New to create a connection manager. 


Hadoop connection manager: 


Hadoop Connection Manager test wy, New... 


Location 


File Path: 


Format 
File format: 


Text ’ 


Column delimiter character: 


C) Column names in the first data row 





Options 
Configure the following options on the General tab of the Hadoop File Destination Editor dialog box. 


FIELD DESCRIPTION 


Hadoop Connection Specify an existing Hadoop Connection Manager or create a 
new one. This connection manager indicates where the HDFS 
files are hosted. 


File Path Specify the name of the HDFS file. 


File format Specify the format for the HDFS file. The available options 
are Text, Avro, and ORC. 


FIELD DESCRIPTION 


Column delimiter character If you select Text format, specify the column delimiter 
character. 
Column names in the first data row If you select Text format, specify whether the first row in the 


file contains column names. 


After you configure these options, select the Columns tab to map source columns to destination columns in the 
data flow. 


Prerequisite for ORC File Format 


Java is required to use ORC file format. Architecture (32/64-bit) of the Java build should match that of the SSIS 
runtime to use. The following Java builds have been tested. 


e@ Zulu's OpenJDK 8u192 


e Oracle's Java SE Runtime Environment 8u192 


Set Up Zulu's OpenJDK 

1. Download and extract the installation zip package. 
From the Command Prompt, run sysdm.cpl . 

On the Advanced tab, select Environment Variables. 
Under the System variables section, select New. 


Enter JAVA_HoME for the Variable name. 


Ov OT. a. Ue IN) 


Select Browse Directory, navigate to the extracted folder, and select the jre subfolder. Then select OK, and 
the Variable value is populated automatically. 

7. Select OK to close the New System Variable dialog box. 

8. Select OK to close the Environment Variables dialog box. 


9. Select OK to close the System Properties dialog box. 


Set Up Oracle's Java SE Runtime Environment 
1. Download and run the exe installer. 


2. Follow the installer instructions to complete setup. 


See Also 


Hadoop Connection Manager 
HDFS File Source 


Flat File Custom Properties 
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Source Custom Properties 
The Flat File source has both custom properties and the properties common to all data flow components. 


The following table describes the custom properties of the Flat File source. All properties are read/write. 


PROPERTY NAME DATA TYPE DESCRIPTION 


FileNameColumnName String The name of an output column that 
contains the file name. If no name is 
specified, no output column containing 
the file name will be generated. 


Note: This property is not available in 
the Flat File Source Editor, but can 
be set by using the Advanced Editor. 


RetainNulls Boolean A value that specifies whether to retain 
Null values from the source file as Null 
values when the data is processed by 
the Data Transformation Pipeline 
engine. The default value of this 
property is False. 


The output of the Flat File source has no custom properties. 


The following table describes the custom properties of the output columns of the Flat File source. All properties 
are read/write. 


PROPERTY NAME DATA TYPE DESCRIPTION 


FastParse Boolean A value that indicates whether the 
column uses the quicker, but locale- 
insensitive, fast parsing routines that 
DTS provides or the locale-sensitive 
standard parsing routines. For more 
information, see Fast Parse and 
Standard Parse. The default value of 
this property is False. 


Note: This property is not available in 


the Flat File Source Editor, but can 
be set by using the Advanced Editor. 


For more information, see Flat File Source. 
Destination Custom Properties 
The Flat File destination has both custom properties and the properties common to all data flow components. 


The following table describes the custom properties of the Flat File destination. All properties are read/write. 


PROPERTY NAME DATA TYPE DESCRIPTION 


Header String A block of text that is inserted in the 
file before any data is written. 


The value of this property can be 
specified by using a property 
expression. 


Overwrite Boolean A value that specifies whether to 
overwrite or append to an existing 
destination file that has the same 
name. The default value of this 
property is True. 


The input and the input columns of the Flat File destination have no custom properties. 


For more information, see Flat File Destination. 


See Also 


Common Properties 


ODE melulres 
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Use the OData Source component in an SSIS package to consume data from an Open Data Protocol (OData) 
service. 


Supported protocols and data formats 
The component supports the OData v3 and v4 protocols. 
e For OData V3 protocol, the component supports the ATOM and JSON data formats. 


e For OData V4 protocol, the component supports the JSON data format. 


Supported data sources 
The OData source includes support for the following data sources: 


e Microsoft Dynamics AX Online and Microsoft Dynamics CRM Online 


e SharePoint lists. To see all the lists on a SharePoint server, use the following URL: 
https://<server>/_vti_bin/ListData.svc . For more information about SharePoint URL conventions, see 


SharePoint Foundation REST Interface. 


Supported data types 


The OData source supports the following simple data types: int, byte[], bool, byte, DateTime, DateTimeOffset, 
decimal, double, Guid, Int16, Int32, Int64, sbyte, float, string, and TimeSpan. 


To discover the data types of columns in your data source, check the https://<OData feed endpoint>/$metadata 
page. 


For the Decimal data type, the precision and scale are determined by the source metadata. If the source 
metadata does not specify the Precision and Scale properties, the data may be truncated. 





IMPORTANT 


The OData Source component does not support complex types, such as multiple-choice items, in SharePoint lists. 


NOTE 


If the source only allows TLS 1.2 connection, you need to enforce TLS 1.2 on your machine through registry settings. In 
an elevated command prompt run the following commands: 


reg add HKLM\SOFTWARE\Microsoft.NETFramework\v4.0.30319 /v SchUseStrongCrypto /t REG_DWORD /d 1 /reg:64 


reg add HKLM\SOFTWARE\Microsoft.NETFramework\v4.0.30319 /v SchUseStrongCrypto /t REG_DWORD /d 1 /reg:32 











OData Format and Performance 


Most OData services can return results in multiple formats. You can specify the format of the result set by using 


the $format query option. Formats such as JSON and JSON Light are more efficient than ATOM or XML, and 
may give you better performance when transferring large amounts of data. The following table provides results 
from sample tests. As you can see, there was a 30-53% performance gain when switching from ATOM to JSON 
and a 67% performance gain when switching from ATOM to the new JSON light format (available in WCF Data 
Services 5.1). 


ROWS ATOM JSON JSON (LIGHT) 
10000 113 seconds 74 seconds 68 seconds 
1000000 1110 seconds 853 seconds 665 seconds 


Related Topics in This Section 
e Tutorial: Using the OData Source 
e Modify OData Source Query at Runtime 


e OData Source Properties 


OData Source Editor (Connection Page) 


Use the Connection page of the OData Source Editor dialog box to select the OData connection manager for 
the OData source. This page also lets you specify a collection or a resource path and any query options to 
indicate what data needs to be retrieved from the OData source. 


Static Options 


OData connection manager 


Select an existing connection manager from the list, or create a new connection by clicking New. 


After you select or create a connection manager, the dialog box displays the OData protocol version that the 


connection manager is using. 


New 
Create a new connection manager by using the OData Connection Manager Editor dialog box. 


Use collection or resource path 
Specify the method for selecting data from the source. 


OPTION DESCRIPTION 

Collection Retrieve data from the OData source by using a collection 
name. 

Resource Path Retrieve data from the OData source by using a resource 
path. 


Query options 
Specify options for the query. For example: $top=5 


Feed url 
Displays the read-only feed URL based on options you selected on this dialog box. 


Preview 


Preview results by using the Preview dialog box. Preview can display up to 20 rows. 


Dynamic Options 


Use collection or resource path = Collection 
Collection 

Select a collection from the drop-down list. 
Use collection or resource path = Resource Path 


Resource path 
Type a resource path. For example: Employees 


OData Source Editor (Columns Page) 


Use the Columns page of the OData Source Editor dialog box to select external (source) columns to be 
included in the output and map them to output columns. 


Options 
Available External Columns 


View the list of available source columns in the data source. Use check boxes in the list to add to or remove 
columns to the table at the bottom of the page. The selected columns are added to the output. 


External Column 
View source columns that you chose to be included in the output. 


Output Column 
Provide a unique name for each output column. The default is the name of the selected external (source) 


column; however, you can choose any unique, descriptive name. 


OData Source Editor (Error Output Page) 


Use the Error Output page of the OData Source Editor dialog box to select error handling options and to set 


properties on error output columns. 


Options 
Input/Output 


View the name of the data source. 


Column 
View the external (source) columns that you selected on the Connection Manager page of the OData Source 
Editor dialog box. 


Error 
Specify what should happen when an error occurs: ignore the failure, redirect the row, or fail the component. 


Related Topics: Error Handling in Data 


Truncation 


Specify what should happen when a truncation occurs: ignore the failure, redirect the row, or fail the component. 


Description 
View the description of the error. 


Set this value to selected cells 
Specify what should happen to all the selected cells when an error or truncation occurs: ignore the failure, 
redirect the row, or fail the component. 


Apply 
Apply the error handling option to the selected cells. 


See Also 


OData Connection Manager 
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This tutorial walks you through the process to extract the Employees collection from the sample Northwind 
OData service (https://services.odata.org/V3/Northwind/Northwind.svc/), and then load it into a flat file. 


1. Create an Integration Services project 


1. Launch SQL Server Data Tools or Visual Studio. 
2. Click File, point to New, and click Project. 


3. In the New Project dialog box, expand Installed, expand Templates, expand Business Intelligence, 
and click Integration Services. 


4. Select Integration Services Project for the type of project. 


5. Enter aname and select a location for the project, and click OK. 


2. Add and configure an OData Source 


1. Drag-drop a Data Flow Task from the SSIS Toolbox on to the control flow design surface of your SSIS 
package. 


2. Click the Data Flow tab, or double-click on the Data Flow Task to open the Data Flow design surface. 
3. Drag-drop OData Source from the Common group in the SSIS Toolbox. 

4. Double-click the OData Source component to launch the OData Source Editor dialog box. 

5. Click New... to add a new OData Connection Manager. 


6. Enter the OData service URL for Service document location. This URL can be the URL to the service 
document, or to a specific feed or entity. For the purpose of this tutorial, enter the URL to the service 
document: https://services.odata.org/V3/Northwind/Northwind.svc/. 


7. Confirm that Windows Authentication is selected for the authentication to use to access the OData 
Service. Windows Authentication is selected by default. 


8. Click Test Connection to test the connection, and click OK to finish creating an instance of OData 
Connection Manager. 


9. Inthe OData Source Editor Dialog Box, confirm that Collection is selected for Use collection on 
resource path option. 


10. From the Collection drop-down list, select Employees. 


11. Enter any additional OData query options or filters for Query Options. For example, 
gorderby=CompanyName&$top=1e0 . For the purpose of this tutorial, enter $top=5 . 


12. Click Preview to preview the data. 
13. Click Columns in the left navigation pane to switch to the Columns page. 


14. Select EmployeelD, FirstName, and LastName from Available External Columns by checking the 


15% 


10. 


check boxes. 


Click OK to close the OData Source Editor dialog box. 


. Add and configure a Flat File Destination 


. Now, drag-drop a Flat File Destination from SSIS Toolbox to the Data Flow design surface below the 


OData Source component. 


. Connect OData Source component with the Flat File Destination component using blue arrow. 
. Double-click on Flat File Destination. You should see the Flat File Destination Editor dialog box. 
. Inthe Flat File Destination Editor dialog box, click New to create a new flat file connection manager. 


. Inthe Flat File Format dialog box, select Delimited. Then you see the Flat File Connection Manager 


Editor dialog box. 


. Inthe Flat File Connection Manager Editor dialog box, for the File name, enter c:\Employees.txt . 
. In the left navigation pane, click Columns. You can preview the data on this page. 
. Click OK to close the Flat File Connection Manager Editor dialog box. 


. Inthe Flat File Destination Editor dialog box, click Mappings in the left navigation pane. Review the 


mappings. 


Click OK to close the Flat File Destination Editor dialog box. 


4. Run the package 


Run the SSIS package. Verify that the output file is created with ID, First Name, and Last Name for five 


employees from the OData feed. 


Provide an OData Source Query at Runtime 
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You can modify the OData Source query at runtime by adding an expression to the [OData Source].[Query] 
property of the Data Flow task. 


The columns returned have to be the same columns that were returned at design time; otherwise, you get an 
error when the package is executed. Be sure to specify the same columns (in the same order) when using the 
$select query option. A safer alternative to using the $select option is to deselect the columns you don't want 
directly from the Source Component UI. 


There are a few different ways of dynamically setting the query value at runtime. Here are some of the more 
common methods. 


Provide the query as a parameter 


The following procedure shows how to expose the query used by an OData Source component as a parameter 
of the package. 


1. Right click on the Data Flow task and select the Parameterize... option. 


2. In the Parameterize dialog, select [< Name of the OData Source Component>].[Query] for 
Property. 


3. Choose whether to create new parameter or use an existing parameter. 
4. If you select Create new parameter: 

a. Enter name and description for the parameter. 

b. Specify default value for the parameter. 

c. Specify the scope (package or project) for the parameter. 

d. Specify whether the parameter is required or not 


5. Click OK to close the dialog box. 


Provide the query with an expression 


This method is useful when you want to dynamically construct the query string at runtime. 
1. Select the Data Flow Task that contains your OData Source. 

2. In the Properties window, highlight the Expressions property. 

3. Click the ... (ellipsis) button to bring up the Property Expressions Editor. 

4. Select the [OData Source].[Query] property. 

5. Click the ... (ellipsis) button for Expression. 

6. Enter the expression. 


7. Click OK. 








NOTE 
When you use this approach, you have to ensure that the values you set are properly URL encoded. When receiving 
values from user input (for example, setting individual query option values from a parameter), you must ensure that the 


values are validated to avoid potential SQL injection-type attacks. 





OData Source Properties 
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When you right-click OData Source in the data flow and click Properties, you see properties for the OData 
Source component in the Properties window. 


Properties 

PROPERTY DESCRIPTION 

CollectionName Name of the collection to retrieve from the OData service. 
The CollectionName property is used when 
UseResourcePath is False. 

This property is expressionable, which lets you set the value 
at runtime. However, if the metadata of the collection does 
not match the metadata that existed at design time, a 
validation error occurs, causing the data flow execution to 
fail. 

DefaultStringLength This value specifies default length for string columns that 
have no max length. 

Default: 4000 

Query The OData query parameters. This property is 
expressionable and can be set at runtime. 

ResourcePath Use this property when you need to specify a full resource 
path, rather than just selecting a collection name. This 
property is used when UseResourcePath is True. 

UseResourcePath When set to True, the ResourcePath value is appended to 
the base URL to determine the OData feed location. When 
set to False, the CollectionName value is used. 

Default: False 
See Also 


OData Source 
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This topic describes the concepts necessary for creating an ODBC data flow using SQL Server 2019 Integration 
Services (SSIS) 


The Connector for Open Database Connectivity (ODBC) for SQL Server 2019 Integration Services (SSIS) helps 
SSIS developers easily create packages that load and unload data from ODBC-supported databases. 


The ODBC Connector is designed to achieve optimal performance when loading data into or unloading data 
from an ODBC-supported database in the context of SQL Server 2019 Integration Services (SSIS). 


Benefits 


The ODBC source and ODBC destination for SQL Server 2019 Integration Services (SSIS) provides a competitive 
edge for SSIS in projects dealing with loading data into or unloading data from ODBC-supported databases. 


Both the ODBC source and ODBC destination enable high performance data integration with ODBC-enabled 
databases. Both components can be configured to work with row-wise parameter array bindings for high- 
functioning ODBC providers that support this mode of binding and single-row parameter bindings for low- 
functioning ODBC providers. 


Getting Started with the ODBC Source and Destination 


Before you can set up packages that use SQL Server 2019 Integration Services (SSIS), you must make sure that 
the following are available. 


e ODBC Source 


e ODBC Destination 


The ODBC source and ODBC destination provide an easy way to unload and load data and transfer data from an 
ODBC-supported source database to an ODBC-supported destination database. 


To use the source or destination to load or unload data, open a new SQL Server 2019 Integration Services (SSIS) 
Project in the SQL Server Data Tools. Then drag the source or destination onto the design surface of the SQL 
Server Data Tools. 


e The ODBC source component reads data from the source ODBC-supported database. 

You can connect the ODBC source to any destination or transform component supported by SSIS. 
See also: 

ODBC Source 

ODBC Source Editor (Connection Manager Page) 

ODBC Source Editor (Error Output Page) 


e The ODBC destination loads data into an ODBC-supported database. You connect the destination to any 
source or transform component supported by SSIS. 


See also: 


ODBC Destination 
ODBC Destination Editor (Connection Manager Page) 


ODBC Destination Editor (Error Output Page) 


Operating Scenarios 


This section describes some of the main uses for the ODBC source and destination components. 


Bulk Copy Data from SQL Server tables to any ODBC-Supported database table 


You can use the components to bulk copy data from one or more SQL Server tables to a single ODBC-supported 
database table. 


The following example shows how to create an SSIS Data Flow Task that extracts data from a SQL Server table 
and loads it into a DB2 table. 


e Create an SQL Server 2019 Integration Services (SSIS) Project in the SQL Server Data Tools. 


e Create an OLE DB connection manager that connects to the SQL Server database that contains the data 
you want to copy. 


e Create an ODBC connection manager that uses a locally installed DB2 ODBC driver with a DSN pointing 
to a local or remote DB2 database. This database is where the data from the SQL Server database is 
loaded. 


e Drag an OLE DB source to the design surface, then configure the source to get the data from the SQL 
Server database and table with the data you are going to extract. Use the OLE DB connection manager 
you created previously. 


e Drag an ODBC destination to the design surface, connect the source output to the ODBC destination, then 
configure the destination to load the data into the DB2 table with the data you extract from the SQL 
Server database. Use the ODBC connection manager you created previously. 


Bulk Copy Data from ODBC-supported database tables to any SQL Server table 


You can use the components to bulk copy data from one or more ODBC-supported database tables to a single 
SQL Server database table. 


The following example shows how to create an SSIS Data Flow Task that extracts data from a Sybase database 


table and loads it into a SQL Server database table. 
e Create an SQL Server 2019 Integration Services (SSIS) Project in the SQL Server Data Tools 


e Create an ODBC connection manager that uses a locally installed Sybase ODBC driver with a DSN 
pointing to a local or remote Sybase database. This database is where the data is extracted. 


e Create an OLE DB connection manager that connects to the SQL Server database where you want to load 
the data. 


e Drag an ODBC source to the design surface, then configure the source to get the data from the Sybase 
table with the data you are going to copy. Use the ODBC connection manager you created previously. 


e Drag an OLE DB destination to the design surface, connect the source output to the OLE DB destination, 
then configure the destination to load the data into the SQL Server table with the data you extract from 
the Sybase database. Use the OLE DB connection manager you created previously. 


Supported Data Types 


The ODBC Bulk SSIS components support all built-in ODBC data types, including support for large objects 


(CLOBs and BLOBs). 


There is no data type support for extensible C types as described in the ODBC 3.8 specifications.The following 
table describes which SSIS data types are used for each ODBC SQL type. An SSIS developer can override the 
default mapping and specify a different SSIS data type for input/output columns without impacting the 
performance for the required data conversions. 


ODBC SQL TYPE SSIS DATA TYPE COMMENTS 
SQL_BIT DT_BOOL 
SQL_TINYINT DT_I1 SQL data types are mapped to SSIS 
unsigned types (DT_UI1, DT_UI2, 
DT_UI1 DT_UI4, DT_UI8) when the ODBC 


driver sets the UNSIGNED_ATTRIBUTE 
to SQL_TRUE for that SQL data type. 


SQL_SMALLINT DT_l2 SQL data types are mapped to SSIS 
unsigned types (DT_UI1, DT_UI2, 
DT_UI2 DT_UI4, DT_UI8) when the ODBC 


driver sets the UNSIGNED_ATTRIBUTE 
to SQL_TRUE for that SQL data type. 


SQL_INTEGER DT_|4 SQL data types are mapped to SSIS 
unsigned types (DT_UI1, DT_UI2, 
DTUI4 DT_UI4, DT_UI8) when the ODBC 


driver sets the UNSIGNED_ATTRIBUTE 
to SQL_TRUE for that SQL data type. 


SQL_BIGINT DT_I8 SQL data types are mapped to SSIS 
unsigned types (DT_UI1, DT_UI2, 
DT_UI8 DT_UI4, DT_UI8) when the ODBC 


driver sets the UNSIGNED_ATTRIBUTE 
to SQL_TRUE for that SQL data type. 


SQL_DOUBLE DT_R8& 

SQL_FLOAT DT_R8& 

SQL_REAL DT_R4 

SQL_NUMERIC (p,s) DT_NUMERIC (p,s) The numeric data type is mapped to 
DT_NUMERIC when P is greater than 
or equal to 38 and S is greater than or 
equal to 0 and S is less than or equal 
toP 

DT_R8 The numeric data type is mapped to 


DT_R8 when at least one of the 
following is true: 


Precision is greater than 38 
Scale is less than zero 
Scale is greater than 38 


Scale is greater than Precision 


ODBC SQL TYPE 


SQL_DECIMAL (p,s) 


SQL_DATE 


SQL_TYPE_DATE 


SQL_TIME 


SQL_TYPE_TIME 


SQL_TIMESTAMP 


SQL_TYPE_TIMESTAMP 


SQL_CHAR 


SQLVARCHAR 


SSIS DATA TYPE 


DT_CY 


DT_NUMERIC (ps) 


DT_R8 


DT_CY 


DT_DBDATE 


DT_DBTIME 


DT_DBTIMESTAMP 


DT_DBTIMESTAMP2 


DT_STR 


DT_WSTR 


DT_TEXT 


DT_NTEXT 


COMMENTS 


The numeric data type is mapped to 
DT_CY when it is declared as a money 
data type. 


The decimal data type is mapped to 
DT_NUMERIC when P is greater than 
or equal to 38 and S is greater than or 
equal to 0 and S is less than or equal 
toP 


The decimal data type is mapped to 
DT_R8 when at least one of the 
following is true: 


Precision is greater than 38 
Scale is less than zero 
Scale is greater than 38 


Scale is greater than Precision 


The decimal data type is mapped to 
DT_CY when it is declared as a money 
data type. 


SQL_TIMESTAMP data types are 
mapped to DT_DBTIMESTAMP2 if scale 
is greater than 3. In all other cases, 
they are mapped to DT_DBTIMESTAMP 


DT_STR is used if the column length is 
less than or equal to 8000 and the 
ExposeStringsAsUnicode property 
is false. 


DT_WSTR is used if the column length 
is less than or equal to 8000 and the 
ExposeStringsAsUnicode property 
is true. 


DT_TEXT is used if the column length is 
greater than 8000 and the 
ExposeStringsAsUnicode property 
is false. 


DT_NTEXT is used if the column length 
is greater than 8000 and the 
ExposeStringsAsUnicode property 
is true. 


ODBC SQL TYPE SSIS DATA TYPE COMMENTS 


SQL_LONGVARCHAR DT_TEXT DT_NTEXT is used if the 
ExposeStringsAsUnicode property 
DT_NTEXT is true. 
SQL_WCHAR DT_WSTR DT_WSTR is used if the column length 
is less than or equal to 4000. 
SQL_WVARCHAR DT_NTEXT 
DT_NTEXT is used if the column length 
is greater than 4000. 
SQL_WLONGVARCHAR DT_NTEXT 
SQL_BINARY DT_BYTE DT_BYTES is used if the column length 
is less than or equal to 8000. 
DT_IMAGE 
DT_IMAGE if the column length is 
greater than 8000. 
SQL_LONGVARBINARY DT_IMAGE 
SQL_GUID DT_GUID 
SQL_INTERVAL_YEAR DT_WSTR 


SQL_INTERVAL_MONTH 
SQL_INTERVAL_DAY 
SQL_INTERVAL_HOUR 
SQL_INTERVAL_MINUTE 
SQL_INTERVAL_SECOND 
SQL_INTERVAL_YEAR_TO_MONTH 
SQL_INTERVAL_DAY_TO_HOUR 
SQL_INTERVAL_DAY_TO_MINUTE 
SQL_INTERVAL_DAY_TO_SECOND 
SQL_INTERVAL_HOUR_TO_MINUTE 
SQL_INTERVAL_HOUR_TO_SECOND 


SQL_INTERVAL_MINUTE_TO_SECOND 


Provider Specific Data Types DT_BYTES DT_BYTES is used if the column length 
is less than or equal to 8000. 
DT_IMAGE 
DT_IMAGE is used if the column length 
is Zero or greater than 8000. 


In This Section 


e ODBC Source 


e ODBC Destination 
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The ODBC destination bulk loads data into ODBC-supported database tables. The ODBC destination uses an 
ODBC connection manager to connect to the data source. 


An ODEC destination includes mappings between input columns and columns in the destination data source. 
You do not have to map input columns to all destination columns, but depending on the properties of the 
destination columns, errors may occur if no input columns are mapped to the destination columns. For example, 
if a destination column does not allow null values, an input column must be mapped to that column. In addition, 
columns of different types can be mapped, however if the input data is not compatible for the destination 
column type, an error occurs at runtime. Depending on the error behavior setting, the error will be ignored, 
cause a failure, or the row is sent to the error output. 


The ODBC destination has one regular output and one error output. 


Load Options 


The ODBC destination can use one of two access load modules. You set the mode in the ODBC Source Editor 
(Connection Manager Page). The two modes are: 


e Batch: In this mode the ODBC destination attempts to use the most efficient insertion method based on 
the perceived ODBC provider capabilities. For most modern ODBC providers, this would mean preparing 
an INSERT statement with parameters and then using a row-wise array parameter binding (where the 
array size is controlled by the BatchSize property). If you select Batch and the provider does not 
support this method, the ODBC destination automatically switches to the Row-by-row mode. 


e Row-by-row: In this mode, the ODBC destination prepares an INSERT statement with parameters and 
uses SQL Execute to insert rows one at a time. 


Error Handling 
The ODBC destination has an error output. The component error output includes the following output columns: 


e Error Code: The number that corresponds to the current error. See the documentation for your source 
database for a list of errors. For a list of SSIS error codes, see the SSIS Error Code and Message Reference. 


e Error Column: The source column causing the error (for conversion errors). 
e The standard output data columns. 


Depending on the error behavior setting, the ODBC destination supports returning errors (data conversion, 
truncation) that occur during the extraction process in the error output. For more information, see ODBC Source 
Editor (Error Output Page). 


Parallelism 


There is no limitation on the number of ODBC destination components that can run in parallel against the same 
table or different tables, on the same machine or on different machines (other than normal global session 
limits). 


However, limitations of the ODBC provider being used may restrict the number of concurrent connections 
through the provider. These limitations limit the number of supported parallel instances possible for the ODBC 
destination. The SSIS developer must be aware of the limitations of any ODBC provider being used and take 
them into consideration when building SSIS packages. 


You must also be aware that concurrently loading into the same table may reduce performance because of 
standard record locking. This depends on the data being loaded and on the table organization. 


Troubleshooting the ODBC Destination 


You can log the calls that the ODBC source makes to external data providers. You can use this logging capability 
to troubleshoot the saving of data to external data sources that the ODBC destination performs. To log the calls 
that the ODBC destination makes to external data providers, enable the ODBC driver manager trace. For more 
information, see the Microsoft documentation on How To Generate an ODBC Trace with ODBC the Data Source 
Administrator. 


Configuring the ODBC Destination 

You can configure the ODBC destination programatically or through the SSIS Designer 

For more information, see one of the following topics: 

e ODBC Destination Editor (Connection Manager Page) 

e ODBC Destination Editor (Mappings Page) 

e ODBC Destination Editor (Error Output Page) 

The Advanced Editor dialog box contains the properties that can be set programmatically. 
To open the Advanced Editor dialog box: 


e Inthe Data Flow screen of your SQL Server 2019 Integration Services (SSIS) project, right click the ODBC 
destination and select Show Advanced Editor. 


For more information about the properties that you can set in the Advanced Editor dialog box, see ODBC 
Destination Custom Properties. 


In This Section 


e Load Data by Using the ODBC Destination 


e ODBC Destination Custom Properties 


ODBC Destination Editor (Connection Manager Page) 


Use the Connection Manager page of the ODBC Destination Editor dialog box to select the ODBC 


connection manager for the destination. This page also lets you select a table or view from the database 
To open the ODBC Destination Editor Connection Manager Page 


Task List 


e@ In SQL Server Data Tools, open the SQL Server 2019 Integration Services (SSIS) package that has the 
ODBC destination. 


e On the Data Flow tab, double-click the ODBC destination. 


e Inthe ODBC Destination Editor, click Connection Manager. 


Options 

Connection manager 

Select an existing ODBC connection manager from the list, or click New to create a new connection. The 
connection can be to any ODBC-supported database. 


New 
Click New. The Configure ODBC Connection Manager Editor dialog box opens where you can create a new 


connection manager. 


Data Access Mode 


Select the method for loading data to the destination. The options are shown in the following table: 
OPTION DESCRIPTION 


Table Name - Batch Select this option to configure the ODBC destination to work 
in batch mode. When you select this option the following 
options are available: 


Name of the table or the view: Select an available table 
or view from the list. 


This list contains the first 1000 tables only. If your database 
contains more than 1000 tables, you can type the beginning 
of a table name or use the (*) wild card to enter any part of 
the name to display the table or tables you want to use. 


Batch size: Type the size of the batch for bulk loading. This 
is the number of rows loaded as a batch 


Table Name - Row by Row Select this option to configure the ODBC destination to 
insert each of the rows into the destination table one at a 
time. When you select this option the following option is 
available: 


Name of the table or the view: Select an available table 
or view from the database from the list. 


This list contains the first 1000 tables only. If your database 
contains more than 1000 tables, you can type the beginning 
of a table name or use the (*) wild card to enter any part of 
the name to display the table or tables you want to use. 


Preview 


Click Preview to view up to 200 rows of data for the table that you selected. 


ODBC Destination Editor (Mappings Page) 


Use the Mappings page of the ODBC Destination Editor dialog box to map input columns to destination 


columns. 


Options 
Available Input Columns 
The list of available input columns. Drag-and-drop an input column to an available destination column to map 


the columns. 


Available Destination Columns 
The list of available destination columns. Drag-and-drop a destination column to an available input column to 


map the columns. 


Input Column 
View the input columns that you selected. You can remove mappings by selecting <ignore> to exclude 


columns from the output. 


Destination Column 


View all available destination columns, both mapped and unmapped. 


ODBC Destination Editor (Error Output Page) 


Use the Error Output page of the ODBC Destination Editor dialog box to select error handling options. 
To open the ODBC Destination Editor Error Output Page 


Task List 


e In SQL Server Data Tools, open the SQL Server 2019 Integration Services (SSIS) package that has the 
ODBC destination. 


e On the Data Flow tab, double-click the ODBC destination. 
e Inthe ODBC Destination Editor, click Error Output. 


Options 
Input/Output 


View the name of the data source. 


Column 


Not used. 


Error 
Select how the ODBC destination should handle errors in a flow: ignore the failure, redirect the row, or fail the 


component. 


Truncation 
Select how the ODBC destination should handle truncation in a flow: ignore the failure, redirect the row, or fail 


the component. 

Description 

View a description of the error. 
Set this value to selected cells 


Select how the ODBC destination handles all selected cells when an error or truncation occurs: ignore the failure, 


redirect the row, or fail the component. 


Apply 

Apply the error handling options to the selected cells. 

Error Handling Options 

You use the following options to configure how the ODBC destination handles errors and truncations. 
Fail Component 

The Data Flow task fails when an error or a truncation occurs. This is the default behavior. 

Ignore Failure 

The error or the truncation is ignored. 

Redirect Flow 


The row that is causing the error or the truncation is directed to the error output of the ODBC destination. For 


more information, see ODBC Destination. 


Load Data by Using the ODBC Destination 
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This procedure shows how to load data by using the ODBC destination. To add and configure an ODBC 
destination, the package must already include at least one Data Flow task and source. 


To load data using an ODBC destination 


1. In SQL Server Data Tools, open the Integration Services package you want. 

2. Click the Data Flow tab, and then, from the Toolbox, drag the ODBC destination to the design surface. 
3. Drag an available output of a data flow component to the input of the ODBC destination. 

4. Double-click the ODBC destination. 


5. In the ODBC Destination Editor dialog box, on the Connection Manager page, select an existing 


ODBC connection manager or click New to create a new connection manager. 
6. Select the data access method. 


e Table Name - Batch: Select this option to configure the ODBC destination to work in batch mode. 
When you select this option, you can set the Batch size. 


e Table Name - Row by Row: Select this option to configure the ODBC destination to insert each 
of the rows into the destination table one at a time. When you select this option, the data is loaded 
into the table one row ata time. 


7. Inthe Name of the table or the view field, select an available table or view from the database from 
the list or type in a regular expression to identify the table.This list contains the first 1000 tables only. If 
your database contains more than 1000 tables, you can type the beginning of a table name or use the (*) 
wild card to enter any part of the name to display the table or tables you want to use. 


8. You can click Preview to view up to 200 rows of the data from the table selected in the ODBC 
destination. 


9. Click Mappings and then map columns from the Available Input Columns list to columns in the 
Available Destination Columns list by dragging columns from one list to another. 


10. To configure the error output, click Error Output. 
11. Click OK. 


12. To save the updated package, click Save Selected Items on the File menu. 


See Also 


ODBC Destination Editor (Connection Manager Page) 
ODBC Destination Editor (Mappings Page) 
ODBC Source Editor (Error Output Page) 


ODBC Destination Custom Properties 
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The following table describes the custom properties of the ODBC destination. All properties can be set from 


SSIS property expressions. 


PROPERTY NAME DATA TYPE 
Connection ODBC Connection 
BatchSize Integer 
BindCharColumnAs Integer (enumeration) 


DESCRIPTION 


An ODBC connection to access the 
destination database. 


The size of the batch for bulk loading. 
This is the number of rows loaded as a 
batch. This is valid only if the row-wise 
parameter binding is supported. If the 
row-wise parameter binding is not 
supported, the batch size is 1. 


This property determines how the 
ODBC destination binds columns with 
multiple-byte string types such as 
SQL_CHAR, SQL_VARCHAR, or 
SQL_LONGVARCHAR. 


The possible values are Unicode (0), 
which binds the columns as 
SQL_C_WCHAR, and ANSI (1), which 
binds the columns as SQL_C_CHAR). 
The default is Unicode (0). 


Unicode is the best option for most 
ODBC 3.x providers and ODBC 2.x 
providers that support binding CHAR 
parameters as wide strings. When you 
select Unicode and 
ExposeCharColumnsAsUnicode is True, 
the user does not need to specify the 
code page used by the source 
database. 


Note: This property is not available in 
the ODBC Destination Editor, but 
can be set by using the Advanced 
Editor. 


PROPERTY NAME 


BindNumericAs 


DefaultCodePage 


InsertMethod 


StatementTimeout 


TableName 


DATA TYPE 


Integer (enumeration) 


Integer 


Integer (enumeration) 


Integer 


String 


DESCRIPTION 


This property determines how the 
ODBC destination binds columns with 
numeric data with data types 
SQL_TYPE_NUMERIC and 
SQL_TYPE_DECIMAL. 


The possible values are Char (0), which 
binds the columns as SQL_C_CHAR 
and Numeric (1), which binds the 
columns as SQL_C_NUMERIC. The 
default value is Char (0). 


Note: This property is not available in 
the ODBC Destination Editor, but 
can be set by using the Advanced 
Editor. 


The code page to use for string 
columns. 


Note: This property is not available in 
the ODBC Destination Editor, but 
can be set by using the Advanced 
Editor. 


The method used for inserting the 
data. The possible values are Row by 
row (0) and Batch (1). The default value 
is Batch (1). 


For more information about these 
options, see "Load Options" in ODBC 
Destination. 


The number of seconds to wait for an 
SQL statement to execute before 
returning, with an error, to the 
application. The default value is 120. 


The name of the destination table 
where the data that is being inserted. 


PROPERTY NAME 


TransactionSize 


LobChunkSize 


DATA TYPE 


Integer 


Integer 


DESCRIPTION 


The number of inserts in a single 
transaction. The default value is 0, 
which means that the ODBC 
destination works in auto commit 
mode. 


Because the ODBC connection 
manager does not support distributed 
transactions, it is possible to set this 
property with a value other than 0. 
However, if the connection manager 
RetainSameConnection property is 
set to true then this property must be 
set to 0. 


Note: This property is not available in 
the ODBC Destination Editor, but 
can be set by using the Advanced 
Editor. 


The chunk size allocation for LOB 
columns. 
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The ODBC source extracts data from ODBC-supported database by using a database table, a view, or an SQL 
statement. 


The ODBC source has the following data access modes for extracting data: 

e A table or view. 

e The results of an SQL statement. 

The source uses an ODBC connection manager, which specifies the provider to use. 


An ODEC source includes the source data output columns. When output columns are mapped in the ODBC 
destination to the destination columns, errors may occur if no output columns are mapped to the destination 
columns. Columns of different types can be mapped, however if the output data is not compatible for the 
destination then an error occurs at runtime. Depending on the error behavior, setting the error will be ignored, 
cause a failure, or the row is sent to the error output. 


The ODBC source has one regular output and one error output. 


Error Handling 
The ODBC source has an error output. The component error output includes the following output columns: 


e Error Code: The number that corresponds to the current error. See the documentation for the ODBC- 
supported database you are using for a list of errors. For a list of SSIS error codes, see the SSIS Error 
Code and Message Reference. 


e Error Column: The source column causing the error (for conversion errors). 
e The standard output data columns. 


Depending on the error behavior setting, the ODBC source supports returning errors (data conversion, 
truncation) that occur during the extraction process in the error output. For more information, see ODBC 
Destination Editor (Connection Manager Page). 


Data Type Support 


For information about the data types supported by the ODBC source, see Connector for Open Database 
Connectivity (ODBC). 


Extract Options 


The ODBC source operates in either Batch or Row-by-Row mode. The mode used is determined by the 
FetchMethod property. The following list describes the modes. 


e Batch: The component attempts to use the most efficient fetch method based on the perceived ODBC 
provider capabilities. For most modern ODBC providers, this is SQLFetchScroll with array binding (where 
the array size is determined by the BatchSize property). If you select Batch and the provider does not 
support this method, the ODBC destination automatically switches to the Row-by-row mode. 


e Row-by Row: The component uses SQLFetch to retrieve the rows one at a time. 


For more information about the FetchMethod property, see ODBC Source Custom Properties. 


Parallelism 


There is no limitation on the number of ODBC source components that can run in parallel against the same table 
or different tables, on the same machine or on different machines (other than normal global session limits). 


However, limitations of the ODBC provider being used may restrict the number of concurrent connections 
through the provider. These limitations limit the number of supported parallel instances possible for the ODBC 
source. The SSIS developer must be aware of the limitations of any ODBC provider being used and take them 
into consideration when building SSIS packages. 


Troubleshooting the ODBC Source 


You can log the calls that the ODBC source makes to external data providers. You can use this logging capability 
to troubleshoot the loading of data from external data sources that the ODBC source performs. To log the calls 
that the ODBC source makes to external data providers, enable the ODBC driver manager trace. For more 
information, see the Microsoft documentation on How To Generate an ODBC Trace with ODBC the Data Source 
Administrator. 


Configuring the ODBC Source 


You can configure the ODBC source programmatically or through the SSIS Designer. 
The Advanced Editor dialog box contains the properties that can be set programmatically. 
To open the Advanced Editor dialog box: 


e Inthe Data Flow screen of your SQL Server 2019 Integration Services (SSIS) project, right click the ODBC 
source and select Show Advanced Editor. 


For more information about the properties that you can set in the Advanced Editor dialog box, see ODBC Source 
Custom Properties. 


In This Section 


e Extract Data by Using the ODBC Source 


e ODBC Source Custom Properties 


ODBC Source Editor (Connection Manager Page) 


Use the Connection Manager page of the ODBC Source Editor dialog box to select the ODBC connection 
manager for the source. This page also lets you select a table or view from the database. 


Task List 
To open the ODBC Source Editor Connection Manager Page 


e In SQL Server Data Tools, open the SQL Server 2019 Integration Services (SSIS) package that has the 
ODBC source. 


e On the Data Flow tab, double-click the ODBC source. 


Options 


Connection manager 


Select an existing ODBC connection manager from the list, or click New to create a new connection. The 


connection can be to any ODBC-supported database. 


New 

Click New. The Configure ODBC Connection Manager Editor dialog box opens where you can create a new 
ODBC connection manager. 

Data Access Mode 


Select the method for selecting data from the source. The options are shown in the following table: 
OPTION DESCRIPTION 


Table Name Retrieve data from a table or view in the ODBC data source. 
When you select this option, select a value from the list for 
the following: 


Name of the table or the view: Select an available table 
or view from the list or type a regular expression to identify 
the table. 


This list contains the first 1000 tables only. If your database 
contains more than 1000 tables, you can type the beginning 
of a table name or use the (*) wild card to enter any part of 
the name to display the table or tables you want to use. 


SQL command Retrieve data from the ODBC data source by using an SQL 
query. You should write the query in the syntax of the 
source database you are working with. When you select this 
option, enter a query in one of the following ways: 


Enter the text of the SQL query in the SQL command text 
field. 


Click Browse to load the SQL query from a text file. 


Click Parse query to verify the syntax of the query text. 


Preview 


Click Preview to view up to the first 200 rows of the data extracted from the table or view you selected. 


ODBC Source Editor (Columns Page) 


Use the Columns page of the ODBC Source Editor dialog box to map an output column to each external 


(source) column. 


Task List 
To open the ODBC Source Editor Columns Page 


1. In SQL Server Data Tools, open the SQL Server 2019 Integration Services (SSIS) package that has the 
ODBC source. 


2. On the Data Flow tab, double-click the ODBC source. 
3. In the ODBC Source Editor, click Columns. 


Options 
Available External Columns 


A list of available external columns in the data source. You cannot use this table to add or delete columns. Select 


the columns to use from the source. The selected columns are added to the External Column list in the order 


they are selected. 


Select the Select All check box to select all of the columns. 


External Column 
A view of the external (source) columns in the order that you see them when configuring components that 


consume data from the ODBC source. 


Output Column 
Enter a unique name for each output column. The default is the name of the selected external (source) column; 


however, you can choose any unique, descriptive name. The name entered is displayed in the SSIS Designer. 


ODBC Source Editor (Error Output Page) 


Use the Error Output page of the ODBC Source Editor dialog box to select error handling options. 


Task List 
To open the ODBC Source Editor Error Output Page 


e In SQL Server Data Tools, open the SQL Server 2019 Integration Services (SSIS) package that has the 
ODBC source. 


e On the Data Flow tab, double-click the ODBC source. 
e Inthe ODBC Source Editor, click Error Output. 


Options 
Input/Output 


View the name of the data source. 


Column 


Not used. 


Error 
Select how the ODBC source should handle errors in a flow: ignore the failure, redirect the row, or fail the 


component. 


Truncation 
Select how the ODBC source should handle truncation in a flow: ignore the failure, redirect the row, or fail the 


component. 
Description 


Not used. 


Set this value to selected cells 
Select how the ODBC source handles all selected cells when an error or truncation occurs: ignore the failure, 


redirect the row, or fail the component. 


Apply 
Apply the error handling options to the selected cells. 


Error Handling Options 
You use the following options to configure how the ODBC source handles errors and truncations. 


Fail Component 


The Data Flow task fails when an error or a truncation occurs. This is the default behavior. 


Ignore Failure 


The error or the truncation is ignored. 


Redirect Flow 


The row that is causing the error or the truncation is directed to the error output of the ODBC source. 


Extract Data by Using the ODBC Source 
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This procedure describes how to extract data by using an ODBC source. To add and configure an ODBC source, 
the package must already include at least one Data Flow task. 


To extract data using an ODBC source 


1. In SQL Server Data Tools, open the SQL Server 2019 Integration Services (SSIS) package you want. 
2. Click the Data Flow tab, and then, from the Toolbox, drag the ODBC source to the design surface. 
3. Double-click the ODBC source. 


4. Inthe ODBC Source Editor dialog box, on the Connection Manager page, select an existing ODBC 
connection manager or click New to create a new connection manager. 


5. Select the data access method. 


e Table Name: Select a table or view in the database or type a regular expression to identify the 
table to which the ODBC connection manager connects. 


This list contains the first 1000 tables only. If your database contains more than 1000 tables, you 
can type the beginning of a table name or use the (*) wild card to enter any part of the name to 
display the table or tables you want to use. 


e SQL Command: Type an SQL Command or click Browse to load the SQL query from a text file. 
6. You can click Preview to view up to 200 rows of the data extracted by the ODBC source. 


7. To update the mapping between external and output columns, click Columns and select different 
columns in the External Column list. 


8. If necessary, update the names of output columns by editing values in the Output Column list. 
9. To configure the error output, click Error Output. 
10. Click OK. 


11. To save the updated package, click Save Selected Items on the File menu. 


See Also 


ODBC Source Editor (Connection Manager Page) 
ODBC Source Editor (Columns Page) 
ODBC Source Editor (Error Output Page) 


ODBC Source Custom Properties 
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The following table describes the custom properties of the ODBC source. All properties can be set from SSIS 
property expressions. 


PROPERTY NAME DATA TYPE DESCRIPTION 


Connection ODBC Connection An ODBC connection to access the 
source database. 


AccessMode Integer (enumeration) The mode used to access the database. 
The possible values are Table Name (0) 
and SQL Command (1). 


The default is Table Name (0). 


BatchSize Integer The size of the batch for bulk 
extraction. This is the number of 
records extracted as an array. If the 
selected ODBC provider does not 
support arrays, the batch size is 1. 


BindCharColumnAs Integer (enumeration) This property determines how the 
ODBC source binds columns with 
multiple-byte string types such as 
SQL_CHAR, SQL_VARCHAR, or 
SQL_LONGVARCHAR. 


The possible values are Unicode (0), 
which binds the columns as 
SQL_C_WCHAR, and ANSI (1), which 
binds the columns as SQL_C_CHAR). 
The default is Unicode (0). 


Note: This property is not available in 
the ODBC Source Editor, but can be 
set by using the Advanced Editor. 


PROPERTY NAME 


BindNumericAs 


DefaultCodePage 


ExposeCharColumnsAsUnicode 


FetchMethod 


SqlCommand 


StatementTimeout 


DATA TYPE 


Integer (enumeration) 


Integer 


Boolean 


Integer (enumeration) 


String 


Integer 


DESCRIPTION 


This property determines how the 
ODBC source binds columns with 
numeric data with data types 
SQL_TYPE_NUMERIC and 
SQL_TYPE_DECIMAL. 


The possible options are Char (0), 
which binds the columns as 
SQL_C_CHAR and Numeric (1), which 
binds the columns as 
SQL_C_NUMERIC. The default value is 
Char (0). 


Note: This property is not available in 
the ODBC Source Editor, but can be 
set by using the Advanced Editor. 


The code page to use for string output 
columns. 


Note: This property is not available in 
the ODBC Source Editor, but can be 
set by using the Advanced Editor. 


This property determines how the 
component exposes CHAR columns. 
The default value is False, which 
indicates that CHAR columns are 
exposed as multi-byte strings (DT_STR). 
If True, CHAR columns are exposed as 
wide strings (DT_WSTR). 


Note: This property is not available in 
the ODBC Source Editor, but can be 
set by using the Advanced Editor. 


The method used for getting the data. 
The possible options are Row by row 
(0) and Batch (1). The default value is 
Batch (1). 


For more information about these 
options, see ODBC Source. 


Note: This property is not available in 
the ODBC Source Editor, but can be 
set by using the Advanced Editor. 


The SQL command to be executed 
when AccessMode is set to SQL 
Command. 


The number of seconds to wait for an 
SQL statement to execute before 
returning, with an error, to the 
application. The default value is 0. A 
value of 0 indicates that the system 
does not time out. 


PROPERTY NAME 


TableName 


LobChunckSize 


See Also 


ODBC Source 


DATA TYPE 


String 


Integer 


ODBC Source Editor (Connection Manager Page) 


DESCRIPTION 


The name of the table with the data 
that is being used when AccessMode is 
set to Table Name. 


The chunk size allocation for LOB 
columns. 


OLE DB Source 
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The OLE DB source extracts data from a variety of OLE DB-compliant relational databases by using a database 
table, a view, or an SQL command. For example, the OLE DB source can extract data from tables in Microsoft 
Office Access or SQL Server databases. 


NOTE 


If the data source is Microsoft Office Excel 2007, the data source requires a different connection manager than earlier 


versions of Excel. For more information, see Connect to an Excel Workbook. 











The OLE DB source provides four different data access modes for extracting data: 
e A table or view. 

e A table or view specified in a variable. 

e@ The results of an SQL statement. The query can be a parameterized query. 


e The results of an SQL statement stored in a variable. 


NOTE 


When you use an SQL statement to invoke a stored procedure that returns results from a temporary table, use the WITH 
RESULT SETS option to define metadata for the result set. 





If you use a parameterized query, you can map variables to parameters to specify the values for individual 
parameters in the SQL statements. 


This source uses an OLE DB connection manager to connect to a data source, and the connection manager 
specifies the OLE DB provider to use. For more information, see OLE DB Connection Manager. 


An Integration Services project also provides the data source object from which you can create an OLE DB 
connection manager, making data sources and data source views available to the OLE DB source. 


Depending on the OLE DB provider, some limitations apply to the OLE DB source: 


e The Microsoft OLE DB provider for Oracle does not support the Oracle data types BLOB, CLOB, NCLOB, 
BFILE, OR UROWID, and the OLE DB source cannot extract data from tables that contain columns with 
these data types. 


e The IBM OLE DB DB2 provider and Microsoft OLE DB DB2 provider do not support using an SQL 
command that calls a stored procedure. When this kind of command is used, the OLE DB source cannot 
create the column metadata and, as a result, the data flow components that follow the OLE DB source in 
the data flow have no column data available and the execution of the data flow fails. 


The OLE DB source has one regular output and one error output. 


Using Parameterized SQL Statements 


The OLE DB source can use an SQL statement to extract data. The statement can be a SELECT or an EXEC 
statement. 


The OLE DB source uses an OLE DB connection manager to connect to the data source from which it extracts 
data. Depending on the provider that the OLE DB connection manager uses and the Relational Database 
Management System (RDBMS) that the connection manager connects to, different rules apply to the naming 
and listing of parameters. If the parameter names are returned from the RDBMS, you can use parameter names 
to map parameters in a parameter list to parameters in an SQL statement; otherwise, the parameters are 
mapped to the parameter in the SQL statement by their ordinal position in the parameter list. The types of 
parameter names that are supported vary by provider. For example, some providers require that you use the 
variable or column names, whereas some providers require that you use symbolic names such as 0 or Param0O. 
You should see the provider-specific documentation for information about the parameter names to use in SQL 
statements. 


When you are use an OLE DB connection manager, you cannot use parameterized subqueries, because the OLE 
DB source cannot derive parameter information through the OLE DB provider. However, you can use an 
expression to concatenate the parameter values into the query string and to set the SqiCommand property of 
the source.In SSIS Designer, you configure an OLE DB source by using the OLE DB Source Editor dialog box 
and map the parameters to variables in the Set Query Parameter dialog box. 


Specifying Parameters by Using Ordinal Positions 
If no parameter names are returned, the order in which the parameters are listed in the Parameters list in the 


Set Query Parameter dialog box governs which parameter marker they are mapped to at run time. The first 
parameter in the list maps to the first ? in the SQL statement, the second to the second ?, and so on. 


The following SQL statement selects rows from the Product table in the AdventureWorks2012 database. The 
first parameter in the Mappings list maps to the first parameter to the Color column, the second parameter to 
the Size column. 


SELECT * FROM Production.Product WHERE Color = ? AND Size = ? 


The parameter names have no effect. For example, if a parameter is named the same as the column to which it 
applies, but not put in the correct ordinal position in the Parameters list, the parameter mapping that occurs at 


run time will use the ordinal position of the parameter, not the parameter name. 


The EXEC command typically requires that you use the names of the variables that provide parameter values in 


the procedure as parameter names. 


Specifying Parameters by Using Names 


If the actual parameter names are returned from the RDBMS, the parameters used by a SELECT and EXEC 
statement are mapped by name. The parameter names must match the names that the stored procedure, run by 
the SELECT statement or the EXEC statement, expects. 


The following SQL statement runs the uspGetWhereUsedProductID stored procedure, available in the 
AdventureWorks2012 database. 


EXEC uspGetWhereUsedProductID ?, ? 


The stored procedure expects the variables, @StartProductID and @CheckDate , to provide parameter values. The 
order in which the parameters appear in the Mappings list is irrelevant. The only requirement is that the 


parameter names match the variable names in the stored procedure, including the @ sign. 


Mapping Parameters to Variables 


The parameters are mapped to variables that provide the parameter values at run time. The variables are 
typically user-defined variables, although you can also use the system variables that Integration Services 
provides. If you use user-defined variables, make sure that you set the data type to a type that is compatible with 


the data type of the column that the mapped parameter references. For more information, see Integration 
Services (SSIS) Variables. 


Troubleshooting the OLE DB Source 


You can log the calls that the OLE DB source makes to external data providers. You can use this logging 
capability to troubleshoot the loading of data from external data sources that the OLE DB source performs. To 
log the calls that the OLE DB source makes to external data providers, enable package logging and select the 
Diagnostic event at the package level. For more information, see Troubleshooting Tools for Package Execution. 


Configuring the OLE DB Source 


You can set properties programmatically or through SSIS Designer. 


The Advanced Editor dialog box reflects the properties that can be set programmatically. For more 
information about the properties that you can set in the Advanced Editor dialog box or programmatically, click 
one of the following topics: 


@ Common Properties 


e OLE DB Custom Properties 


Related Tasks 


e Extract Data by Using the OLE DB Source 
e Map Query Parameters to Variables in a Data Flow Component 
e Set the Properties of a Data Flow Component 


e Sort Data for the Merge and Merge Join Transformations 


Related Content 


Wiki article, SSIS with Oracle Connectors, on social.technet.microsoft.com. 


OLE DB Source Editor (Connection Manager Page) 


Use the Connection Manager page of the OLE DB Source Editor dialog box to select the OLE DB connection 
manager for the source. This page also lets you select a table or view from the database. 


NOTE 
To load data from a data source that uses Microsoft Office Excel 2007, use an OLE DB source. You cannot use an Excel 


source to load data from an Excel 2007 data source. For more information, see Configure OLE DB Connection Manager. 


To load data from a data source that uses Microsoft Office Excel 2003 or earlier, use an Excel source. For more information, 


see Excel Source Editor (Connection Manager Page). 








NOTE 


The CommandTimeout property of the OLE DB source is not available in the OLE DB Source Editor, but can be set 
by using the Advanced Editor. For more information on this property, see the Excel Source section of OLE DB Custom 
Properties. 





Open the OLE DB Source Editor (Connection Manager Page) 





1. Add the OLE DB source to the Integration Services package, in SQL Server Data Tools (SSDT). 
2. Right-click the source component and when click Edit. 
3. Click Connection Manager. 


Static Options 


OLE DB connection manager 
Select an existing connection manager from the list, or create a new connection by clicking New. 


New 
Create a new connection manager by using the Configure OLE DB Connection Manager dialog box. 


Data access mode 
Specify the method for selecting data from the source. 


OPTION DESCRIPTION 

Table or view Retrieve data from a table or view in the OLE DB data 
source. 

Table name or view name variable Specify the table or view name in a variable. 


Related information: Use Variables in Packages 


SQL command Retrieve data from the OLE DB data source by using a SQL 
query. 
SQL command from variable Specify the SQL query text in a variable. 
Preview 


Preview results by using the Data View dialog box. Preview can display up to 200 rows. 


NOTE 

When you preview data, columns with a CLR user-defined type do not contain data. Instead the values <value too big to 
display> or System.Byte[] display. The former displays when the data source is accessed using the SQL OLE DB provider, 
the latter when using the SQL Server Native Client provider. 











Data Access Mode Dynamic Options 

Data access mode = Table or view 

Name of the table or the view 

Select the name of the table or view from a list of those available in the data source. 


Data access mode = Table name or view name variable 
Variable name 
Select the variable that contains the name of the table or view. 


Data access mode = SQL command 

SQL command text 

Enter the text of a SQL query, build the query by clicking Build Query, or locate the file that contains the query 
text by clicking Browse. 


Parameters 
If you have entered a parameterized query by using ? as a parameter placeholder in the query text, use the Set 
Query Parameters dialog box to map query input parameters to package variables. 


Build query 
Use the Query Builder dialog box to construct the SQL query visually. 


Browse 
Use the Open dialog box to locate the file that contains the text of the SQL query. 


Parse query 
Verify the syntax of the query text. 


Data access mode = SQL command from variable 


Variable name 
Select the variable that contains the text of the SQL query. 


OLE DB Source Editor (Columns Page) 


Use the Columns page of the OLE DB Source Editor dialog box to map an output column to each external 


(source) column. 


Options 
Available External Columns 


View the list of available external columns in the data source. You cannot use this table to add or delete columns. 


External Column 

View external (source) columns in the order in which you will see them when configuring components that 
consume data from this source. You can change this order by first clearing the selected columns in the table, and 
then selecting external columns from the list in a different order. 


Output Column 

Provide a unique name for each output column. The default is the name of the selected external (source) 
column; however, you can choose any unique, descriptive name. The name provided will be displayed within the 
SSIS Designer. 


OLE DB Source Editor (Error Output Page) 


Use the Error Output page of the OLE DB Source Editor dialog box to select error handling options and to 


set properties on error output columns. 


Options 
Input/Output 


View the name of the data source. 


Column 
View the external (source) columns that you selected on the Connection Manager page of the OLE DB 
Source Editordialog box. 


Error 
Specify what should happen when an error occurs: ignore the failure, redirect the row, or fail the component. 


Related Topics: Error Handling in Data 


Truncation 
Specify what should happen when a truncation occurs: ignore the failure, redirect the row, or fail the component. 


Description 
View the description of the error. 


Set this value to selected cells 
Specify what should happen to all the selected cells when an error or truncation occurs: ignore the failure, 


redirect the row, or fail the component. 


Apply 
Apply the error handling option to the selected cells. 


See Also 


OLE DB Destination 
Integration Services (SSIS) Variables 
Data Flow 


Map Query Parameters to Variables in a Data Flow 


Component 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 
When you configure the OLE DB source to use parameterized queries, you can map the parameters to variables. 
The OLE DB source uses parameterized queries to filter data when the source connects to a data source. 


To map a query parameter to a variable 


1. In SQL Server Data Tools (SSDT), open the Integration Services project that contains the package you 
want. 


2. In Solution Explorer, double-click the package to open it. 
3. Click the Data Flow tab, and then, from the Toolbox, drag the OLE DB source to the design surface. 
4. Right-click the OLE DB source, and then click Edit. 


5. Inthe OLE DB Source Editor, select an OLE DB connection manager to use to connect to the data 
source, or click New to create a new OLE DB connection manager. 


6. Select the SQL command option for data access mode, and then type a parameterized query in the SQL 
command text pane. 


7. Click Parameters. 


8. Inthe Set Query Parameters dialog box, map each parameter in the Parameters list to a variable in 
the Variables list, or create a new variable by clicking <New variable>. Click OK. 





NOTE 


Only system variables and user-defined variables that are in the scope of the package, a parent container such as 
a Foreach Loop, or the Data Flow task that contains the data flow component are available for mapping. The 
variable must have a data type that is compatible with the column in the WHERE clause to which the parameter is 
assigned. 








9. You can click Preview to view up to 200 rows of the data that the query returns. 


10. To save the updated package, click Save Selected Items on the File menu. 


See Also 


OLE DB Source 


Lookup Transformation 


Extract Data by Using the OLE DB Source 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


To add and configure an OLE DB source, the package must already include at least one Data Flow task. 


To extract data using an OLE DB Source 


1. 


10. 


11. 


In SQL Server Data Tools (SSDT), open the Integration Services project that contains the package you 
want. 


. In Solution Explorer, double-click the package to open it. 
. Click the Data Flow tab, and then, from the Toolbox, drag the OLE DB source to the design surface. 
. Double-click the OLE DB source. 


. Inthe OLE DB Source Editor dialog box, on the Connection Manager page, select an existing OLE DB 


connection manager or click New to create a new connection manager. For more information, see OLE 
DB Connection Manager. 


. Select the data access method: 


e Table or view Select a table or view in the database to which the OLE DB connection manager 
connects. 


e Table name or view name variable Select the user-defined variable that contains the name of a 
table or view in the database to which the OLE DB connection manager connects. 


e SQL command Type an SQL command or click Build Query to write an SQL command using 
the Query Builder. 


NOTE 


The command can include parameters. For more information, see Map Query Parameters to Variables in a 


Data Flow Component. 





e SQL command from variable Select the user-defined variable that contains the SQL command. 





NOTE 


The variables must be defined in the scope of the same Data Flow task that contains the OLE DB source, 
or in the scope of the same package; additionally, the variable must have a string data type. 








. To update the mapping between external and output columns, click Columns and select different 


columns in the External Column list. 


. Optionally, update the names of output columns by editing values in the Output Column list. 


. To configure the error output, click Error Output. For more information, see Debugging Data Flow. 


You can click Preview to view up to 200 rows of the data extracted by the OLE DB source. 


Click OK. 





12. To save the updated package, click Save Selected Items on the File menu. 


See Also 


OLE DB Source 

Integration Services Transformations 
Integration Services Paths 

Data Flow Task 


OLE DB Destination 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


The OLE DB destination loads data into a variety of OLE DB-compliant databases using a database table or view 
or an SQL command. For example, the OLE DB source can load data into tables in Microsoft Office Access and 
SQL Server databases. 


NOTE 


If the data source is Microsoft Office Excel 2007, the data source requires a different connection manager than earlier 


versions of Excel. For more information, see Connect to an Excel Workbook. 











The OLE DB destination provides five different data access modes for loading data: 

e A table or view. You can specify an existing table or view, or you create a new table. 

e A table or view using fast-load options. You can specify an existing table or create a new table. 
e A table or view specified in a variable. 

e A table or view specified in a variable using fast-load options. 


e The results of an SQL statement. 





NOTE 


The OLE DB destination does not support parameters. If you need to execute a parameterized INSERT statement, consider 
the OLE DB Command transformation. For more information, see OLE DB Command Transformation. 











When the OLE DB destination loads data that uses a double-byte character set (DBCS), the data may be 
corrupted if the data access mode does not use the fast load option and if the OLE DB connection manager uses 
the Microsoft OLE DB Provider for SQL Server (SQLOLEDB). To ensure the integrity of DBCS data you should 
configure the OLE DB connection manager to use the SQL Server Native Client, or use one of the fast-load 
access modes: Table or view - fast load or Table name or view name variable - fast load. Both options 
are available from the OLE DB Destination Editor dialog box. When programming the SSIS object model, you 
should set the AccessMode property to OpenRowset Using FastLoad, or OpenRowset Using FastLoad 
From Variable. 





NOTE 


If you use the OLE DB Destination Editor dialog box in SSIS Designer to create the destination table into which the 
OLE DB destination inserts data, you may have to select the newly created table manually. The need for manual selection 
occurs when an OLE DB provider, such as the OLE DB provider for DB2, automatically adds schema identifiers to the table 
name. 











NOTE 


The CREATE TABLE statement that the OLE DB Destination Editor dialog box generates may require modification 
depending on the destination type. For example, some destinations do not support the data types that the CREATE TABLE 
statement uses. 








This destination uses an OLE DB connection manager to connect to a data source and the connection manager 
specifies the OLE DB provider to use. For more information, see OLE DB Connection Manager. 


An Integration Services project also provides the data source object from which you can create an OLE DB 
connection manager, to make data sources and data source views available to the OLE DB destination. 


An OLE DB destination includes mappings between input columns and columns in the destination data source. 
You do not have to map input columns to all destination columns, but depending on the properties of the 
destination columns, errors can occur if no input columns are mapped to the destination columns. For example, 
if a destination column does not allow null values, an input column must be mapped to that column. In addition, 
the data types of mapped columns must be compatible. For example, you cannot map an input column with a 
string data type to a destination column with a numeric data type. 


The OLE DB destination has one regular input and one error output. 


For more information about data types, see Integration Services Data Types. 


Fast Load Options 


If the OLE DB destination uses a fast-load data access mode, you can specify the following fast load options in 
the user interface, OLE DB Destination Editor, for the destination: 


e Keep identity values from the imported data file or use unique values assigned by SQL Server. 
e Retain a null value during the bulk load operation. 

e Check constraints on the target table or view during the bulk import operation. 

e Acquire a table-level lock for the duration of the bulk load operation. 

e Specify the number of rows in the batch and the commit size. 


Some fast load options are stored in specific properties of the OLE DB destination. For example, 
FastLoadKeepldentity specifies whether to keep identify values, FastloadKeepNulls specifies whether to keep 
null values, and FastloadMaxInsertCommitSize specifies the number of rows to commit as a batch. Other fast 
load options are stored in a comma-separated list in the FastLoadOptions property. If the OLE DB destination 
uses all the fast load options that are stored in FastLloadOptions and listed in the OLE DB Destination Editor 
dialog box, the value of the property is set to TABLOCK, CHECK_CONSTRAINTS, 
ROWS_PER_BATCH=1000. The value 1000 indicates that the destination is configured to use batches of 1000 
rows. 


NOTE 


Any constraint failure at the destination causes the entire batch of rows defined by FastLoadMaxInsertCommitSize to fail. 





In addition to the fast load options exposed in the OLE DB Destination Editor dialog box,you can configure 
the OLE DB destination to use the following bulk load options by typing the options in FastLoadOptions 
property in the Advanced Editor dialog box. 


FAST LOAD OPTION DESCRIPTION 


KILOBYTES_PER_BATCH Specifies the size in kilobytes to insert. The option has the 
form KILOBYTES_PER_BATCH = <positive integer value>. 


FIRE_TRIGGERS Specifies whether triggers fire on the insert table. The option 
has the form FIRE_TRIGGERS. The presence of the option 
indicates that triggers fire. 


ORDER Specifies how the input data is sorted. The option has the 
form ORDER <column name> ASC|DESC. Any number of 
columns may be listed and it is optional to include the sort 
order. If sort order is omitted, the insert operation assumes 
the data is unsorted. 


Note: Performance can be improved if you use the ORDER 


option to sort the input data according to the clustered 
index on the table. 


The Transact-SQL keywords are traditionally typed using uppercase letters, but the keywords are not case 
sensitive. 


To learn more about fast load options, see BULK INSERT (Transact-SQL). 


Troubleshooting the OLE DB Destination 


You can log the calls that the OLE DB destination makes to external data providers. You can use this logging 
capability to troubleshoot the saving of data to external data sources that the OLE DB destination performs. To 
log the calls that the OLE DB destination makes to external data providers, enable package logging and select 
the Diagnostic event at the package level. For more information, see Troubleshooting Tools for Package 
Execution. 


Configuring the OLE DB Destination 


You can set properties through SSIS Designer or programmatically. 


The Advanced Editor dialog box reflects the properties that can be set programmatically. For more 
information about the properties that you can set in the Advanced Editor dialog box or programmatically, click 
one of the following topics: 


e Common Properties 

e OLE DB Custom Properties 

For more information about how to set properties, click one of the following topics: 
e Load Data by Using the OLE DB Destination 


e Set the Properties of a Data Flow Component 


OLE DB Destination Editor (Connection Manager Page) 


Use the Connection Manager page of the OLE DB Destination Editor dialog box to select the OLE DB 
connection for the destination. This page also lets you select a table or view from the database. 





NOTE 


If the data source is Microsoft Office Excel 2007, the data source requires a different connection manager than earlier 


versions of Excel. For more information, see Connect to an Excel Workbook. 








NOTE 
The CommandTimeout property of the OLE DB destination is not available in the OLE DB Destination Editor, but 


can be set by using the Advanced Editor. In addition, certain fast load options are available only in the Advanced 


Editor. For more information on these properties, see the OLE DB Destination section of OLE DB Custom Properties. 


The CommandTimeout property only takes effective when data access mode is SQL command. 











Static Options 


OLE DB connection manager 


Select an existing connection manager from the list, or create a new connection by clicking New. 


New 
Create a new connection manager by using the Configure OLE DB Connection Manager dialog box. 


Data access mode 

Specify the method for loading data into the destination. Loading double-byte character set (DBCS) data 
requires use of one of the fast load options. For more information about the fast load data access modes, which 
are optimized for bulk inserts, see OLE DB Destination. 


OPTION DESCRIPTION 
Table or view Load data into a table or view in the OLE DB destination. 
Table or view - fast load Load data into a table or view in the OLE DB destination and 


use the fast load option. For more information about the 
fast load data access modes, which are optimized for bulk 
inserts, see OLE DB Destination. 


Table name or view name variable Specify the table or view name in a variable. 


Related information: Use Variables in Packages 


Table name or view name variable - fast load Specify the table or view name in a variable, and use the fast 
load option to load the data. For more information about 
the fast load data access modes, which are optimized for 
bulk inserts, see OLE DB Destination. 


SQL command Load data into the OLE DB destination by using a SQL 
query. 


Preview 


Preview results by using the Preview Query Results dialog box. Preview can display up to 200 rows. 


Data Access Mode Dynamic Options 


Each of the settings for Data access mode displays a dynamic set of options specific to that setting. The 
following sections describe each of the dynamic options available for each Data access mode setting. 


Data access mode = Table or view 


Name of the table or the view 


Select the name of the table or view from a list of those available in the data source. 


New 
Create a new table by using the Create Table dialog box. 


NOTE 


When you click New, Integration Services generates a default CREATE TABLE statement based on the connected data 
source. This default CREATE TABLE statement will not include the FILESTREAM attribute even if the source table includes a 
column with the FILESTREAM attribute declared. To run an Integration Services component with the FILESTREAM 
attribute, first implement FILESTREAM storage on the destination database. Then, add the FILESTREAM attribute to the 
CREATE TABLE statement in the Create Table dialog box. For more information, see Binary Large Object (Blob) Data (SQL 
Server). 





Data access mode = Table or view - fast load 
Name of the table or view 
Select a table or view from the database by using this list, or create a new table by clicking New. 


New 
Create a new table by using the Create Table dialog box. 








NOTE 


When you click New, Integration Services generates a default CREATE TABLE statement based on the connected data 
source. This default CREATE TABLE statement will not include the FILESTREAM attribute even if the source table includes a 
column with the FILESTREAM attribute declared. To run an Integration Services component with the FILESTREAM 
attribute, first implement FILESTREAM storage on the destination database. Then, add the FILESTREAM attribute to the 
CREATE TABLE statement in the Create Table dialog box. For more information, see Binary Large Object (Blob) Data (SQL 


Server). 











Keep identity 
Specify whether to copy identity values when data is loaded. This property is available only with the fast load 
option. The default value of this property is false. 


Keep nulls 
Specify whether to copy null values when data is loaded. This property is available only with the fast load option. 
The default value of this property is false. 


Table lock 
Specify whether the table is locked during the load. The default value of this property is true. 


Check constraints 
Specify whether the destination checks constraints when it loads data. The default value of this property is true. 


Rows per batch 
Specify the number of rows in a batch. The default value of this property is -1, which indicates that no value has 
been assigned. 





NOTE 
Clear the text box in the OLE DB Destination Editor to indicate that you do not want to assign a custom value for this 
property. 











Maximum insert commit size 
Specify the batch size that the OLE DB destination tries to commit during fast load operations. The value of 0 


indicates that all data is committed in a single batch after all rows have been processed. 


NOTE 


A value of 0 might cause the running package to stop responding if the OLE DB destination and another data flow 
component are updating the same source table. To prevent the package from stopping, set the Maximum insert 
commit size option to 2147483647. 











If you provide a value for this property, the destination commits rows in batches that are the smaller of (a) the 
Maximum insert commit size, or (b) the remaining rows in the buffer that is currently being processed. 





NOTE 


Any constraint failure at the destination causes the entire batch of rows defined by Maximum insert commit size to 
fail. 





Data access mode = Table name or view name variable 
Variable name 
Select the variable that contains the name of the table or view. 


Data Access Mode = Table name or view name variable - fast load) 
Variable name 
Select the variable that contains the name of the table or view. 


New 
Create a new table by using the Create Table dialog box. 


NOTE 


When you click New, Integration Services generates a default CREATE TABLE statement based on the connected data 
source. This default CREATE TABLE statement will not include the FILESTREAM attribute even if the source table includes a 
column with the FILESTREAM attribute declared. To run an Integration Services component with the FILESTREAM 
attribute, first implement FILESTREAM storage on the destination database. Then, add the FILESTREAM attribute to the 
CREATE TABLE statement in the Create Table dialog box. For more information, see Binary Large Object (Blob) Data (SQL 


Server). 





Keep identity 
Specify whether to copy identity values when data is loaded. This property is available only with the fast load 
option. The default value of this property is false. 


Keep nulls 
Specify whether to copy null values when data is loaded. This property is available only with the fast load option. 
The default value of this property is false. 


Table lock 
Specify whether the table is locked during the load. The default value of this property is false. 


Check constraints 
Specify whether the task checks constraints. The default value of this property is false. 


Rows per batch 
Specify the number of rows in a batch. The default value of this property is -1, which indicates that no value has 
been assigned. 











NOTE 
Clear the text box in the OLE DB Destination Editor to indicate that you do not want to assign a custom value for this 


property. 











Maximum insert commit size 
Specify the batch size that the OLE DB destination tries to commit during fast load operations. The default value 
of 2147483647 indicates that all data is committed in a single batch after all rows have been processed. 


NOTE 

A value of 0 might cause the running package to stop responding if the OLE DB destination and another data flow 
component are updating the same source table. To prevent the package from stopping, set the Maximum insert 
commit size option to 2147483647. 





Data access mode = SQL command 

SQL command text 

Enter the text of a SQL query, build the query by clicking Build Query, or locate the file that contains the query 
text by clicking Browse. 








NOTE 


The OLE DB destination does not support parameters. If you need to execute a parameterized INSERT statement, consider 


the OLE DB Command transformation. For more information, see OLE DB Command Transformation. 











Build query 
Use the Query Builder dialog box to construct the SQL query visually. 


Browse 
Use the Open dialog box to locate the file that contains the text of the SQL query. 


Parse query 
Verify the syntax of the query text. 


OLE DB Destination Editor (Mappings Page) 


Use the Mappings page of the OLE DB Destination Editor dialog box to map input columns to destination 


columns. 


Options 

Available Input Columns 

View the list of available input columns. Use a drag-and-drop operation to map available input columns in the 
table to destination columns. 


Available Destination Columns 
View the list of available destination columns. Use a drag-and-drop operation to map available destination 
columns in the table to input columns. 


Input Column 
View the input columns that you selected. You can remove mappings by selecting <ignore> to exclude 
columns from the output. 


Destination Column 
View each available destination column, regardless of whether it is mapped or not. 


OLE DB Destination Editor (Error Output Page) 


Use the Error Output page of the OLE DB Destination Editor dialog box to specify error handling options. 


Options 
Input/Output 
View the name of the input. 


Column 
Not used. 


Error 
Specify what should happen when an error occurs: ignore the failure, redirect the row, or fail the component. 


Related Topics: Error Handling in Data 


Truncation 
Not used. 


Description 
View the description of the operation. 


Set this value to selected cells 
Specify what should happen to all the selected cells when an error or truncation occurs: ignore the failure, 
redirect the row, or fail the component. 


Apply 


Apply the error handling option to the selected cells. 


Related Content 


OLE DB Source 
Integration Services (SSIS) Variables 


Data Flow 


Load Data by Using the OLE DB Destination 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


To add and configure an OLE DB destination, the package must already include at least one Data Flow task and a 
source. 


To load data using an OLE DB destination 


1. In SQL Server Data Tools (SSDT), open the Integration Services project that contains the package you 
want. 


2. In Solution Explorer, double-click the package to open it. 
3. Click the Data Flow tab, and then, from the Toolbox, drag the OLE DB destination to the design surface. 


4. Connect the OLE DB destination to the data flow by dragging a connector from a data source or a 
previous transformation to the destination. 


5. Double-click the OLE DB destination. 


6. In the OLE DB Destination Editor dialog box, on the Connection Manager page, select an existing 
OLE DB connection manager or click New to create a new connection manager. For more information, 
see OLE DB Connection Manager. 


7. Select the data access method: 
e Table or view Select a table or view in the database that contains the data. 


e Table or view - fast load Select a table or view in the database that contains the data, and then 
set the fast-load options: Keep identity, Keep null, Table lock, Check constraint, Rows per 
batch, or Maximum insert commit size. 


e Table name or view name variable Select the user-defined variable that contains the name of a 
table or view in the database. 


e Table name or view name variable fast load Select the user-defined variable that contains the 
name of a table or view in the database that contains the data, and then set the fast-load options. 


e SQL command Type an SQL command or click Build Query to write an SQL command by using 
the Query Builder. 


8. Click Mappings and then map columns from the Available Input Columns list to columns in the 
Available Destination Columns list by dragging columns from one list to another. 





NOTE 


The OLE DB destination automatically maps same-named columns. 








9. To configure the error output, click Error Output. For more information, see Debugging Data Flow. 
10. Click OK. 


11. To save the updated package, click Save Selected Items on the File menu. 


See Also 


OLE DB Destination 

Integration Services Transformations 
Integration Services Paths 

Data Flow Task 


OLE DB Custom Properties 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 
Source Custom Properties 
The OLE DB source has both custom properties and the properties common to all data flow components. 


The following table describes the custom properties of the OLE DB source. All properties are read/write. 


PROPERTY NAME DATA TYPE DESCRIPTION 


AccessMode Integer The mode used to access the database. 
The possible values are Open Rowset, 
Open Rowset from Variable, SQL 
Command, and SQL Command 
from Variable. The default value is 
Open Rowset. 


AlwaysUseDefaultCodePage Boolean A value that indicates whether to use 
the value of the DefaultCodePage 
property for each column, or to try to 
derive the codepage from each 
column's locale. The default value of 
this property is False. 


CommandTimeout Integer The number of seconds before a 
command times out. A value of 0 
indicates an infinite time-out. 


Note: 

This property only takes effective when 
data access mode is SQL command. 
This property is not available in the 
OLE DB Source Editor, but can be 
set by using the Advanced Editor. 


DefaultCodePage Integer The code page to use when code page 
information is unavailable from the 
data source. 


OpenRowset String The name of the database object that 
is used to open a rowset. 


OpenRowsetVariable String The variable that contains the name of 
the database object that is used to 
open a rowset. 


ParameterMapping String The mapping from parameters in the 
SQL command to variables. 


SqlCommand String The SQL command to be executed. 


PROPERTY NAME 


SqlCommandVariable 


DATA TYPE 


String 


DESCRIPTION 


The variable that contains the SQL 
command to be executed. 


The output and the output columns of the OLE DB source have no custom properties. 


For more information, see OLE DB Source. 


Destination Custom Properties 


The OLE DB destination has both custom properties and the properties common to all data flow components. 


The following table describes the custom properties of the OLE DB destination. All properties are read/write. 





NOTE 





The FastLoad options listed here (FastLoadKeepldentity, FastLoadKeepNulls, and FastLoadOptions) correspond to the 
similarly named properties exposed by the |RowsetFastLoad interface implemented by the Microsoft OLE DB Provider 
for SQL Server (SQLOLEDB). For more information, search for |RowsetFastLoad in the MSDN Library. 





PROPERTY NAME 


AccessMode 


AlwaysUseDefaultCodePage 


DATA TYPE 


Integer (enumeration) 


Boolean 


DESCRIPTION 


A value that specifies how the 
destination access its destination 
database. 


This property can have one of the 
following values: 


OpenRowset (0)-You provide the 
name of a table or view. 


OpenRowset from Variable (1)-You 
provide the name of a variable that 
contains the name of a table or view. 


OpenRowset Using Fastload (3)- 
You provide the name of a table or 
view. 


OpenRowset Using Fastload from 
Variable (4)-You provide the name of 
a variable that contains the name of a 
table or view. 


SQL Command (2)-You provide a 
SQL statement. 


A value that indicates whether to use 
the value of the DefaultCodePage 
property for each column, or to try to 
derive the codepage from each 
column's locale. The default value of 
this property is False. 





PROPERTY NAME 


CommandTimeout 


DefaultCodePage 


FastLoadKeepldentity 


FastLoadKeepNulls 


FastLoadMaxInsertCommitSize 


FastLoadOptions 


OpenRowset 


DATA TYPE 


Integer 


Integer 


Boolean 


Boolean 


Integer 


String 


String 


DESCRIPTION 


The maximum number of seconds that 
the SQL command can run before 
timing out. A value of 0 indicates an 
infinite time. The default value of this 
property is 0. 


Note: This property is not available in 
the OLE DB Destination Editor, but 
can be set by using the Advanced 
Editor. 


The default codepage associated with 
the OLE DB destination. 


A value that specifies whether to copy 
identity values when data is loaded. 
This property is available only with one 
of the fast load options. The default 
value of this property is False. This 
property corresponds to the OLE DB 
|RowsetFastLoad (OLE DB) property 
SSPROP_FASTLOADKEEPIDENTITY. 


A value that specifies whether to copy 
Null values when data is loaded. This 
property is available only with one of 
the fast load options. The default value 
of this property is False. This property 
corresponds to the OLE DB 
|RowsetFastLoad (OLE DB) property 
SSPROP_FASTLOADKEEPNULLS. 


A value that specifies the batch size 
that the OLE DB destination tries to 
commit during fast load operations. 
The default value, 0, indicates a single 
commit operation after all rows are 
processed. 


A collection of fast load options. The 
fast load options include the locking of 
tables and the checking of constraints. 
You can specify one, both, or neither. 
This property corresponds to the OLE 
DB |RowsetFastLoad property 
SSPROP_FASTLOADOPTIONS and 
accepts string options such as 
CHECK_CONSTRAINTS and 
TABLOCK. 


Note: Some options for this property 
are not available in the Excel 
Destination Editor, but can be set 
by using the Advanced Editor. 


When AccessMode is OpenRowset, 
the name of the table or view that the 
OLE DB destination accesses. 


PROPERTY NAME DATA TYPE DESCRIPTION 


OpenRowsetVariable String When AccessMode is OpenRowset 
from Variable, the name of the 
variable that contains the name of the 
table or view that the OLE DB 
destination accesses. 


SqlCommand String When AccessMode is SQL 
Command, the Transact-SQL 
statement that the OLE DB destination 
uses to specify the destination 
columns for the data. 


The input and the input columns of the OLE DB destination have no custom properties. 


For more information, see OLE DB Destination. 


See Also 


Common Properties 


Partition Processing Destination 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


The Partition Processing destination loads and processes an SQL Server Analysis Services partition. For more 
information about partitions, see Partitions (Analysis Services - Multidimensional Data). 


The Partition Processing destination includes the following features: 
e Options to perform incremental, full, or update processing. 


e Error configuration, to specify whether processing ignores errors or stops after a specified number of 
errors. 


e Mapping of input columns to partition columns. 


For more information about processing Analysis Services objects, see Processing Options and Settings (Analysis 
Services). 





NOTE 

Tasks described here do not apply to Analysis Services tabular models. You cannot map input columns to partition 
columns for tabular models. You can instead use the Analysis Services Execute DDL task Analysis Services Execute DDL 
Task to process the partition. 





Configuration of the Partition Processing Destination 


The Partition Processing destination uses an Analysis Services connection manager to connect to the Analysis 
Services project or the instance of Analysis Services that contains the cubes and partitions the destination 


processes. For more information, see Analysis Services Connection Manager. 
This destination has one input. It does not support an error output. 
You can set properties through SSIS Designer or programmatically. 


The Advanced Editor dialog box reflects the properties that can be set programmatically. For more 
information about the properties that you can set in the Advanced Editor dialog box or programmatically, click 
one of the following topics: 


e Common Properties 
e Partition Processing Destination Custom Properties 


For more information about how to set the properties, see Set the Properties of a Data Flow Component. 


Partition Processing Destination Editor (Connection Manager Page) 


Use the Connection Manager page of the Partition Processing Destination Editor dialog box to specify a 
connection to a SQL Server Analysis Services project or to an instance of Analysis Services. 








NOTE 


Tasks described here do not apply to Analysis Services tabular models. You cannot map input columns to partition 
columns for tabular models. You can instead use the Analysis Services Execute DDL task Analysis Services Execute DDL 


Task to process the partition. 





Options 
Connection manager 


Select an existing connection manager from the list, or create a new connection by clicking New. 


New 
Create a new connection by using the Add Analysis Services Connection Manager dialog box. 


List of available partitions 
Select the partition to process. 


Processing method 
Select the processing method. The default value of this option is Full. 


VALUE DESCRIPTION 

Add (incremental) Perform an incremental processing of the partition. 
Full Perform full processing of the partition. 

Data only Perform an update processing of the partition. 


Partition Processing Destination Editor (Mappings Page) 


Use the Mappings page of the Partition Processing Destination Editor dialog box to map input columns to 
partition columns. 


NOTE 


Tasks described here do not apply to Analysis Services tabular models. You cannot map input columns to partition 
columns for tabular models. You can instead use the Analysis Services Execute DDL task Analysis Services Execute DDL 
Task to process the partition. 














Options 

Available Input Columns 

View the list of available input columns. Use a drag-and-drop operation to map available input columns in the 
table to destination columns. 


Available Destination Columns 
View the list of available destination columns. Use a drag-and-drop operation to map available destination 
columns in the table to input columns. 


Input Column 
View input columns selected from the table above. You can change the mappings by using the list of Available 
Input Columns. 


Destination Column 
View each available destination column, whether it is mapped or not. 


Partition Processing Destination Editor (Advanced Page) 


Use the Advanced page of the Partition Processing Destination Editor dialog box to configure error 
handling. 





NOTE 
Tasks described here do not apply to Analysis Services tabular models. You cannot map input columns to partition 
columns for tabular models. You can instead use the Analysis Services Execute DDL task Analysis Services Execute DDL 


Task to process the partition. 





Options 
Use default error configuration. 
Specify whether to use the default Analysis Services error handling. By default, this value is True. 


Key error action 
Specify how to handle records that have unacceptable key values. 


VALUE DESCRIPTION 
ConvertToUnknown Convert the unacceptable key value to the Unknown value. 
DiscardRecord Discard the record. 


Ignore errors 
Specify that errors should be ignored. 


Stop on error 
Specify that processing should stop when an error occurs. 


Number of errors 
Specify the error threshold at which processing should stop, if you have selected Stop on error. 


On error action 
Specify the action to take when the error threshold is reached, if you have selected Stop on error. 


VALUE DESCRIPTION 
StopProcessing Stop processing. 
StopLogging Stop logging errors. 


Key not found 
Specify the action to take for a key not found error. By default, this value is ReportAndContinue. 


VALUE DESCRIPTION 

IgnoreError Ignore the error and continue processing. 
ReportAndContinue Report the error and continue processing. 
ReportAndStop Report the error and stop processing. 


Duplicate key 
Specify the action to take for a duplicate key error. By default, this value is IgnoreError. 





VALUE DESCRIPTION 


IgnoreError Ignore the error and continue processing. 
ReportAndContinue Report the error and continue processing. 
ReportAndStop Report the error and stop processing. 


Null key converted to unknown 


Specify the action to take when a null key has been converted to the Unknown value. By default, this value is 
IgnoreError. 


VALUE DESCRIPTION 

IgnoreError Ignore the error and continue processing. 
ReportAndContinue Report the error and continue processing. 
ReportAndStop Report the error and stop processing. 


Null key not allowed 
Specify the action to take when null keys are not allowed and a null key is encountered. By default, this value is 
ReportAndContinue. 


VALUE DESCRIPTION 

IgnoreError Ignore the error and continue processing. 
ReportAndContinue Report the error and continue processing. 
ReportAndStop Report the error and stop processing. 


Error log path 
Type the path for the error log, or select a destination by using the browse (...) button. 


Browse (...) 
Select a path for the error log. 


See Also 


Integration Services Error and Message Reference 


Partition Processing Destination Custom Properties 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


The Partition Processing destination has both custom properties and the properties common to all data flow 


components. 


The following table describes the custom properties of the Partition Processing destination. All properties are 


read/write. 


PROPERTY 


ASConnectionString 


KeyDuplicate 


KeyErrorAction 


KeyErrorLimit 


KeyErrorLimitAction 


KeyErrorLogFile 


DATA TYPE 


String 


Integer (enumeration) 


Integer (enumeration) 


Integer 


Integer (enumeration) 


String 


DESCRIPTION 


The connection string to an Analysis 
Services project or an instance of 
Analysis Services. 


When UseDefaultConfiguration is 
False, a value that indicates how to 
handle duplicate key errors. The 
possible values are |gnoreError (0), 
ReportAndContinue (1), and 
ReportAndsStop (2). The default value 
of this property is IgnoreError (0). 


When UseDefaultConfiguration is 
False, a value that indicates how to 
handle key errors. The possible values 
are ConvertToUnknown (0) and 
DiscardRecord (1). The default value 
of this property is 
ConvertToUnknown (0). 


When UseDefaultConfiguration is 
False, the upper limit of key errors 
that are allowed. 


When UseDefaultConfiguration is 
False, a value that indicates the action 
to take when KeyErrorLimit is 
reached. The possible values are 
StopLogging (1) and 
StopProcessing (0). The default value 
of this property is StopProcessing 
(0). 


When UseDefaultConfiguration is 
False, the path and file name of the 
error log file. 


PROPERTY 


KeyNotFound 


NullkeyConvertedToUnknown 


NullkeyNotAllowed 


ProcessType 


UseDefaultConfiguration 


DATA TYPE 


Integer (enumeration) 


Integer (enumeration) 


Integer (enumeration) 


Integer (enumeration) 


Boolean 


DESCRIPTION 


When UseDefaultConfiguration is 
False, a value that indicates how to 
handle missing key errors. The possible 
values are IgnoreError (0), 
ReportAndContinue (1), and 
ReportAndStop (2). The default value 
of this property is 
ReportAndContinue (1). 


When UseDefaultConfiguration is 
False, a value that indicates how to 
handle null keys converted to the 
Unknown value. The possible values 
are IgnoreError (0), 
ReportAndContinue (1), and 
ReportAndStop (2). The default value 
of this property is IgnoreError (0). 


When UseDefaultConfiguration is 
False, a value that indicates how to 
handle disallowed nulls. The possible 
values are IgnoreError (0), 
ReportAndContinue (1), and 
ReportAndStop (2). The default value 
of this property is 
ReportAndContinue (1). 


The type of partition processing the 
transformation uses. The possible 
values are ProcessAdd (1) 
(incremental), ProcessFull (0), and 
ProcessUpdate (2). 


A value that specifies whether the 
transformation uses the default error 
configuration. If this property is False, 
the transformation uses the values of 
the error-handling custom properties 
listed in this table, including 
KeyDuplicate, KeyErrorAction, and so 
on. 


The input and the input columns of the Partition Processing destination have no custom properties. 


For more information, see Partition Processing Destination. 


See Also 


Common Properties 


Power Query Source (Preview) 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


This article describes how to configure the properties of the Power Query Source in the SQL Server Integration 
Services (SSIS) data flow. Power Query is a technology that allows you to connect to various data sources and 
transform data using Excel/Power BI Desktop. For more info, see Power Query - Overview and Learning article. 
The script generated by Power Query can be copied & pasted into the Power Query Source in the SSIS data flow 
to configure it. 


NOTE 


For the current preview release, Power Query Source can only be used on SQL Server 2017/2019 and Azure-SSIS 
Integration Runtime (IR) in Azure Data Factory (ADF). You can download and install the latest Power Query Source for SQL 
Server 2017/2019 from here. Power Query Source for Azure-SSIS IR is already preinstalled. To provision Azure-SSIS IR, see 
Provision SSIS in ADF article. 











Configure the Power Query Source 


To open Power Query Source Editor in SSDT, drag & drop Power Query Source from SSIS Toolbox onto 
the data flow designer and double-click on it. 


PQ + Power Query Source €3 





Three tabs are shown on the left side. On Queries tab, you can select your query mode from the dropdown 
menu. 


e Single Query mode allows you to copy & paste a single Power Query script from Excel/Power BI Desktop. 


e Single Query from Variable mode allows you to specify a string variable that contains your query to be 
executed. 


Bi Power Query Source Editor o x 


Configure the properties used to obtain data from Power Query. 


Queries Specify the query mode and query text. If using the Single Query from Variable mode, specify the variable name 
. which contains the query text. 
Connection Managers 
Columns 
Query Mode 
Single Query ¥ 
Single Query Text 

















| A The property ‘SingleQueryText' is not set. 


OK Cancel Help 


On Connection Managers tab, you can add or remove Power Query connection managers that contain data 
source access credentials. Selecting the Detect Data Source button identifies the referenced data sources in 
your query and lists them for you to assign the appropriate existing Power Query connection managers or 


create new ones. 


Configure the properties used to obtain data from Power Query. 


f Queries Specify the Power Query connection managers for each data source that the Power Query source uses. 
Connection Managers 
Columns 
Power Query Connection Managers 
Name Description Connection Manager 


© Successfully detect 1 data sources referenced by the query. 


Add more connection managers if necessary. 








OK Cancel Help 


Configure the properties used to obtain data from Power Query. 


f Queries Specify the Power Query connection managers for each data source that the Power Query source uses. 
Connection Managers 
Columns 
Power Query Connection Managers 
Name Description Connection Manager 
‘SOLcometion SQ absenindows. (| 
_<New connection...» __| 





wt || toe 


OK Cancel Help 


Finally, on Columns tab, you can edit the output column info. 


Bi Power Query Source Editor Oo x 


Configure the properties used to obtain data from Power Query. 






Available External ... 





External Column Output Column 
[propery.name | property name 
property_value property_value 








[a [eet [oe 


Configure the Power Query Connection Manager 


When designing your data flow with Power Query Source on SSDT, you can create a new Power Query 
Connection Manager in the following ways: 


e Indirectly create iton Connection Managers tab of Power Query Source after selecting Add/Detect Data 


Source button and selecting <New connection...> from the dropdown menu as described above. 


e Directly create it by right-clicking on Connection Managers panel of your package and selecting New 


Connection... from the dropdown menu. 





Work Offline 
New OLE DB Connection... 


New Flat File Connection... 

New ADO.NET Connection... 

New Analysis Services Connection... 
New File Connection... 

New Connection... 

Cut 

Copy 

Paste 


Delete 





Rename 


# Properties 


Ctrl+X 
Ctrl+C 
Ctrl+V 
Del 


Alt+Enter 


In Add SSIS Connection Manager dialog, double-click on PowerQuery from the list of connection manager 


types. 




















¥ Add SSIS Connection Manager Oo x 
Select the type of connection manager to add to the package. 
Connection manager type: 

Type Description File Na... Filev * 
Hadoop Connection manager for Hadoop Micros... 14.10 
HTTP Connection manager for HTTP connections C:\Pro... 15.0.¢ 
MSMQ Connection manager for the Message Queuet... Micros... 14.10 
MSOLAP 100 Connection manager for Analysis Services con... C:\Pro... 15.0.6 
MULTIFILE Connection manager for multiple files C:\Pro... 15.0. 
MULTIFLATFILE Connection manager for multiple flat files C:\Pro... 15.0.5 
ODATA Connection Manager for OData services Micros... 14.10 
ODBC Connection manager for ODBC connections C:\Pro... 15.0.5 
OLEDB Connection manager for OLE DB connections C:\Pro... 15.0.5 

; Query ‘ ection Manager for Power Query Source s 14.1 
SMOServer Connection manager for SQL Server transfer ta... Micros... 14.10 
SMTP Connection manager for the Send Mail task Micros... 14.10 
SQLMOBILE Connection manager for SQL Server Compact... C:\Pro... 15.0.4 
WMI Connection manager for the WMI tasks Micros... 14.10 

v 

< > 


In Power Query Connection Manager Editor, you need to specify Data Source Kind, Data Source Path, 


and Authentication Kind, as well as assign the appropriate access credentials. For Data Source Kind, you can 


currently select one of 22 kinds from the dropdown menu. 


Bl Power Query Connection Manager Editor o x 
Data Source Kind 
Data Source Path Edit 
Authentication Kind 
Test Connection Help 





Some of these sources (Oracle, DB2, MySQL, PostgreSQL, Teradata, Sybase) require additional installations 
of ADO.NET drivers that can be obtained from Power Query Prerequisites article. You can use the custom setup 
interface to install them on your Azure-SSIS IR, see Customizing Azure-SSIS IR article. 


For Data Source Path, you can enter data source-specific properties forming a connection string without the 
authentication info. For example, the path for SQL data source is formed as <Server>;<Database> . You can select 
the Edit button to assign values to data source-specific properties forming the path. 

( Gl Data Source Path Editor Oo x 


Data Source Kind: SQL 


Data Source Properties 





Finally, For Authentication Kind, you can select AnNonymous/Windows Authentication/Username 
Password/Key from the dropdown menu, enter the appropriate access credentials, and select the Test 
Connection button to ensure that Power Query Source has been properly configured. 


Bi Power Query Connection Manager Editor oO x 


Data Source Kind SQL ¥ 





Data Source Path | | Edt 

















Test Connection OK Cancel Help 


Current limitations 


e Oracle data source can not currently be used on Azure-SSIS IR, because Oracle ADO.NET driver can not 
be installed there, so please install Oracle ODBC driver instead and use ODBC data source to connect to 
Oracle for now, see ORACLE STANDARD ODBC example in Customizing Azure-SSIS IR article. 


e Web data source can not currently be used on Azure-SSIS IR with custom setups, so please use it on 
Azure-SSIS IR without custom setups for now. 


Next steps 


Learn how to run SSIS packages in the Azure-SSIS IR as first-class activities in ADF pipelines. See Execute SSIS 


Package activity Runtime article. 


Raw File Source 
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Applies to: Q sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


The Raw File source reads raw data from a file. Because the representation of the data is native to the source, the 
data requires no translation and almost no parsing. This means that the Raw File source can read data more 
quickly than other sources such as the Flat File and the OLE DB sources. 


The Raw File source is used to retrieve raw data that was previously written by the Raw File destination. You can 
also point the Raw File source to an empty raw file that contains only the columns (metadata-only file). You use 
the Raw File destination to generate the metadata-only file without having to run the package. For more 
information, see Raw File Destination. 


The raw file format contains sort information. The Raw File Destination saves all the sort information including 
the comparison flags for string columns. The Raw File source reads and honors the sort information. You do 
have the option of configuring the Raw File Source to ignore the sort flags in the file, using the Advanced Editor. 
For more information about comparison flags, see Comparing String Data. 


You configure the Raw File by specifying the name of the name of the file that the Raw File source reads. 





NOTE 


This source does not use a connection manager. 





This source has one output. It does not support an error output. 


Configuration of the Raw File Source 


You can set properties through SSIS Designer or programmatically. 


The Advanced Editor dialog box reflects the properties that can be set programmatically. For more 
information about the properties that you can set in the Advanced Editor dialog box or programmatically, click 
one of the following topics: 


e Common Properties 


e Raw File Custom Properties 


Related Tasks 


For information about how to set the properties of the component, see Set the Properties of a Data Flow 
Component. 


Related Content 


e Blog entry, Raw Files Are Awesome, on sqlservercentral.com 


Raw File Source Editor (Connection Manager Page) 


The Raw File source reads raw data from a file. Because the representation of the data is native to the source, the 
data requires no translation and almost no parsing. 


Raw File Source Editor (Columns Page) 


The Raw File source reads raw data from a file. Because the representation of the data is native to the source, the 


data requires no translation and almost no parsing. 


See Also 


Raw File Destination 
Data Flow 


Raw File Destination 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


The Raw File destination writes raw data to a file. Because the format of the data is native to the destination, the 
data requires no translation and little parsing. This means that the Raw File destination can write data more 
quickly than other destinations such as the Flat File and the OLE DB destinations. 


In addition to writing raw data to a file, you can also use the Raw File destination to generate an empty raw file 
that contains only the columns (metadata-only file), without having to run the package. You use the Raw File 
source to retrieve raw data that was previously written by the destination. You can also point the Raw File source 
to the metadata-only file. 


The raw file format contains sort information. The Raw File Destination saves all the sort information including 
the comparison flags for string columns. The Raw File source reads and honors the sort information. You do 
have the option of configuring the Raw File Source to ignore the sort flags in the file, using the Advanced Editor. 
For more information about comparison flags, see Comparing String Data. 


You can configure the Raw File destination in the following ways: 


e Specify an access mode which is either the name of the file or a variable that contains the name of the file 
to which the Raw File destination writes. 


e Indicate whether the Raw File destination appends data to an existing file that has the same name or 
creates a new file. 


The Raw File destination is frequently used to write intermediary results of partly processed data between 
package executions. Storing raw data means that the data can be read quickly by a Raw File source and then 
further transformed before it is loaded into its final destination. For example, a package might run several times, 
and each time write raw data to files. Later, a different package can use the Raw File source to read from each 
file, use a Union All transformation to merge the data into one data set, and then apply additional 
transformations that summarize the data before loading the data into its final destination such as a SQL Server 
table. 





NOTE 
The Raw File destination supports null data but not binary large object (BLOB) data. 


NOTE 


The Raw File destination does not use a connection manager. 








This source has one regular input. It does not support an error output. 


Append and New File Options 
The WriteOption property includes options to append data to an existing file or create a new file. 


The following table describes the available options for the WriteOption property. 


OPTION DESCRIPTION 


Append Appends data to an existing file. The metadata of the 
appended data must match the file format. 


Create always Always creates a new file. 

Create once Creates a new file. If the file exists, the component fails. 

Truncate and append Truncates an existing file and then writes the data to the file. 
The metadata of the appended data must match the file 
format. 


The following are important items about appending data: 
e Appending data to an existing raw file does not re-sort the data. 
You need to make certain that the sorted keys remain in the correct order. 
e Appending data to an existing raw file does not change the file metadata (sort information). 


For example, a package reads data sorted on the ProductKey (PK). The package data flow appends the data to an 
existing raw file. The first time the package runs, three rows are received (PK 1000, 1100, 1200). The raw file 


now contains the following data. 
e 1000, productA 
e 1100, productB 
e 1200, productC 


The second time the package runs, two new rows are received (PK 1001, 1300). The raw file now contains the 


following data. 

e 1000, productA 
e 1100, productB 
e 1200, productC 
e 1001, productD 
e 1300, productE 


The new data is appended to the end of the raw file, and the sorted keys (PK) are out of order. In addition, the 
append operation didn't change the file metadata (sort information). If you read the file by using the Raw File 
source, the component indicates that the file is still sorted on PK even though the data in the file is no longer in 
the correct order. 


To keep the sorted keys in the correct order while appending data, you can design the package data flow as 


follows: 

1. Retrieve new rows by using Source A. 

2. Retrieve existing rows from RawFile1 using Source B. 

3. Combine the inputs from Source A and Source B by using the Union All transformation. 
4. Sort on PK. 


5. Write to RawFile2 by using the Raw File destination. 


RawFile1 is locked because it's being read from, in the data flow. 
6. Replace RawFile1 with RawFile2. 


Using the Raw File Destination in a Loop 


If the data flow that uses the Raw File destination is in a loop, you may want to create the file once and then 
append data to the file when the loop repeats. To append data to the file, the data that is appended must match 
the format of the existing file. 


To create the file in the first iteration of the loop, and then append rows in the subsequent iterations of the loop, 
you need to do the following at design time: 


1. Set the WriteOption property to CreateOnce or CreateAlwaysand run one iteration of the loop. The file 
is created. This ensures that the metadata of appended data and the file matches. 


2. Reset the WriteOption property to Append and set the ValidateExternalMetadata property to False. 


If you use the TruncateAppend option instead of the Append option, it will truncate rows that were added in 
any previous Iteration, and then append new rows. Using the TruncateAppend option also requires that the 
data matches the file format. 


Configuration of the Raw File Destination 
You can set properties through SSIS Designer or programmatically. 


The Advanced Editor dialog box reflects the properties that can be set programmatically. For more 
information about the properties that you can set in the Advanced Editor dialog box or programmatically, click 
one of the following topics: 


@ Common Properties 


e Raw File Custom Properties 


Related Tasks 


For information about how to set properties of the component, see Set the Properties of a Data Flow 
Component. 


Related Content 


Blog entry, Raw Files Are Awesome, on sqlservercentral.com. 


Raw File Destination Editor (Connection Manager Page) 


Use the Raw File Destination Editor to configure the Raw File destination to write raw data to a file. 
What do you want to do? 

e@ Open the Raw File Destination Editor 

e@ Set options on the Connection Manager tab 

e Set options on the Columns tab 


Open the Raw File Destination Editor 


1. Add the Raw File destination to an Integration Services package, in SQL Server Data Tools (SSDT). 


2. Right-click the component and then click Edit. 


Set options on the Connection Manager tab 


Access mode 
Select how the file name is specified. Select File name to enter the file name and path directly, of File name 
from variable to specify a variable that contains the file name. 


File name or Variable name 
Enter the name and path of the raw file, or select the variable that contains the file name. 


Write option 
Select the method used to create and write to the file. 


Generate initial raw file 

Click the button to generate an empty raw file that contains only the columns (metadata-only file), without 
having to run the package. The file contains the columns that you selected on the Columns page of the Raw 
File Destination Editor. You can point the Raw File source to this metadata-only file. 


When you click Generate initial raw file, a message box appears. Click OK to proceed with creating the file. 
Click Cancel to select a different list of columns on the Columns page. 


Set options on the Columns tab 


Available Input Columns 
Select one or more input columns to write to the raw file. 


Input Column 
An input column is automatically added to this table when you select it under Available Input Columns, or 
you can select the input column directly in this table. 


Output Alias 
Specify an alternate name to use for the output column. 


Raw File Destination Editor (Columns Page) 

Use the Raw File Destination Editor to configure the Raw File destination to write raw data to a file. 
What do you want to do? 

e Open the Raw File Destination Editor 

e Set options on the Connection Manager tab 

e@ Set options on the Columns tab 


Open the Raw File Destination Editor 
1. Add the Raw File destination to an Integration Services package, in SQL Server Data Tools (SSDT). 


2. Right-click the component and then click Edit. 


Set options on the Connection Manager tab 


Access mode 
Select how the file name is specified. Select File name to enter the file name and path directly, of File name 
from variable to specify a variable that contains the file name. 


File name or Variable name 
Enter the name and path of the raw file, or select the variable that contains the file name. 


Write option 
Select the method used to create and write to the file. 


Generate initial raw file 


Click the button to generate an empty raw file that contains only the columns (metadata-only file), without 
having to run the package. You can point the Raw File source to the metadata-only file. 


When you click the button, a list of the columns appears. You can click cancel and modify the columns or click 
OK to proceed with creating the file. 


Set options on the Columns tab 


Available Input Columns 
Select one or more input columns to write to the raw file. 


Input Column 
An input column is automatically added to this table when you select it under Available Input Columns, or 
you can select the input column directly in this table. 


Output Alias 
Specify an alternate name to use for the output column. 


See Also 


Raw File Source 
Data Flow 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 
Source Custom Properties 
The Raw File source has both custom properties and the properties common to all data flow components. 


The following table describes the custom properties of the Raw File source. All properties are read/write. 


PROPERTY NAME DATA TYPE DESCRIPTION 


AccessMode Integer (enumeration) The mode used to access the raw data. 
The possible values are File name (0) 
and File name from variable (1). 
The default value is File name (0). 


FileName String The path and file name of the source 
file. 


The output and the output columns of the Raw File source have no custom properties. 

For more information, see Raw File Source. 

Destination Custom Properties 

The Raw File destination has both custom properties and the properties common to all data flow components. 


The following table describes the custom properties of the Raw File destination. All properties are read/write. 


PROPERTY NAME DATA TYPE DESCRIPTION 


AccessMode Integer (enumeration) A value that specifies whether the 
FileName property contains a file 
name, or the name of a variable that 
contains a file name. The options are 
File name (0) and File name from 
variable (1). 


FileName String The name of the file to which the Raw 
File destination writes. 


WriteOption Integer (enumeration) A value that specifies whether the Raw 
File destination deletes an existing file 
that has the same name. The options 
are Create Always (0), Create Once 
(1), Truncate and Append (3), and 
Append (2). The default value of this 
property is Create Always (0). 





NOTE 


An append operation requires the metadata of the appended data to match the metadata of the data already present in 
the file. 











The input and the input columns of the Raw File destination have no custom properties. 


For more information, see Raw File Destination. 


See Also 


Common Properties 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


The Recordset destination creates and populates an in-memory ADO recordset. The shape of the recordset is 
defined by the input to the Recordset destination at design time. 


Configuration of the Recordset Destination 


You configure the Recordset destination by specifying the variable that stores the ADO recordset. 


At run time, an ADO recordset is written to the variable of type, Object, that is specified in the VariableName 
property of the Recordset destination. The variable then makes the Recordset available outside the data flow, 
where it can be used by scripts and other package elements. 


This source has one input. It does not support an error output. 
You can set properties through SSIS Designer or programmatically. 


The Advanced Editor dialog box reflects the properties that can be set programmatically. For more 
information about the properties that you can set in the Advanced Editor dialog box or programmatically, click 
one of the following topics: 


@ Common Properties 


e Recordset Destination Custom Properties 


For more information about how to set the properties, see Set the Properties of a Data Flow Component. 


Related Tasks 


Use a Recordset Destination 


Use a Recordset Destination 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


The Recordset destination does not save data to an external data source. Instead, the Recordset destination saves 
data in memory in a recordset that is stored in an Integration Services package variable of the Object data type. 
After the Recordset destination saves the data, you typically use a Foreach Loop container with the Foreach ADO 
enumerator to process one row of the recordset at a time. The Foreach ADO enumerator saves the value from 
each column of the current row into a separate package variable. Then, the tasks that you configure inside the 
Foreach Loop container read those values from the variables and perform some action with them. 


You can use the Recordset destination in many different scenarios. Here are some examples: 


e You can use a Send Mail task and the Integration Services expression language to send a customized e- 
mail message for each row in the recordset. 


e You can use a Script component configured as a source, inside a Data Flow task, to read the column 
values into the columns of the data flow. Then, you can use transformations and destinations to 
transform and save the row. In this example, the Data Flow task runs once for each row. 


The following sections first describe the general process of using the Recordset destination and then show a 
specific example of how to use the destination. 


General Steps to Using a Recordset Destination 


The following procedure summarizes the steps that are required to save data to a Recordset destination, and 
then use the Foreach Loop container to process each row. 


To save data to a Recordset destination and process each row by using the Foreach Loop container 


1. In SQL Server Data Tools (SSDT), create or open an Integration Services package. 


2. Create a variable that will contain the recordset saved into memory by the Recordset destination, and set 
the variable's type to Object. 


3. Create additional variables of the appropriate types to contain the values of each column in the recordset 
that you want to use. 


4. Add and configure the connection manager required by the data source that you plan to use in your data 
flow. 


5. Add a Data Flow task to the package, and on the Data Flow tab of SSIS Designer, configure sources and 
transformations to load and transform the data. 


6. Add a Recordset destination to the data flow and connect it to the transformations. For the 
VariableName property of the Recordset destination, enter the name of the variable that you created to 
hold the recordset. 


7. On the Control Flow tab of SSIS Designer, add a Foreach Loop container and connect this container after 
the Data Flow task. Then, open the Foreach Loop Editor to configure the container with the following 
settings: 


a. On the Collection page, select the Foreach ADO Enumerator. Then, for ADO object source 
variable, select the variable that contains the recordset. 


b. On the Variable Mappings page, map the zero-based index of each column that you want to use 
to the appropriate variable. 


On each iteration of the loop, the enumerator populates these variables with the column values 


from the current row. 


8. Inside the Foreach Loop container, add and configure tasks to process one row of the recordset at a time 
by reading the values from the variables. 


Example of Using the Recordset Destination 


In the following example, the Data Flow task loads information about AdventureWorks2012 employees from the 
Sales.SalesPerson table into a Recordset destination. Then, a Foreach Loop container reads one row of data at a 
time, and calls a Send Mail task. The Send Mail task uses expressions to send a customized e-mail message to 


each salesperson about the amount of his or her bonus. 


To create the project and configure the variables 


1. In SQL Server Data Tools, create a new Integration Services project. 
2. Onthe SSIS menu, select Variables. 


3. In the Variables window, create the variables that will hold the recordset and the column values from the 


current row: 

a. Create a variable named, BonusRecordset, and set its type to Object. 
The BonusRecordset variable holds the recordset. 

b. Create a variable named, EmailAddress, and set its type to String. 
The EmailAddress variable holds the salesperson's e-mail address. 

c. Create a variable named, FirstName, and set its type to String. 
The FirstName variable holds the salespersons first name. 

d. Create a variable named, Bonus, and set its type to Double. 


The Bonus variable holds the amount of the salesperson's bonus. 


To configure the connection managers 
1. In the Connection Managers area of the SSIS Designer, add and configure a new OLE DB connection 
manager that connects to the AdventureWorks2012 sample database. 


The OLE DB source in the Data Flow task will use this connection manager to retrieve data. 


2. In the Connection Managers area, add and configure a new SMTP connection manager that connects to 


an available SMTP server. 
The Send Mail task inside the Foreach Loop container will use this connection manager to send emails. 


To configure the data flow and the Recordset Destination 


1. On the Control Flow tab of SSIS Designer, add a Data Flow task to the design surface. 


2. On the Data Flow tab, add an OLE DB source to the Data Flow task, and then open the OLE DB Source 
Editor. 


3. On the Connection Manager page of the editor, configure the source with the following settings: 


a. For OLE DB connection manager, select the OLE DB connection manager that you previously 
created. 


b. For Data access mode, select SQL command. 


c. For SQL command text, enter the following query: 


SELECT Person.Contact.EmailAddress, Person.Contact.FirstName, CONVERT(float, 
Sales.SalesPerson.Bonus) AS Bonus 
FROM Sales.SalesPerson INNER JOIN 


Person.Contact ON Sales.SalesPerson.SalesPersonID = 
Person.Contact.ContactID 


NOTE 


You have to convert the currency value in the Bonus column to a float before you can load that value 


into a package variable whose type is Double. 





4. On the Data Flow tab, add a Recordset destination, and connect the destination after the OLE DB source. 
5. Open the Recordset Destination Editor, and configure the destination with the following settings: 


a. On the Component Properties tab, for VariableName property, select 
User::BonusRecordset. 


b. On the Input Columns tab, select all three of the available columns. 


To configure the Foreach Loop container and run the package 
1. On the Control Flow tab of SSIS Designer, add a Foreach Loop container, and connect the container after 
the Data Flow task. 


2. Open the Foreach Loop Editor, and configure the container with the following settings: 


a. On the Collection page, for Enumerator, select Foreach ADO Enumerator, and for ADO 
object source variable, select User::BonusRecordset. 


b. On the Variable Mappings page, map User::EmailAddress to index 0, User::FirstName to 
index 1, and User::Bonus to index 2. 


3. On the Control Flow tab, inside the Foreach Loop container, add a Send Mail task. 


4. Open the Send Mail Task Editor, and then on the Mail page, configure the task with the following 
settings: 


a. For SmtpConnection, select the SMTP connection manager that was configured previously. 
b. For From, enter an appropriate e-mail address. 


If you use your own e-mail address, you will be able to confirm that the package runs successfully. 
You will receive undeliverable receipts for the messages sent by the Send Mail task to the fictitious 
salespersons of AdventureWorks2012. 


c. For To, enter a default e-mail address. 


This value will not be used, but will be replaced at run time by the e-mail address of each 
salesperson. 


d. For Subject, enter "Your annual bonus". 
e. For MessageSourceType, select Direct Input. 


5. On the Expressions page of the Send Mail Task Editor, click the ellipsis button (...) to open the 
Property Expressions Editor. 


6. In the Property Expressions Editor, enter the following information: 


a. For ToLine, add the following expression: 


@[User: :EmailAddress ] 


b. For the MessageSource property, add the following expression: 


“Dear "+ @[User::FirstName] + ": The amount of your bonus for this year is $" + (DT_WSTR, 
12) @[User::Bonus] + ". Thank you!" 


7. Run the package. 


If you have specified a valid SMTP server and provided your own e-mail address, you will receive 
undeliverable receipts for the messages that the Send Mail task sends to the fictitious salespersons of 
AdventureWorks2012. 


Recordset Destination Custom Properties 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 
The Recordset destination has both custom properties and the properties common to all data flow components. 


The following table describes the custom properties of the Recordset destination. All properties are read/write. 


PROPERTY NAME DATA TYPE DESCRIPTION 


VariableName String The name of the variable that holds 
the ADO recordset. 


The input and the input columns of the Recordset destination have no custom properties. 


For more information, see Recordset Destination. 


See Also 


Common Properties 


SAP BW Source 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


The SAP BW source is the source component of the Microsoft Connector 1.1 for SAP BW. Thus, the SAP BW 
source extracts data from an SAP Netweaver BW version 7 system and makes this data available to the data flow 
in a Microsoft Integration Services package. 


This source has one output and one error output. 





IMPORTANT 
The documentation for the Microsoft Connector 1.1 for SAP BW assumes familiarity with the SAP Netweaver BW 


environment. For more information about SAP Netweaver BW, or for information about how to configure SAP Netweaver 


BW objects and processes, see your SAP documentation. 








IMPORTANT 


Extracting data from SAP Netweaver BW requires additional SAP licensing. Check with SAP to verify these requirements. 








To use the SAP BW source, you have to do the following tasks: 
e@ Prepare the SAP Netweaver BW objects 
e Connect to the SAP Netweaver BW system 


e Configure the SAP BW source 


Preparing the SAP Netweaver BW Objects That the Source Requires 


The SAP BW source requires that certain objects are in the SAP Netweaver BW system before the source can 
function. If these objects do not already exist, you have to follow these steps to create and configure these 
objects in the SAP Netweaver BW system. 





NOTE 


For additional details about these objects and these configuration steps, see the SAP Netweaver BW documentation. 





1. Log on to SAP Netweaver BW through the SAP GUI, enter transaction code SM59, and create an RFC 
destination: 


a. For Connection Type, select TCP/IP. 
b. For Activation Type, select Registered Server Program. 


c. For Communication Type with Target System, select Non-Unicode (Inactive MDMP 
Settings). 


d. Assign an appropriate Program ID. 


2. Create an Open Hub Destination: 


a. Go to the Administrator Workbench (transaction code RSA1) and, in the left pane, select Open 
Hub Destination. 


b. In the middle pane, right-click an InfoArea, and then select "Create Open Hub Destination". 


c. For Destination Type, select "Third Party Tool", and then enter the previously created RFC 
Destination. 


d. Save and activate the new Open Hub Destination. 
3. Create a Data Transfer Process (DTP): 


a. In the middle pane of the InfoArea, right-click the previously created destination, and then select 
"Create data transfer process". 


b. Configure, save, and activate the DTP. 
c. On the menu, click Goto, and then click Settings for Batch Manager. 
d. Update Number of processes to 1 for serial processing. 

4. Create a process chain: 


a. When configuring the process chain, select the Start Using Metadata Chain or API as the 
Scheduling Options of the Start Process, and then add the previously created DTP as the 
subsequent node. 


b. Save and activate the process chain. 


The SAP BW source can call the process chain to activate the data transfer process. 


Connecting to the SAP Netweaver BW System 


To connect to the SAP Netweaver BW version 7 system, the SAP BW source uses the SAP BW connection 
manager that is part of the Microsoft Connector 1.1 for SAP BW package. The SAP BW connection manager is 
the only Integration Services connection manager that the SAP BW source can use. 


For more information about the SAP BW connection manager, see SAP BW Connection Manager. 


Configuring the SAP BW Source 


You can configure the SAP BW source in the following ways: 
e Look up and select the Open Hub Service (OHS) destination to use to extract data. 
e Select one of the following methods for extracting data: 
o Trigger a process chain. In this case, the Integration Services package starts the extraction process. 


o Wait for notification from the SAP Netweaver BW system to begin an extraction. In this case, the 
SAP Netweaver BW system starts the extraction process. 


o Retrieve the data that is associated with a particular Request ID. In this case, the SAP Netweaver 
BW system has already extracted the data to an internal table, and the Integration Services 
package just reads the data. 


e Depending on the method selected for extracting data, provide the following additional information: 


o For theP - Trigger Process Chain option, provide the gateway host name, gateway service 
name, program ID for the RFC destination, and name of the process chain. 


o For the W - Wait for Notify option, provide the gateway host name, the gateway server name, 


and the program ID for the RFC destination. You can also specify the timeout (in seconds). The 
timeout is the maximum period of time that the source will wait to be notified. 


o For theE - Extract Only option, provide the Request ID. 


e Specify rules for string conversion. (For example, convert all strings depending on whether the SAP 
Netweaver BW system is Unicode or not, or convert all strings to varchar or nvarchar). 


e Use the options that you have selected to preview the data to be extracted. 


You can also enable logging of RFC function calls by the source. (This logging is separate from the optional 
logging that you can enable on Integration Services packages.) You enable logging of RFC function calls when 
you configure the SAP BW connection manager that the source will use. For more information about how to 
configure the SAP BW connection manager, see SAP BW Connection Manager. 


If you do not know all the values that are required to configure the source, you might have to ask your SAP 
administrator. 


For a walkthrough that demonstrates how to configure and use the SAP BW connection manager, source, and 
destination, see the white paper, Using SQL Server 2008 Integration Services with SAP BI 7.0. This white paper 
also shows how to configure the required objects in SAP BW. 


Using the SSIS Designer to Configure the Source 


For more information about the properties of the SAP BW source that you can set in SSIS Designer, click one of 
the following topics: 


e SAP BW Source Editor (Connection Manager Page) 
e SAP BW Source Editor (Columns Page) 

e SAP BW Source Editor (Error Output Page) 

e SAP BW Source Editor (Advanced Page) 


While you are configuring the SAP BW source, you can also use various dialog boxes to look up SAP Netweaver 
BW objects or to preview the source data. For more information about these dialog boxes, click one of the 
following topics: 


e Look Up RFC Destination 
@ Look Up Process Chain 
e Request Log 


e Preview 


See Also 


Microsoft Connector for SAP BW Components 


SAP BW Source Editor (Connection Manager Page) 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Use the Connection Manager page of the SAP BW Source Editor to select the SAP BW connection manager 
for the SAP BW source. On this page, you also select the execution mode and the parameters for extracting the 
data from the SAP Netweaver BW system. 


To learn more about the SAP BW source component of the Microsoft Connector 1.1 for SAP BW, see SAP BW 
Source. 


IMPORTANT 


The documentation for the Microsoft Connector 1.1 for SAP BW assumes familiarity with the SAP Netweaver BW 
environment. For more information about SAP Netweaver BW, or for information about how to configure SAP Netweaver 


BW objects and processes, see your SAP documentation. 


IMPORTANT 
Extracting data from SAP Netweaver BW requires additional SAP licensing. Check with SAP to verify these requirements. 











To open the Connection Manager page 
1. In SQL Server Data Tools (SSDT), open the Integration Services package that contains the SAP BW source. 
2. On the Data Flow tab, double-click the SAP BW source. 


3. In the SAP BW Source Editor, click Connection Manager to open the Connection Manager page of 
the editor. 


Static Options 





NOTE 


If you do not know all the values that are required to configure the source, you might have to ask your SAP administrator. 





SAP BW connection manager 


Select an existing connection manager from the list, or create a new connection by clicking New. 


New 
Create a new connection manager by using the SAP BW Connection Manager dialog box. 


For more information about this dialog box, see SAP BW Connection Manager Editor. 


OHS destination 
Select the Open Hub Service (OHS) destination to use to extract data from the source. 


Execution mode 


Specify the method for extracting data from the source. 


OPTION DESCRIPTION 


P - Trigger Process Chain Trigger a process chain. In this case, the Integration Services 
package starts the extraction process. 


W - Wait for Notify Wait for notification from the SAP Netweaver BW system to 
begin extracting the data. In this case, the SAP Netweaver 
BW system starts the extraction process. 


E - Extract Only Retrieve the data that is associated with a particular Request 
ID. In this case, the SAP Netweaver BW system has already 
extracted the data into an internal table, and the Integration 
Services package just reads the data. 


Preview 


Open the Preview dialog box in which you can preview results. For more information, see Preview. 





IMPORTANT 
The Preview option, that is available on the Connection Manager page of the SAP BW Source Editor, actually extracts 
data. If you have configured SAP Netweaver BW to extract only data that has changed since the previous extraction, 


selecting Preview will exclude the previewed data from the next extraction. 








When you click Preview, you also open the Request Log dialog box. You can use this dialog box to view the 
events that are logged during the request that is made to the SAP Netweaver BW system for sample data. For 
more information, see Request Log. 


Execution Mode Dynamic Options 





NOTE 


If you do not know all the values that are required to configure the source, you might have to ask your SAP administrator. 





Execution Mode = P - Trigger Process Chain 


RFC Destination Options 

You do not have to know and enter these values in advance. Use the Look up button to find and select the 
appropriate RFC destination. After you select an RFC destination, the component enters the appropriate values 
for these options. 


Gateway host 
Enter the server name or IP address of the gateway host. Usually, the name or IP address is the same as the SAP 
application server. 


Gateway service 
Enter the name of the gateway service, in the format sapgwNN, where NN is the system number. 


Program ID 
Enter the Program ID that is associated with the RFC destination. 


Look up 
Look up the RFC destination by using the Look Up RFC Destination dialog box. For more information about 
this dialog box, see Look Up RFC Destination. 


Process Chain Options 


You do not have to know and enter these values in advance. Use the Look up button to find and select the 


appropriate process chain. After you select a process chain, the component enters the appropriate value for the 
option. 


Process chain 
Enter the name of the process chain to be triggered by the source. 


Look up 
Look up the process chain by using the Look Up Process Chain dialog box. For more information about this 
dialog box, see Look Up Process Chain. 


Execution Mode = W - Wait for Notify 

RFC Destination Options 

You do not have to know and enter these values in advance. Use the Look up button to find and select the 
appropriate RFC destination. After you select an RFC destination, the component enters the appropriate values 
for the options. 


Gateway host 
Enter the server name or IP address of the gateway host. Usually, the name or IP address is the same as the SAP 
application server. 


Gateway service 
Enter the name of the gateway service, in the format sapgwNN, where NN is the system number. 


Program ID 
Enter the Program ID that is associated with the RFC destination. 


Look up 
Look up the RFC destination by using the Look Up RFC Destination dialog box. For more information about 
this dialog box, see Look Up RFC Destination. 


Execution Mode = E - Extract Only 


Request ID 
Enter the Request ID that is associated with the extraction. 


See Also 


SAP BW Source Editor (Columns Page) 
SAP BW Source Editor (Error Output Page) 
SAP BW Source Editor (Advanced Page) 
Microsoft Connector for SAP BW F1 Help 
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Use the Columns page of the SAP BW Source Editor to map an output column to each external (source) 
column. 


To learn more about the SAP BW source component of the Microsoft Connector 1.1 for SAP BW, see SAP BW 
Source. 





IMPORTANT 
The documentation for the Microsoft Connector 1.1 for SAP BW assumes familiarity with the SAP Netweaver BW 
environment. For more information about SAP Netweaver BW, or for information about how to configure SAP Netweaver 


BW objects and processes, see your SAP documentation. 








IMPORTANT 


Extracting data from SAP Netweaver BW requires additional SAP licensing. Check with SAP to verify these requirements. 








To open the Columns page 
1. In SQL Server Data Tools (SSDT), open the Integration Services package that contains the SAP BW source. 
2. On the Data Flow tab, double-click the SAP BW source. 


3. Inthe SAP BW Source Editor, click Columns to open the Columns page of the editor. 


Options 





NOTE 


If you do not know all the values that are required to configure the source, you might have to ask your SAP administrator. 





Available External Columns 
View the list of available external columns in the data source, and then select the columns to be included in the 
data flow. 


To include a column in the data flow, select the check box that corresponds to that column. The order in which 
you select the check boxes determines the order in which columns will be output. That is, the first check box that 
you select will be the first output column, the second check box will be the second output columns, and so on. 


External Column 

View the selected external (source) columns. The selected columns appear in the order in which you will see 
their corresponding output columns when you configure downstream components that consume data from this 
source. 


To change the order of the columns, in the Available External Columns list, clear the check boxes for all 
columns. Then, select the columns in the order that you want them to appear. 


Output Column 

Provide a unique name for each output column. The default is the name of the selected external (source) 
column. However, you can enter any unique, descriptive name. SSIS Designer will display the Output Column 
names for the columns when you configure downstream components that consume data from this source. 


See Also 


SAP BW Source Editor (Connection Manager Page) 
SAP BW Source Editor (Error Output Page) 

SAP BW Source Editor (Advanced Page) 

Microsoft Connector for SAP BW F1 Help 


SAP BW Source Editor (Error Output Page) 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Use the Error Output page of the SAP BW Source Editor to select error handling options and to set 
properties on error output columns. 


To learn more about the SAP BW source component of the Microsoft Connector 1.1 for SAP BW, see SAP BW 
Source. 





IMPORTANT 
The documentation for the Microsoft Connector 1.1 for SAP BW assumes familiarity with the SAP Netweaver BW 


environment. For more information about SAP Netweaver BW, or for information about how to configure SAP Netweaver 
BW objects and processes, see your SAP documentation. 








IMPORTANT 


Extracting data from SAP Netweaver BW requires additional SAP licensing. Check with SAP to verify these requirements. 








To open the Error Output page 
1. In SQL Server Data Tools (SSDT), open the Integration Services package that contains the SAP BW source. 
2. On the Data Flow tab, double-click the SAP BW source. 


3. Inthe SAP BW Source Editor, click Error Output to open the Error Output page of the editor. 


Options 





NOTE 


If you do not know all the values that are required to configure the source, you might have to ask your SAP administrator. 





Input or Output 
View the name of the data source. 


Column 
View the external (source) columns that you selected on the Columns page of the SAP BW Source Editor 
dialog box. For more information about this dialog box, see SAP BW Source Editor (Columns Page). 


Error 
Specify what the SAP BW source component should do when there is an error: ignore the failure, redirect the 
row, or fail the component. 


Truncation 
Specify what the SAP BW source component should do when a truncation occurs: ignore the failure, redirect the 
row, or fail the component. 


Description 


View the description of the error. 


Set this value to selected cells 
Specify what the SAP BW source component should do to all the selected cells when an error or truncation 
occurs: ignore the failure, redirect the row, or fail the component. 


Apply 
Apply the error handling option to the selected cells. 


See Also 


SAP BW Source Editor (Connection Manager Page) 
SAP BW Source Editor (Columns Page) 

SAP BW Source Editor (Advanced Page) 

Microsoft Connector for SAP BW F1 Help 


SAP BW Source Editor (Advanced Page) 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Use the Advanced page of the SAP BW Source Editor to specify the string conversion rule and the time-out 
period, and also to reset the status of a particular Request ID. 


To learn more about the SAP BW source component of the Microsoft Connector 1.1 for SAP BW, see SAP BW 
Source. 





IMPORTANT 
The documentation for the Microsoft Connector 1.1 for SAP BW assumes familiarity with the SAP Netweaver BW 


environment. For more information about SAP Netweaver BW, or for information about how to configure SAP Netweaver 
BW objects and processes, see your SAP documentation. 








IMPORTANT 


Extracting data from SAP Netweaver BW requires additional SAP licensing. Check with SAP to verify these requirements. 








To open the Connection Manager page 
1. In SQL Server Data Tools (SSDT), open the Integration Services package that contains the SAP BW source. 
2. On the Data Flow tab, double-click the SAP BW source. 


3. Inthe SAP BW Source Editor, click Advanced to open the Advanced page of the editor. 


Options 





NOTE 


If you do not know all the values that are required to configure the source, you might have to ask your SAP administrator. 





String Conversion 
Specify the rule to apply for string conversion. 


OPTION DESCRIPTION 


Automatic string conversion Convert all strings to nvarchar when the SAP Netweaver 
BW system is a Unicode system. Otherwise, convert all 
strings to varchar. 


Convert strings to varchar Convert all strings to varchar. 


Convert strings to nvarchar Convert all strings to nvarchar. 


Timeout (seconds) 
Specify the maximum number of seconds that the source should wait. 





NOTE 


This option is only valid if you have selected W - Wait for Notify as the value of Execution Mode on the Connection 
Manager page of the editor. For more information, see SAP BW Source Editor (Connection Manager Page). 











Request ID 
Specify the Request ID whose status you want to reset to "G - Green" when you click Reset. 


Reset 

Lets you reset the status of the specified Request ID to "G - Green", after prompting you for confirmation. This 
can be useful when a problem has occurred, and the SAP Netweaver BW system has flagged the request with a 
yellow or red status. 


See Also 


SAP BW Source Editor (Connection Manager Page) 
SAP BW Source Editor (Columns Page) 

SAP BW Source Editor (Error Output Page) 
Microsoft Connector for SAP BW F1 Help 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Use the Look Up RFC Destination dialog box to look up an RFC destination that is defined in the SAP 
Netweaver BW system. When the list of available RFC destinations appears, select the destination that you want, 
and the component will populate the associated options with the required values. 


Both the SAP BW source and the SAP BW destination use the Look Up RFC Destination dialog box. For more 
information about these components of the Microsoft Connector 1.1 for SAP BW, see SAP BW Source and SAP 
BW Destination. 


IMPORTANT 


The documentation for the Microsoft Connector 1.1 for SAP BW assumes familiarity with the SAP Netweaver BW 
environment. For more information about SAP Netweaver BW, or for information about how to configure SAP Netweaver 
BW objects and processes, see your SAP documentation. 











To open the Look Up RFC Destination dialog box 


1. In SQL Server Data Tools (SSDT), open the Integration Services package that contains the SAP BW source 
or destination. 


2. On the Data Flow tab, double-click the SAP BW source or destination. 


3. In the SAP BW Source Editor or the SAP BW Destination Editor, click Connection Manager to 
open the Connection Manager page of the editor. 


4. On the Connection Manager page, in the RFC Destination group box, click Look up to display the 
Look Up RFC Destination dialog box. 


In the SAP BW Source Editor, the RFC Destination group box appears only if the value for Execution 
mode is P - Trigger process chain or W - Wait for notify. 


Options 


Destination 
View the name of the RFC destination that is defined in the SAP Netweaver BW system. 


Gateway Host 
View the server name or IP address of the gateway host. Usually, the name or IP address is the same as the SAP 
application server. 


Gateway Service 
View the name of the gateway service, in the format sapgwNN, where NN is the system number. 


Program ID 
View the Program ID that is associated with the RFC destination. 


See Also 


SAP BW Source Editor (Connection Manager Page) 


SAP BW Destination Editor (Connection Manager Page) 
Microsoft Connector for SAP BW F1 Help 


Look Up Process Chain 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Use the Look Up Process Chain dialog box to look up a process chain that is defined in the SAP Netweaver 
BW system. When the list of available process chains appears, select the chain that you want, and the source will 
populate the associated options with the required values. 


The SAP BW source of the Microsoft Connector 1.1 for SAP BW uses the Look Up Process Chain dialog box. 
To learn more about the SAP BW source, see SAP BW Source. 


IMPORTANT 


The documentation for the Microsoft Connector 1.1 for SAP BW assumes familiarity with the SAP Netweaver BW 
environment. For more information about SAP Netweaver BW, or for information about how to configure SAP Netweaver 


BW objects and processes, see your SAP documentation. 








To open the Look Up Process Chain dialog box 
1. In SQL Server Data Tools (SSDT), open the Integration Services package that contains the SAP BW source. 
2. On the Data Flow tab, double-click the SAP BW source. 


3. In the SAP BW Source Editor, click Connection Manager to open the Connection Manager page of 
the editor. 


4. In the Process Chain group box, click Look up to display the Look Up Process Chain dialog box. 


The Process Chain group box appears only if the value for Execution mode is P - Trigger process 
chain. 


Lookup Options 


In the lookup fields, you can filter results by using the asterisk wildcard character (*), or by using a partial string 
in combination with the asterisk wildcard character. However, if you leave a lookup field empty, the lookup 
operation will only match empty strings in that field. 


Process chain 
Enter the name of the process chain that you want to look up, or enter a partial name with the asterisk wildcard 
character (*). Or, use the asterisk wildcard character alone to include all process chains. 


Look up 
Look up matching process chains that are defined in the SAP Netweaver BW system. 


Lookup Results 


After you click the Look up button, a list of the process chains in the SAP Netweaver BW system appears in a 
table with the following column headings: 


Process Chain 
Displays the name of the process chain that is defined in the SAP Netweaver BW system. 


Description 


Displays the description of the process chain. 


When the list of available process chains appears, select the chain that you want, and the source will populate 
the associated options with the required values. 


See Also 


SAP BW Source Editor (Connection Manager Page) 
Microsoft Connector for SAP BW F1 Help 


Request Log 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Use the Request Log dialog box to view the events that are logged during the request that is made to the SAP 
Netweaver BW system for sample data. This information can be useful if you have to troubleshoot your 
configuration of the SAP BW source. 


To learn more about the SAP BW source component of the Microsoft Connector 1.1 for SAP BW, see SAP BW 
Source. 


IMPORTANT 


The documentation for the Microsoft Connector 1.1 for SAP BW assumes familiarity with the SAP Netweaver BW 
environment. For more information about SAP Netweaver BW, or for information about how to configure SAP Netweaver 


BW objects and processes, see your SAP documentation. 


IMPORTANT 


Extracting data from SAP Netweaver BW requires additional SAP licensing. Check with SAP to verify these requirements. 











To open the Request Log dialog box 
1. In SQL Server Data Tools (SSDT), open the Integration Services package that contains the SAP BW source. 
2. On the Data Flow tab, double-click the SAP BW source. 


3. In the SAP BW Source Editor, click Connection Manager to open the Connection Manager page of 
the editor. 


4. After you configure the SAP BW source, click Preview to preview the events in the Request Log dialog 


box. 





NOTE 


Clicking Preview also opens the Preview dialog box. For more information about this dialog box, see Preview. 





Options 


Time 


Displays the time that the event that was logged. 


Type 
Displays the type of the event that was logged. The following table lists the possible event types. 


VALUE DESCRIPTION 


S Success message. 


VALUE DESCRIPTION 

E Error message 

Ww Warning message. 
Informational message. 

A The operation was aborted. 


Message 
Displays the message text that is associated with the logged event. 


See Also 


SAP BW Source Editor (Connection Manager Page) 
Microsoft Connector for SAP BW F1 Help 


Preview 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Use the Preview dialog box to preview the data that the SAP BW source will extract. 


IMPORTANT 


The Preview option, that is available on the Connection Manager page of the SAP BW Source Editor, actually 
extracts data. If you have configured SAP Netweaver BW to extract only data that has changed since the previous 
extraction, selecting Preview will exclude the previewed data from the next extraction. 








To learn more about the SAP BW source component of the Microsoft Connector 1.1 for SAP BW, see SAP BW 
Source. 


IMPORTANT 

The documentation for the Microsoft Connector 1.1 for SAP BW assumes familiarity with the SAP Netweaver BW 
environment. For more information about SAP Netweaver BW, or for information about how to configure SAP Netweaver 
BW objects and processes, see your SAP documentation. 








IMPORTANT 
Extracting data from SAP Netweaver BW requires additional SAP licensing. Check with SAP to verify these requirements. 








To open the Preview dialog box 
1. In SQL Server Data Tools (SSDT), open the Integration Services package that contains the SAP BW source. 
2. On the Data Flow tab, double-click the SAP BW source. 


3. In the SAP BW Source Editor, click Connection Manager to open the Connection Manager page of 
the editor. 


4. Configure the SAP BW source. 


5. After you configure the SAP BW source, on the Connection Manager page, click Preview to preview 


the data in the Preview dialog box. 





NOTE 


Clicking Preview also opens the Request Log dialog box. For more information about this dialog box, see 
Request Log. 








Options 


The Preview dialog box displays the rows that are requested from the SAP Netweaver BW system. The columns 
that are displayed are the columns that are defined in the source data. 


There are no other options in this dialog box. 


See Also 


SAP BW Source Editor (Connection Manager Page) 
Microsoft Connector for SAP BW F1 Help 


SAP BW Destination 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


The SAP BW destination is the destination component of the Microsoft Connector 1.1 for SAP BW. Thus, the SAP 
BW destination loads data from the data flow in an Integration Services package into an SAP Netweaver BW 
version 7 system. 


This destination has one input and one error output. 





IMPORTANT 
The documentation for the Microsoft Connector 1.1 for SAP BW assumes familiarity with the SAP Netweaver BW 


environment. For more information about SAP Netweaver BW, or for information about how to configure SAP Netweaver 


BW objects and processes, see your SAP documentation. 











To use the SAP BW destination, you have to do the following tasks: 
e Prepare the SAP Netweaver BW objects 
e@ Connect to the SAP Netweaver BW system 


e Configure the SAP BW destination 


Preparing the SAP Netweaver BW Objects That the Destination 
Requires 


The SAP BW destination requires that certain objects are in the SAP Netweaver BW system before the 
destination can function. If these objects do not already exist, you have to follow these steps to create and 
configure these objects in the SAP Netweaver BW system. 





NOTE 


For additional details about these objects and these configuration steps, see the SAP Netweaver BW documentation. 





1. Create a new Source System: 


a. Select the type, "Third Party/Staging BAPIs". 


b. For Communication Type with Target System, select Non-Unicode (Inactive MDMP 
Settings). 


c. Assign an appropriate Program ID. 
2. Assign the Source System to an InfoSource. 
3. Create an InfoPackage. 
The InfoPackage is the most important object that is required by the SAP BW destination. 


You can also create additional InfoObjects, InfoCubes, InfoSources, and InfoPackages that are required to 
support loading data into the SAP Netweaver BW system. 


Connecting to the SAP Netweaver BW System 


To connect to the SAP Netweaver BW version 7 system, the SAP BW destination uses the SAP BW connection 
manager that is part of the Microsoft Connector 1.1 for SAP BW package. The SAP BW connection manager is 
the only Integration Services connection manager that the SAP BW destination can use. 


For more information about the SAP BW connection manager, see SAP BW Connection Manager. 


Configuring the SAP BW Destination 


You can configure the SAP BW destination in the following ways: 

e Look up and select the InfoPackage to use to load data. 

e@ Map each column in the data flow to the appropriate InfoObject in the InfoPackage. 

e Specify how many rows of data will be transferred at a time by configuring the PackageSize property. 
e Choose to wait until the loading of data is completed by the SAP Netweaver BW system. 


e Choose not to trigger the InfoPackage, but to wait for notification that the SAP Netweaver BW system has 
started the loading of data. 


e Optionally, trigger another process chain after the loading of data is completed. 


e@ Optionally, create the SAP Netweaver BW objects that are required by the destination. This includes 
creating InfoObjects, InfoCubes, InfoSources, and InfoPackages. 


e Test the loading of data with the options that you have selected. 


You can also enable logging of RFC function calls by the destination. (This logging is separate from the optional 
logging that you can enable on Integration Services packages.) You enable logging of RFC function calls when 
you configure the SAP BW connection manager that the destination will use. For more information about how to 
configure the SAP BW connection manager, see SAP BW Connection Manager. 


If you do not know all the values that are required to configure the destination, you might have to ask your SAP 
administrator. 


For a walkthrough that demonstrates how to configure and use the SAP BW connection manager, source, and 
destination, see the white paper, Using SQL Server 2008 Integration Services with SAP BI 7.0. This white paper 
also shows how to configure the required objects in SAP BW. 


Using the SSIS Designer to Configure the Destination 


For more information about the properties of the SAP BW destination that you can set in SSIS Designer, click 
one of the following topics: 


e SAP BW Destination Editor (Connection Manager Page) 
e SAP BW Destination Editor (Mappings Page) 

e SAP BW Destination Editor (Error Output Page) 

e SAP BW Destination Editor (Advanced Page) 


While you are configuring the SAP BW destination, you can also use various dialog boxes to look up or to create 
SAP Netweaver BW objects. For more information about these dialog boxes, click one of the following topics: 


e Look Up InfoPackage 


e Create New InfoObject 


e Create InfoCube for Transaction Data 
e Look Up InfoObject 

® Create InfoSource 

e@ Create InfoSource for Transaction Data 
e@ Create InfoSource for Master Data 


e@ Create InfoPackage 


See Also 


Microsoft Connector for SAP BW Components 


SAP BW Destination Editor (Connection Manager 


Page) 
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Applies to: Q sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Use the Connection Manager page of the SAP BW Destination Editor to select the SAP BW connection 
manager that the SAP BW destination will use. On this page, you also select the parameters for loading the data 
into the SAP Netweaver BW system. 


To learn more about the SAP BW destination of the Microsoft Connector 1.1 for SAP BW, see SAP BW. 
Destination. 


IMPORTANT 
The documentation for the Microsoft Connector 1.1 for SAP BW assumes familiarity with the SAP Netweaver BW 


environment. For more information about SAP Netweaver BW, or for information about how to configure SAP Netweaver 


BW objects and processes, see your SAP documentation. 











To open the Connection Manager page 


1. In SQL Server Data Tools (SSDT), open the Integration Services package that contains the SAP BW 
destination. 


2. On the Data Flow tab, double-click the SAP BW destination. 
3. In the SAP BW Destination Editor, click Connection Manager to open the Connection Manager 


page of the editor. 


Options 





NOTE 


If you do not know all the values that are required to configure the destination, you might have to ask your SAP 
administrator. 











SAP BW connection manager 
Select an existing connection manager from the list, or create a new connection by clicking New. 


New 
Create a new connection manager by using the SAP BW Connection Manager dialog box. 


Test Load 
Perform a test of the loading process that uses the settings that you have selected and loads zero rows. 


InfoPackage/InfoSource Options 


You do not have to know and enter these values in advance. Use the Look up button to find and select the 
appropriate InfoPackage. After you select an InfoPackage, the component enters the appropriate values for these 
options. 


InfoPackage 


Enter the name of the InfoPackage. 


InfoSource 
Enter the name of the InfoSource. 


Type 
Enter the single-character that identifies the type of the InfoSource. The following table lists the acceptable 


single-character values. 


VALUE DESCRIPTION 

D Transaction data 
M Master data 

T Texts 

H Hierarchy data 


Logical system 
Enter the name of the logical system that is associated with the InfoPackage. 


Look up 

Look up the InfoPackage by using the Look Up InfoPackage dialog box. For more information about this 
dialog box, see Look Up InfoPackage. 

RFC Destination Options 


You do not have to know and enter these values in advance. Use the Look up button to find and select the 
appropriate RFC destination. After you select an RFC destination, the component enters the appropriate values 
for these options. 


Gateway host 
Enter the server name or IP address of the gateway host. Usually, the name or IP address is the same as the SAP 


application server. 


Gateway service 
Enter the name of the gateway service, in the format sapgwNN, where NN is the system number. 


Program ID 
Enter the Program ID that is associated with the RFC destination. 


Look up 
Look up the RFC destination by using the Look Up RFC Destination dialog box. For more information about 
this dialog box, see Look Up RFC Destination. 


Create SAP BW Objects Options 


Select object type 
Select the type of SAP Netweaver BW object that you want to create. You can select one of the following types: 


e InfoObject 

e InfoCube 

e InfoSource 

e InfoPackage 


Create 


Create the selected type of SAP Netweaver BW object. 
OBJECT TYPE 


InfoObject 


InfoCube 


InfoSource 


InfoPackage 


See Also 


SAP BW Destination Editor (Mappings Page) 
SAP BW Destination Editor (Error Output Page) 
SAP BW Destination Editor (Advanced Page) 
Microsoft Connector for SAP BW F1 Help 


RESULT 


Create a new InfoObject by using the Create New 
InfoObject dialog box. For more information about this 
dialog box, see Create New InfoObject. 


Create a new InfoCube by using the Create InfoCube for 
Transaction Data dialog box. For more information about 
this dialog box, see Create InfoCube for Transaction Data. 


Create a new InfoSource by using the Create InfoSource 
dialog box, and then by using the Create InfoSource for 
Transaction Data or the Create InfoSource for Master 
Data dialog box. For more information about these dialog 
boxes, see Create InfoSource, Create InfoSource for 
Transaction Data and Create InfoSource for Master Data. 


Create a new InfoPackage by using the Create 
InfoPackage dialog box. For more information about this 
dialog box, see Create InfoPackage. 


SAP BW Destination Editor (Mappings Page) 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 
Use the Mappings page of the SAP BW Destination Editor to map input columns to destination columns. 


To learn more about the SAP BW destination of the Microsoft Connector 1.1 for SAP BW, see SAP BW 
Destination. 


IMPORTANT 
The documentation for the Microsoft Connector 1.1 for SAP BW assumes familiarity with the SAP Netweaver BW 
environment. For more information about SAP Netweaver BW, or for information about how to configure SAP Netweaver 


BW objects and processes, see your SAP documentation. 





To open the Mappings page 


1. In SQL Server Data Tools (SSDT), open the Integration Services package that contains the SAP BW 
destination. 


2. On the Data Flow tab, double-click the SAP BW destination. 


3. In the SAP BW Destination Editor, click Mappings to open the Mappings page of the editor. 


Options 








NOTE 


If you do not know all the values that are required to configure the destination, you might have to ask your SAP 
administrator. 











The Mappings page of the SAP BW Destination Editor consists of two sections: 


e The upper section shows the available input and destination columns and lets you create mappings 
between these two types of columns. 


e The lower section is a table that lists which input columns have been mapped to which output columns. 


Upper Section Options 


The upper section has the following options: 


Available Input Columns 
View the list of available input columns. 


To map an input column to a destination column, drag a column from the Available Input Columns list and 
drop that column onto a column in the Available Destination Columns list. 


Available Destination Columns 
View the list of available destination columns. 


To map an input column to destination column, drag a column from the Available Input Columns list and 
drop that column onto a column in the Available Destination Columns list. 


The upper section also has a context menu that you can open by right-clicking on the background. This context 
menu contains the following options: 


e Select All Mappings 
e Delete Selected Mappings 
e Map Items by Matching Names 


Lower Section Columns 


The lower section is a table of the mappings, and has the following columns: 


Input Column 
View the input columns that you have selected. 


To map a different input column to the same destination column, select a different input column in the list. To 
remove a mapping, select <ignore> to exclude the input column from the output. 


Destination Column 
View each available destination column, regardless of whether that column is mapped or not. 


See Also 


SAP BW Destination Editor (Connection Manager Page) 
SAP BW Destination Editor (Error Output Page) 

SAP BW Destination Editor (Advanced Page) 

Microsoft Connector for SAP BW F1 Help 


SAP BW Destination Editor (Error Output Page) 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 
Use the Error Output page of the SAP BW Destination Editor to specify error handling options. 


To learn more about the SAP BW destination of the Microsoft Connector 1.1 for SAP BW, see SAP BW 
Destination. 


IMPORTANT 
The documentation for the Microsoft Connector 1.1 for SAP BW assumes familiarity with the SAP Netweaver BW 
environment. For more information about SAP Netweaver BW, or for information about how to configure SAP Netweaver 


BW objects and processes, see your SAP documentation. 








To open the Error Output page 


1. In SQL Server Data Tools (SSDT), open the Integration Services package that contains the SAP BW 
destination. 


2. On the Data Flow tab, double-click the SAP BW destination. 


3. Inthe SAP BW Destination Editor, click Error Output to open the Error Output page of the editor. 


Options 





NOTE 


If you do not know all the values that are required to configure the destination, you might have to ask your SAP 
administrator. 











Input or Output 
View the name of the input. 


Column 
This option is not used. 


Error 
Specify what the destination should do when an error occurs: ignore the failure, redirect the row, or fail the 
component. 


Truncation 
This option is not used. 


Description 
View the description of the operation. 


Set this value to selected cells 
Specify what the destination should do to all the selected cells when an error or truncation occurs: ignore the 
failure, redirect the row, or fail the component. 


Apply 


Apply the error handling option to the selected cells. 


See Also 


SAP BW Destination Editor (Connection Manager Page) 
SAP BW Destination Editor (Mappings Page) 

SAP BW Destination Editor (Advanced Page) 

Microsoft Connector for SAP BW F1 Help 


SAP BW Destination Editor (Advanced Page) 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Use the Advanced page of the SAP BW Destination Editor to set advanced settings such as package size and 
time-out information. 


To learn more about the SAP BW destination of the Microsoft Connector 1.1 for SAP BW, see SAP BW 
Destination. 





IMPORTANT 

The documentation for the Microsoft Connector 1.1 for SAP BW assumes familiarity with the SAP Netweaver BW 
environment. For more information about SAP Netweaver BW, or for information about how to configure SAP Netweaver 
BW objects and processes, see your SAP documentation. 











To open the Advanced page 


1. In SQL Server Data Tools (SSDT), open the Integration Services package that contains the SAP BW 
destination. 


2. On the Data Flow tab, double-click the SAP BW destination. 


3. Inthe SAP BW Destination Editor, click Advanced to open the Advanced page of the editor. 
Options 


NOTE 


If you do not know all the values that are required to configure the destination, you might have to ask your SAP 


administrator. 





Package size 

Specify how many rows of data will be transferred at a time. The optimal value for this parameter depends on 
the SAP Netweaver BW system and on additional processing of the data that might occur. Typically, values 
between 2000 and 20000 offer the best performance. 


Trigger process chain 
(Optional) Specify the name of a process chain to be triggered after the loading of data is completed. 


Timeout for waiting InfoPackage 
Specify the maximum number of seconds that the destination should wait for the InfoPackage to finish. 


Wait for data transfer to finish 
Specify whether the destination should wait until the SAP Netweaver BW system has finished loading the data. 


No InfoPackage Start (Only Wait) 
Specify that the destination does not trigger an InfoPackage, but just waits for notification that the SAP 
Netweaver BW system has started loading the data. 


See Also 


SAP BW Destination Editor (Connection Manager Page) 
SAP BW Destination Editor (Mappings Page) 

SAP BW Destination Editor (Error Output Page) 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Use the Look Up InfoPackage dialog box to look up an InfoPackage that is defined in the SAP Netweaver BW 
system. When the list of InfoPackages appears, select the InfoPackage that you want, and the destination will 
populate the associated options with the required values. 


The SAP BW destination of the Microsoft Connector 1.1 for SAP BW uses the Look Up Process Chain dialog 
box. To learn more about the SAP BW destination, see SAP BW Destination. 


IMPORTANT 
The documentation for the Microsoft Connector 1.1 for SAP BW assumes familiarity with the SAP Netweaver BW 
environment. For more information about SAP Netweaver BW, or for information about how to configure SAP Netweaver 


BW objects and processes, see your SAP documentation. 








To open the Look Up InfoPackage dialog box 


1. In SQL Server Data Tools (SSDT), open the Integration Services package that contains the SAP BW 
destination. 


2. On the Data Flow tab, double-click the SAP BW destination. 


3. In the SAP BW Destination Editor, click Connection Manager to open the Connection Manager 
page of the editor. 


4. On the Connection Manager page, in the InfoPackage/InfoSource group box, click Look up to 
display the Look Up InfoPackage dialog box. 


Lookup Options 


In the lookup fields, you can filter results by using the asterisk wildcard character (*), or by using a partial string 
in combination with the asterisk wildcard character. However, if you leave a lookup field empty, the lookup 
operation will only match empty strings in that field. 


InfoPackage 
Enter the name of the InfoPackage that you want to look up, or a partial name with the asterisk wildcard 
character (*). Or, use the asterisk wildcard character alone to include all InfoPackages. 


InfoSource 
Enter the name of the InfoSource, or a partial name with the asterisk wildcard character (*). Or, use the asterisk 
wildcard character alone to include all InfoPackages regardless of InfoSource. 


Source system 
Enter the name of the source system, or a partial name with the asterisk wildcard character (*). Or, use the 
asterisk wildcard character alone to include all InfoPackages regardless of source systems. 


Look up 
Look up matching InfoPackages that are defined in the SAP Netweaver BW system. 


Lookup Results 


After you click the Look up button, a list of the InfoPackages in the SAP Netweaver BW system appears in a table 
with the following column headings. 


InfoPackage 
Displays the name of the InfoPackage that is defined in the SAP Netweaver BW system. 


Type 
Displays the type of the InfoPackage. The following table lists the possible values for the type. 


VALUE DESCRIPTION 

Trans. Transaction data. 

Attr Attribute data. 

Texts Texts. 
Description 


Displays the description of the InfoPackage. 


InfoSource 
Displays the name of the InfoSource, if any, that is associated with the InfoPackage. 


Source System 
Displays the name of the source system. 


When the list of InfoPackages appears, select the InfoPackage that you want, and the destination will populate 
the associated options with the required values. 


See Also 


SAP BW Destination Editor (Connection Manager Page) 
Microsoft Connector for SAP BW F1 Help 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 
Use the Create New InfoObject dialog box to create a new InfoObject in the SAP Netweaver BW system. 


You can open the Create InfoObject dialog box from the Connection Manager page of the SAP BW 
Destination Editor. To learn more about the SAP BW destination, see SAP BW Destination. 


IMPORTANT 


The documentation for the Microsoft Connector 1.1 for SAP BW assumes familiarity with the SAP Netweaver BW 
environment. For more information about SAP Netweaver BW, or for information about how to configure SAP Netweaver 


BW objects and processes, see your SAP documentation. 








To open the Create New InfoObject dialog box 


1. In SQL Server Data Tools (SSDT), open the Integration Services package that contains the SAP BW 
destination. 


2. On the Data Flow tab, double-click the SAP BW destination. 


3. In the SAP BW Destination Editor, click Connection Manager to open the Connection Manager 
page of the editor. 


4. On the Connection Manager page, in the Create SAP BW Objects group box, do one of the following 
steps to create an InfoObject: 


a. To create an InfoObject directly, select InfoObject, and then click Create to open the Create New 
InfoObject dialog box. 


b. To create an InfoObject while creating an InfoCube, select InfoCube, and then click Create. In the 
Create InfoCube for Transaction Data dialog box, in the Object column for one of the rows in 
the list, select Create to open the Create New InfoObject dialog box. 





NOTE 


Each row in the table represents a column in the data flow of the package. 





c. To create an InfoObject while creating an InfoSouce for transactional data, select InfoSource, and 
then click Create. In the Create InfoSource dialog box, select Transaction Data, and then click 
OK. In the Create InfoSource for Transaction Data dialog box, in the lObject column for one 
of the rows in the list, select Create to open the Create New InfoObject dialog box. 





NOTE 


Each row in the table represents a column in the data flow of the package. 





d. To create an InfoObject while creating an InfoSource for master data, select InfoSource, and then 
click Create. In the Create InfoSource dialog box, select Master Data, and then click OK. In the 
Create InfoSource for Master Data dialog box, click New to open the Create New 


InfoObject dialog box. 


You can also open the Create New InfoObject dialog box by clicking New in the Attributes section of the 
Create New InfoObject dialog box. 


General Options 


Characteristic 
Create an InfoObject that represents dimension data. 


Key figure 
Create an InfoObject that represents fact data. 


InfoObject name 
Enter a name for the InfoObject. 


Short description 
Enter a short description for the InfoObject. 


Long description 
Enter a long description for the InfoObject. 


Has master data 
Indicate that the InfoObject contains master data in the form of attributes, texts, or hierarchies. 





NOTE 


Select this option if the InfoObject represents dimensional data and you have selected the Characteristic option. 





Allow lower-case characters 


Allow lower-case characters in the InfoObject data. 


Save & Activate 
Save and active the new InfoObject. 


Data Type Options 


CHAR - Character String 
Indicates that the InfoObject contains character data. 


NUMC - Numeric String 
Indicates that the InfoObject contains numeric data. 


DATS - Date (VYYYYMMDD) 
Indicates that the InfoObject contains date data. 


TIMS - Time (HHMMSS) 
Indicates that the InfoObject contains time data. 


Length 
Enter the length of the data. 


Text Options 


With Texts 
Indicate that the InfoObject contains texts. 


Short Text 


Indicates that the InfoObject contains short texts. 


Medium Text 
Indicates that the InfoObject contains medium texts. 


Long Text 
Indicates that the InfoObject contains long texts. 


Text Language-Dependent 
Indicates that the texts are language-dependent. 


Text Time-Dependent 
Indicates that the texts are time-dependent. 


Attributes Section 


The Attributes section consists of a list of attributes for the InfoObject, and the options that let you add and 
remove attributes from the list. 

Attributes List 

The Attributes list displays the attributes of the InfoObject that you are creating. The Attributes list has the 


following column headings: 


InfoObject 
View the name of the InfoObject. 


Description 
View the description of the InfoObject. 


InfoObject Type 
View the type of the InfoObject. The following table lists the possible values for the type. 


VALUE DESCRIPTION 

CHA Characteristics 

KYF Key figures 

UNI Units 

TIM Time characteristics 
Attributes Options 


Use the following options to add and remove attributes for the InfoObject that you are creating: 


Add 
Add an existing InfoObject as an attribute. 


To add an existing InfoObject, click Add, and then use the Look Up InfoObject dialog box to find the 
InfoObject. For more information about this dialog box, see Look Up InfoObject. 


New 
Add a new InfoObject as an attribute. 


To create and add a new InfoObject, click New, and then use a new instance of the Create New InfoObject 
dialog box to create the new InfoObject. 


Remove 


Remove the selected InfoObject from the Attributes list. 


See Also 


Create InfoCube for Transaction Data 
Create InfoSource 

Create InfoSource for Transaction Data 
Create InfoSource for Master Data 
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11/23/2021 * 2 minutes to read « Edit Online 





Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Use the Create InfoCube for Transaction Data dialog box to create a new InfoCube for transaction data in 
the SAP Netweaver BW system. 


You can open the Create InfoCube for Transaction Data dialog box from the Connection Manager page of 
the SAP BW Destination Editor. To learn more about the SAP BW destination, see SAP BW Destination. 





IMPORTANT 


The documentation for the Microsoft Connector 1.1 for SAP BW assumes familiarity with the SAP Netweaver BW 
environment. For more information about SAP Netweaver BW, or for information about how to configure SAP Netweaver 
BW objects and processes, see your SAP documentation. 











To open the Create InfoCube for Transaction Data dialog box 


1. In SQL Server Data Tools (SSDT), open the Integration Services package that contains the SAP BW 
destination. 


2. On the Data Flow tab, double-click the SAP BW destination. 


3. In the SAP BW Destination Editor, click Connection Manager to open the Connection Manager 
page of the editor. 


4. On the Connection Manager page, in the Create SAP BW Objects group box, select InfoCube, and 
then click Create. 


General Options 


InfoCube name 
Enter a name for the new InfoCube. 


Long description 
Enter a description for the new InfoCube. 


Save & Activate 
Save and activate the new InfoCube. 


InfoCube Transfer Structure Options 
The InfoCube transfer structure section lets you associate data flow columns to InfoObjects. 


PipelineElement 
Displays the column in the output of the data flow that is connected to the SAP BW destination. 


PipelineDataType 
Displays the data type of the data flow column. 


InfoObject 
Displays the name of the InfoObject that is associated with the data flow column. 


Type 
Displays the type of the InfoObject that is associated with the data flow column. The following table lists the 
possible values for the type. 


VALUE DESCRIPTION 

CHA Characteristics 

UNI Units 

KYF Key figures 

TIM Time characteristics 


lobject - Search 

Associate an existing InfoObject to the data flow column for the current row. To make this association, click 
Search, and then use the Look Up InfoObject dialog box to select the existing InfoObject. For more 
information about this dialog box, see Look Up InfoObject. 


After you select an existing InfoObject, the component populates the InfoObject and Type columns with the 
selected values. 


lobject - New 

Create a new InfoObject and associate this new InfoObject to the data flow column in the current row. To create 
the new InfoObject, click New, and then use the Create New InfoObject dialog box to create the InfoObject. 
For more information about this dialog box, see Create New InfoObject. 


After you create a new InfoObject, the component populates the InfoObject and Type columns with the new 
values. 


lobject - Remove 
Remove the association between the InfoObject and the data flow column for the current row. To remove this 
association, click Remove. 


See Also 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Use the Look Up InfoObject dialog box to look up an InfoObject that is defined in the SAP Netweaver BW 
system. When the list of available InfoObjects appears, select the InfoObject that you want, and the SAP BW 
destination will populate the associated options with the required values. 


The SAP BW destination of the Microsoft Connector 1.1 for SAP BW uses the Look Up InfoObject dialog box. 
To learn more about the SAP BW destination, see SAP BW Destination. 


IMPORTANT 


The documentation for the Microsoft Connector 1.1 for SAP BW assumes familiarity with the SAP Netweaver BW 
environment. For more information about SAP Netweaver BW, or for information about how to configure SAP Netweaver 


BW objects and processes, see your SAP documentation. 








To open the Look Up InfoObject dialog box 


1. In SQL Server Data Tools (SSDT), open the Integration Services package that contains the SAP BW 
destination. 


2. On the Data Flow tab, double-click the SAP BW destination. 


3. In the SAP BW Destination Editor, click Connection Manager to open the Connection Manager 
page of the editor. 


4. On the Connection Manager page, in the Create SAP BW Objects group box, select one of the 
following options: 


a. Select InfoCube. Then, click Create. In the Create InfoCube for Transaction Data dialog box, 
click Search in the |Object column for one of the rows in the list. Each row represents a column in 
the data flow of the package. 


b. Select InfoSource. Then click Create. In the Create InfoSource dialog box, select Transaction 
data. In the Create InfoSource for Transaction Data dialog box, click Search in the lObject 
column for one of the rows in the list. Each row represents a column in the data flow of the 
package. 


c. Select InfoSource. Then click Create. In the Create InfoSource dialog box, select Master data. 
In the Create InfoSource for Master Data dialog box, click Look up. 


You can also open the Look Up InfoObject dialog box by clicking Add in the Attributes section of the Create 
New InfoObject dialog box. 


Lookup Options 


In the lookup field text boxes, you can filter results by using the asterisk wildcard character (*), or by using a 
partial string in combination with the asterisk wildcard character. However, if you leave a lookup field empty, the 
lookup process will only match empty strings in that field. 


Characteristics 


Look up InfoObjects that represent characteristics. 


Units 
Look up InfoObjects that represent units. 


Key figures 
Look up InfoObjects that represent key figures. 


Time characteristics 
Look up InfoObjects that represent time characteristics. 


Name 
Enter the name of the InfoObject that you want to look up, or a partial name with the asterisk wildcard character 
(*). Or, use the asterisk wildcard character alone to include all InfoObjects. 


Description 
Enter the description, or a partial description with the asterisk wildcard character (*). Or, use the asterisk 
wildcard character alone to include all InfoObjects regardless of description. 


Look up 
Look up matching InfoObjects that are defined in the SAP Netweaver BW system. 


Lookup Results 


After you click the Look up button, a list of the InfoObjects in the SAP Netweaver BW system appears in a table 
with the following column headings. 


InfoObject 
Displays the name of the InfoObject that is defined in the SAP Netweaver BW system. 


Text (short) 
Displays the short text that is associated with the InfoObject. 


When the list of available InfoObjects appears, select the InfoObject that you want, and the destination will 
populate the associated options with the required values. 


See Also 


Create InfoCube for Transaction Data 

Create InfoSource 

Create InfoSource for Transaction Data 

Create InfoSource for Master Data 

Create New InfoObject 

SAP BW Destination Editor (Connection Manager Page) 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Use the Create InfoSource dialog box to create a new InfoSource. To create the new InfoSource, you use either 
the Create InfoSource for Transaction Data or the Create InfoSource for Master Data dialog box. 


You can open the Create InfoSource dialog box from the Connection Manager page of the SAP BW 
Destination Editor. To learn more about the SAP BW destination, see SAP BW Destination. 





IMPORTANT 
The documentation for the Microsoft Connector 1.1 for SAP BW assumes familiarity with the SAP Netweaver BW 


environment. For more information about SAP Netweaver BW, or for information about how to configure SAP Netweaver 


BW objects and processes, see your SAP documentation. 











To open the Create InfoSource dialog box 


1. In SQL Server Data Tools (SSDT), open the Integration Services package that contains the SAP BW 
destination. 


2. On the Data Flow tab, double-click the SAP BW destination. 


3. In the SAP BW Destination Editor, click Connection Manager to open the Connection Manager 
page of the editor. 


4. On the Connection Manager page, in the Create SAP BW Objects group box, select InfoSource, and 
then click Create. 


Options 


Transaction data 
Create a new InfoSource for transaction data. 


If you select this option, the Create InfoSource for Transaction Data dialog box opens. You use the Create 
InfoSource for Transaction Data dialog box to create the new InfoSource. For more information about this 
dialog box, see Create InfoSource for Transaction Data. 


Master data 
Create a new InfoSource for master data. 


If you select this option, the Create InfoSource for Master Data dialog box opens. You use the Create 
InfoSource for Master Data dialog box to create the new InfoSource. For more information about this dialog 
box, see Create InfoSource for Master Data. 


See Also 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Use the Create InfoSource for Transaction Data dialog box to create a new InfoSource for transaction data 
in the SAP Netweaver BW system. 


You can open the Create InfoSource for Transaction Data dialog box from the Connection Manager page 
of the SAP BW Destination Editor. To learn more about the SAP BW destination, see SAP BW Destination. 





IMPORTANT 
The documentation for the Microsoft Connector 1.1 for SAP BW assumes familiarity with the SAP Netweaver BW 
environment. For more information about SAP Netweaver BW, or for information about how to configure SAP Netweaver 


BW objects and processes, see your SAP documentation. 











To open the Create InfoSource for Transaction Data dialog box 


1. In SQL Server Data Tools (SSDT), open the Integration Services package that contains the SAP BW 
destination. 


2. On the Data Flow tab, double-click the SAP BW destination. 


3. In the SAP BW Destination Editor, click Connection Manager to open the Connection Manager 
page of the editor. 


4. On the Connection Manager page, in the Create SAP BW Objects group box, select InfoSource, and 
then click Create. 


5. Inthe Create InfoSource dialog box, select Transaction data, and then click OK. 


General Options 


InfoSource name 


Enter a name for the new InfoSource. 


Short description 
Enter a short description for the new InfoSource. 


Long description 
Enter a long description for the new InfoSource. 


Source system 
Select the source system associated with the InfoSource. 


Save & Activate 
Save and activate the new InfoSource. 


InfoSource Transfer Structure Options 
The InfoSource transfer structure lets you associate data flow columns to InfoSources. 


PipelineElement 


Displays the column in the output of the data flow that is connected to the SAP BW destination. 


PipelineDataType 
Displays the Integration Services data type of the data flow column. 


lobject - Search 

Associate an existing InfoObject to the data flow column in the current row. To make this association, click 
Search, and then use the Look Up InfoObject dialog box to select the existing InfoObject. For more 
information about this dialog box, see Look Up InfoObject. 


After you select an existing InfoObject, the component populates the InfoObject and Type columns with the 
selected values. 


lobject - New 

Create a new InfoObject and associate this new InfoObect to the data flow column in the current row. To create 
the new InfoObject, click New, and then use the Create New InfoObject dialog box to create the InfoObject. 
For more information about this dialog box, see Create New InfoObject. 


After you create a new InfoObject, the component populates the InfoObject and Type columns with the new 
values. 


lobject - Remove 
Remove the association between the InfoObject and the data flow column for the current row. To remove this 


association, click Remove. 


InfoObject 
Displays the name of the InfoObject that is associated with the data flow column. 


Type 
Displays the type of the InfoObject that is associated with the data flow column. The following table lists the 
possible values for the type. 


VALUE DESCRIPTION 

CHA Characteristics 

UNI Units 

KYF Key figures 

TIM Time characteristics 
Unit Field 


Specify the units that the InfoObject will use. 


See Also 


Create InfoSource 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Use the Create InfoSource for Master Data dialog box to create a new InfoSource for master data in the SAP 
Netweaver BW system. 


You can open the Create InfoSource for Master Data dialog box from the Connection Manager page of 
the SAP BW Destination Editor. To learn more about the SAP BW destination, see SAP BW Destination. 





IMPORTANT 
The documentation for the Microsoft Connector 1.1 for SAP BW assumes familiarity with the SAP Netweaver BW 


environment. For more information about SAP Netweaver BW, or for information about how to configure SAP Netweaver 
BW objects and processes, see your SAP documentation. 











To open the Create InfoSource for Master Data dialog box 


1. In SQL Server Data Tools (SSDT), open the Integration Services package that contains the SAP BW 
destination. 


2. On the Data Flow tab, double-click the SAP BW destination. 


3. In the SAP BW Destination Editor, click Connection Manager to open the Connection Manager 
page of the editor. 


4. On the Connection Manager page, in the Create SAP BW Objects group box, select InfoSource, and 
then click Create. 


5. Inthe Create InfoSource dialog box, select Master data, and then click OK. 


Options 


InfoObject name 
Enter the name of the InfoObject on which the new InfoSource should be based. 


Look up 
Look up the InfoObject. This option opens the Look Up InfoObject dialog box in which you can select the 
InfoObject. For more information about this dialog box, see Look Up InfoObject. 


After you select an InfoObject, the component populates the InfoObject name text box with the name of the 
selected InfoObject. 


New 
Create a new InfoObject. This option opens the Create New InfoObject dialog box in which you can create the 
new InfoObject. For more information about this dialog box, see Create New InfoObject. 


After you create an InfoObject, the component populates the InfoObject name text box with the name of the 
new InfoObject. 


Short description 
Enter a short description for the new InfoSource. 


Long description 
Enter a long description for the new InfoSource. 


Source system 
Select the source system to be associated with the new InfoSource. 


Application 
Enter the name of the application to be associated with the new InfoSource. 


Attributes 
Indicates that the master data consists of attributes. 


Texts 
Indicates that the master data consists of attributes. 


Save & Activate 
Save and activate the new InfoSource. 


See Also 


Create InfoSource 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 
Use the Create InfoPackage dialog box to create a new InfoPackage in the SAP Netweaver BW system. 


You can open the Create InfoPackage dialog box from the Connection Manager page of the SAP BW 
Destination Editor. To learn more about the SAP BW destination, see SAP BW Destination. 


IMPORTANT 
The documentation for the Microsoft Connector 1.1 for SAP BW assumes familiarity with the SAP Netweaver BW 
environment. For more information about SAP Netweaver BW, or for information about how to configure SAP Netweaver 


BW objects and processes, see your SAP documentation. 








To open the Create InfoPackage dialog box 


1. In SQL Server Data Tools (SSDT), open the Integration Services package that contains the SAP BW 
destination. 


2. On the Data Flow tab, double-click the SAP BW destination. 


3. In the SAP BW Destination Editor, click Connection Manager to open the Connection Manager 
page of the editor. 


4. On the Connection Manager page, in the Create SAP BW Objects group box, select InfoPackage, 
and then click Create. 


Options 


InfoSource 
Enter the name of the InfoSource on which the new InfoPackage should be based. 


Short description 
Enter a description for the new InfoPackage. 


Source system 
Select the source system with which the new InfoPackage should be associated. 


Attributes 
Indicates that the InfoPackage will load attribute data. 


Texts 
Indicates that the InfoPackage will load text data. 


Transaction 
Indicates that the InfoPackage will load transaction data. 


Save & Activate 
Save and activate the new InfoPackage. 


See Also 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


The SQL Server Compact destination writes data to SQL Server Compact databases. 


NOTE 


On a 64-bit computer, you must run packages that connect to SQL Server Compact data sources in 32-bit mode. The 
SQL Server Compact provider that Integration Services uses to connect to SQL Server Compact data sources is available 
only in a 32-bit version. 





You configure the SQL Server Compact destination by specifying the name of the table into which the SQL 
Server Compact destination inserts the data. The custom property TableName of the SQL Server Compact 
destination contains the table name. 


This destination uses an SQL Server Compact connection manager to connect to a data source, and the 
connection manager specifies the OLE DB provider to use. For more information, see SQL Server Compact 
Edition Connection Manager. 


The SQL Server Compact destination includes the TableName custom property, which can be updated by a 
property expression when the package is loaded. For more information, see Integration Services (SSIS) 
Expressions, Use Property Expressions in Packages, and SQL Server Compact Edition Destination Custom 
Properties. 


The SQL Server Compact destination has one input and does not support an error output. 


Configuration of the SQL Server Compact Edition Destination 
You can set properties through SSIS Designer or programmatically. 


The Advanced Editor dialog box reflects the properties that can be set programmatically. For more 
information about the properties that you can set in the Advanced Editor dialog box or programmatically, click 
one of the following topics: 


@ Common Properties 


e SQL Server Destination Custom Properties 


Related Tasks 


For more information about how to set properties of this component, see Set the Properties of a Data Flow 
Component. 


See Also 


Data Flow 
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Applies to: Q sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


The SQL Server Compact destination has both custom properties and the properties common to all data flow 
components. 


The following table describes the custom properties of the SQL Server Compact destination. All properties are 
read/write. 


PROPERTY NAME DATA TYPE DESCRIPTION 


TableName String The name of the destination table in a 
SQL Server Compact database. 


The value of this property can be 


specified by using a property 
expression. 


The input and the input columns of the SQL Server Compact destination have no custom properties. 


For more information, see SQL Server Compact Edition Destination. 


See Also 


Common Properties 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


The SQL Server destination connects to a local SQL Server database and bulk loads data into SQL Server tables 
and views. You cannot use the SQL Server destination in packages that access a SQL Server database on a 
remote server. Instead, the packages should use the OLE DB destination. For more information, see OLE DB 
Destination. 


Permissions 


Users who execute packages that include the SQL Server destination require the "Create global objects" 
permission. You can grant this permission to users by using the Local Security Policy tool opened from the 
Administrative Tools menu. If you receive an error message when executing a package that uses the SQL 
Server destination, make sure that the account running the package has the "Create global objects" permission. 


Bulk Inserts 


If you attempt to use the SQL Server destination to bulk load data into a remote SQL Server database, you may 
see an error message similar to the following: "An OLE DB record is available. Source: "Microsoft SQL Server 
Native Client" Hresult: 0x80040E14 Description: "Could not bulk load because SSIS file mapping object 
'Global\DTSQLIMPORT ' could not be opened. Operating system error code 2 (The system cannot find the file 


specified.). Make sure you are accessing a local server via Windows security. 


The SQL Server destination offers the same high-speed insertion of data into SQL Server that the Bulk Insert 
task provides; however, by using the SQL Server destination, a package can apply transformations to column 
data before the data is loaded into SQL Server. 


For loading data into SQL Server, you should consider using the SQL Server destination instead of the OLE DB 
destination. 


Bulk Insert Options 


If the SQL Server destination uses a fast-load data access mode, you can specify the following fast load options: 
e Retain identity values from the imported data file, or use unique values assigned by SQL Server. 

e Retain null values during the bulk load operation. 

e Verify constraints on the target table or view during the bulk import operation. 

e Acquire a table-level lock for the duration of the bulk load operation. 

e Execute insert triggers defined on the destination table during the bulk load operation. 

e Specify the number of the first row in the input to load during the bulk insert operation. 

e Specify the number of the last row in the input to load during the bulk insert operation. 


e@ Specify the maximum number of errors allowed before the bulk load operation is canceled. Each row that 
cannot be imported is counted as one error. 


e@ Specify the columns in the input that contain sorted data. 


For more information about bulk load options, see BULK INSERT (Transact-SQL). 


Performance Improvements 


To improve the performance of a bulk insert and the access to table data during the bulk insert operation, you 
should change the default options as follows: 


e Do not verify constraints on the target table or view during the bulk import operation. 
e Do not execute insert triggers defined on the destination table during the bulk load operation. 


e Do not apply a lock to the table. That way, the table remains available to other users and applications 
during the bulk insert operation. 


Configuration of the SQL Server Destination 


You can configure the SQL Server destination in the following ways: 

e Specify the table or view into which to bulk load the data. 

e Customize the bulk load operation by specifying options such as whether to check constraints. 

e Specify whether all rows commit in one batch or set the maximum number of rows to commit as a batch. 
e Specify a time-out for the bulk load operation. 


This destination uses an OLE DB connection manager to connect to a data source, and the connection manager 
specifies the OLE DB provider to use. For more information, see OLE DB Connection Manager. 


An Integration Services project also provides the data source object from which you can create an OLE DB 
connection manager. This makes data sources and data source views available to the SQL Server destination. 


The SQL Server destination has one input. It does not support an error output. 
You can set properties through SSIS Designer or programmatically. 


The Advanced Editor dialog box reflects the properties that can be set programmatically. For more 
information about the properties that you can set in the Advanced Editor dialog box or programmatically, click 
one of the following topics: 


@ Common Properties 

e SQL Server Destination Custom Properties 

For more information about how to set properties, click one of the following topics: 
e Bulk Load Data by Using the SQL Server Destination 


e Set the Properties of a Data Flow Component 


Related Tasks 
e Bulk Load Data by Using the SQL Server Destination 


e Set the Properties of a Data Flow Component 


Related Content 


@ Technical article, You may get "Unable to prepare the SSIS bulk insert for data insertion" error on UAC 
enabled systems, on support.microsoft.com. 


e Technical article, The Data Loading Performance Guide, on msdn.microsoft.com. 


e Technical article, Using SQL Server Integration Services to Bulk Load Data, on simple-talk.com. 


SQL Destination Editor (Connection Manager Page) 


Use the Connection Manager page of the SQL Destination Editor dialog box to specify data source 
information, and to preview the results. The SQL Server destination loads data into tables or views in a 
Microsoft SQL Server database. 


Options 
OLE DB connection manager 


Select an existing connection from the list, or create a new connection by clicking New. 


New 
Create a new connection by using the Configure OLE DB Connection Manager dialog box. 


Use a table or view 
Select an existing table or view from the list, or create a new connection by clicking New. 


New 
Create a new table by using the Create Table dialog box. 





NOTE 

When you click New, Integration Services generates a default CREATE TABLE statement based on the connected data 
source. This default CREATE TABLE statement will not include the FILESTREAM attribute even if the source table includes a 
column with the FILESTREAM attribute declared. To run an Integration Services component with the FILESTREAM 
attribute, first implement FILESTREAM storage on the destination database. Then, add the FILESTREAM attribute to the 
CREATE TABLE statement in the Create Table dialog box. For more information, see Binary Large Object (Blob) Data (SQL 
Server). 











Preview 
Preview results by using the Preview Query Results dialog box. Preview can display up to 200 rows. 


SQL Destination Editor (Mappings Page) 


Use the Mappings page of the SQL Destination Editor dialog box to map input columns to destination 


columns. 


Options 
Available Input Columns 
View the list of available input columns. Use a drag-and-drop operation to map available input columns in the 


table to destination columns. 


Available Destination Columns 
View the list of available destination columns. Use a drag-and-drop operation to map available destination 
columns in the table to input columns. 


Input Column 
View input columns selected from the table above. You can change the mappings by using the list of Available 
Input Columns. 


Destination Column 
View each available destination column, whether it is mapped or not. 


SQL Destination Editor (Advanced Page) 


Use the Advanced page of the SQL Destination Editor dialog box to specify advanced bulk insert options. 


Options 
Keep identity 
Specify whether the task should insert values into identity columns. The default value of this property is False. 


Keep nulls 
Specify whether the task should keep null values. The default value of this property is False. 


Table lock 
Specify whether the table is locked when the data is loaded. The default value of this property is True. 


Check constraints 
Specify whether the task should check constraints. The default value of this property is True. 


Fire triggers 
Specify whether the bulk insert should fire triggers on tables. The default value of this property is False. 


First Row 
Specify the first row to insert. The default value of this property is -1, indicating that no value has been 
assigned. 





NOTE 


Clear the text box in the SQL Destination Editor to indicate that you do not want to assign a value for this property. 
Use -1 in the Properties window, the Advanced Editor, and the object model. 











Last Row 
Specify the last row to insert. The default value of this property is -1, indicating that no value has been assigned. 





NOTE 


Clear the text box in the SQL Destination Editor to indicate that you do not want to assign a value for this property. 
Use -1 in the Properties window, the Advanced Editor, and the object model. 











Maximum number of errors 
Specify the number of errors that can occur before the bulk insert stops. The default value of this property is -1, 
indicating that no value has been assigned. 


NOTE 


Clear the text box in the SQL Destination Editor to indicate that you do not want to assign a value for this property. 


Use -1 in the Properties window, the Advanced Editor, and the object model. 





Timeout 
Specify the number of seconds to wait before the bulk insert stops because of a time-out. 


Order columns 
Type the names of the sort columns. Each column can be sorted in ascending or descending order. If you use 
multiple sort columns, delimit the list with commas. 


See Also 


Data Flow 


Bulk Load Data by Using the SQL Server 
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Applies to: Q sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


To add and configure a SQL Server destination, the package must already include at least one Data Flow task 
and a data source. 


To load data using a SQL Server destination 


1. In SQL Server Data Tools (SSDT), open the Integration Services project that contains the package you 
want. 


2. In Solution Explorer, double-click the package to open it. 


3. Click the Data Flow tab, and then, from the Toolbox, drag the SQL Server destination to the design 
surface. 


4. Connect the destination to a source or a previous transformation in the data flow by dragging a 
connector to the destination. 


5. Double-click the destination. 


6. Inthe SQL Server Destination Editor, on the Connection Manager page, select an existing OLE DB 
connection manager or click New to create a new connection manager. For more information, see OLE 
DB Connection Manager. 


7. To specify the table or view into which to load the data, do one of the following: 
e Select an existing table or view. 


e Click New, and in the Create Table dialog boxwrite an SQL statement that creates a table or view. 





NOTE 


Integration Services generates a default CREATE TABLE statement based on the connected data source. 
This default CREATE TABLE statement will not include the FILESTREAM attribute even if the source table 
includes a column with the FILESTREAM attribute declared. To run an Integration Services component with 
the FILESTREAM attribute, first implement FILESTREAM storage on the destination database. Then, add 
the FILESTREAM attribute to the CREATE TABLE statement in the Create Table dialog box. For more 
information, see Binary Large Object (Blob) Data (SQL Server). 











8. Click Mappings and map columns from the Available Input Columns list to columns in the Available 


Destination Columns list by dragging columns from one list to another. 





NOTE 


The destination automatically maps same-named columns. 





9. Click Advanced and set the bulk load options: Keep identity, Keep nulls, Table lock, Check 
constraints, and Fire triggers. 


Optionally, specify the first and last input rows to insert, the maximum number of errors that can occur 
before the insert operation stops, and the columns on which the insert is sorted. 





NOTE 


The sort order is determined by the order in which the columns are listed. 





10. Click OK. 


11. To save the updated package, click Save Selected Items on the File menu. 


See Also 


SQL Server Destination 

Integration Services Transformations 
Integration Services Paths 

Data Flow Task 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


The SQL Server destination has both custom properties and the properties common to all data flow 
components. 


The following table describes the custom properties of the SQL Server destination. All properties are read/write. 


PROPERTY NAME DATA TYPE DESCRIPTION 


AlwaysUseDefaultCodePage Boolean Forces the use of the DefaultCodePage 
property value. The default value of 
this property is False. 


BulklnsertCheckConstraints Boolean A value that specifies whether the bulk 
insert checks constraints. The default 
value of this property is True. 


BulkinsertFireTriggers Boolean A value that specifies whether the bulk 
insert fires triggers on tables. The 
default value of this property is False. 


BulkinsertFirstRow Integer A value that specifies the first row to 
insert. The default value of this 
property is -1, which indicates that no 
value has been assigned 


BulkinsertKeepldentity Boolean A value that specifies whether values 
can be inserted into identity columns. 
The default value of this property is 
False. 


BulkiInsertKeepNulls Boolean A value that specifies whether the bulk 
insert keeps Null values. The default 
value of this property is False. 


BulkinsertLastRow Integer A value that specifies the last row to 
insert. The default value of this 
property is -1, which indicates that no 
value has been assigned. 


BulkInsertMaxErrors Integer A value that specifies the number of 
errors that can occur before the bulk 
insert stops. The default value of this 
property is -1, which indicates that no 
value has been assigned. 


BulkinsertOrder String The names of the sort columns. Each 
column can be sorted in ascending or 
descending order. If multiple sort 
columns are used, the column names 
are separated by commas. 


PROPERTY NAME 


BulklnsertTableName 


BulklnsertTablock 


DefaultCodePage 


MaxiInsertCommitSize 


Timeout 


DATA TYPE 


String 


Boolean 


Integer 


Integer 


Integer 


DESCRIPTION 


The SQL Server table or view in the 
database to which the data is copied. 


A value that specifies whether the 
table is locked during the bulk insert. 
The default value of this property is 
True. 


The code page to use when code page 
information is not available from the 
data source. 


A value that specifies the maximum 
number of rows to insert in a batch. 
When the value is zero, all rows are 
inserted in a single batch. 


A value that specifies the number of 
seconds the SQL Server destination 
waits before termination if there is no 
data available for insertion. A value of 
0 means that the SQL Server 
destination will not time out. The 
default value of this property is 30. 


The input and the input columns of the SQL Server destination have no custom properties. 


For more information, see SQL Server Destination. 


See Also 


Common Properties 
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Applies to: Q sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


SQL Server Integration Services transformations are the components in the data flow of a package that 
aggregate, merge, distribute, and modify data. Transformations can also perform lookup operations and 
generate sample datasets. This section describes the transformations that Integration Services includes and 
explains how they work. 


Business Intelligence Transformations 


The following transformations perform business intelligence operations such as cleaning data, mining text, and 
running data mining prediction queries. 


TRANSFORMATION DESCRIPTION 


Slowly Changing Dimension Transformation The transformation that configures the updating of a slowly 
changing dimension. 


Fuzzy Grouping Transformation The transformation that standardizes values in column data. 


Fuzzy Lookup Transformation The transformation that looks up values in a reference table 
using a fuzzy match. 


Term Extraction Transformation The transformation that extracts terms from text. 


Term Lookup Transformation The transformation that looks up terms in a reference table 
and counts terms extracted from text. 


Data Mining Query Transformation The transformation that runs data mining prediction queries. 

DQS Cleansing Transformation The transformation that corrects data from a connected data 
source by applying rules that were created for the data 
source. 


Row Transformations 


The following transformations update column values and create new columns. The transformation is applied to 
each row in the transformation input. 


TRANSFORMATION DESCRIPTION 

Character Map Transformation The transformation that applies string functions to character 
data. 

Copy Column Transformation The transformation that adds copies of input columns to the 


transformation output. 


Data Conversion Transformation The transformation that converts the data type of a column 
to a different data type. 


TRANSFORMATION 


Derived Column Transformation 


Export Column Transformation 


Import Column Transformation 


Script Component 


OLE DB Command Transformation 


Rowset Transformations 


DESCRIPTION 


The transformation that populates columns with the results 
of expressions. 


The transformation that inserts data from a data flow into a 
file. 


The transformation that reads data from a file and adds it to 
a data flow. 


The transformation that uses script to extract, transform, or 
load data. 


The transformation that runs SQL commands for each row in 
a data flow. 


The following transformations create new rowsets. The rowset can include aggregate and sorted values, sample 


rowsets, or pivoted and unpivoted rowsets. 


TRANSFORMATION 


Aggregate Transformation 


Sort Transformation 


Percentage Sampling Transformation 


Row Sampling Transformation 


Pivot Transformation 


Unpivot Transformation 


Split and Join Transformations 


DESCRIPTION 


The transformation that performs aggregations such as 
AVERAGE, SUM, and COUNT. 


The transformation that sorts data. 


The transformation that creates a sample data set using a 
percentage to specify the sample size. 


The transformation that creates a sample data set by 
specifying the number of rows in the sample. 


The transformation that creates a less normalized version of 
a normalized table. 


The transformation that creates a more normalized version 
of a nonnormalized table. 


The following transformations distribute rows to different outputs, create copies of the transformation inputs, 


join multiple inputs into one output, and perform lookup operations. 


TRANSFORMATION 


Conditional Split Transformation 


DESCRIPTION 


The transformation that routes data rows to different 
outputs. 


TRANSFORMATION 


Multicast Transformation 


Union All Transformation 
Merge Transformation 


Merge Join Transformation 
Lookup Transformation 


Cache Transform 


Balanced Data Distributor Transformation 


Auditing Transformations 


DESCRIPTION 


The transformation that distributes data sets to multiple 
outputs. 


The transformation that merges multiple data sets. 


The transformation that merges two sorted data sets. 


The transformation that joins two data sets using a FULL, 
LEFT, or INNER join. 


The transformation that looks up values in a reference table 
using an exact match. 


The transformation that writes data from a connected data 
source in the data flow to a Cache connection manager that 
saves the data to a cache file. The Lookup transformation 
performs lookups on the data in the cache file. 


The transformation distributes buffers of incoming rows 
uniformly across outputs on separate threads to improve 
performance of SSIS packages running on multi-core and 
multi-processor servers. 


Integration Services includes the following transformations to add audit information and count rows. 


TRANSFORMATION 


Audit Transformation 


Row Count Transformation 


Custom Transformations 


DESCRIPTION 


The transformation that makes information about the 
environment available to the data flow in a package. 


The transformation that counts rows as they move through 
it and stores the final count in a variable. 


You can also write custom transformations. For more information, see Developing a Custom Transformation 


Component with Synchronous Outputs and Developing a Custom Transformation Component with 


Asynchronous Outputs. 


Aggregate Transformation 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


The Aggregate transformation applies aggregate functions, such as Average, to column values and copies the 
results to the transformation output. Besides aggregate functions, the transformation provides the GROUP BY 
clause, which you can use to specify groups to aggregate across. 


Operations 


The Aggregate transformation supports the following operations. 


OPERATION DESCRIPTION 


Group by Divides datasets into groups. Columns of any data type can 
be used for grouping. For more information, see GROUP BY 
(Transact-SQL). 


Sum Sums the values in a column. Only columns with numeric 
data types can be summed. For more information, see SUM 
(Transact-SQL). 


Average Returns the average of the column values in a column. Only 
columns with numeric data types can be averaged. For more 
information, see AVG (Transact-SQL). 


Count Returns the number of items in a group. For more 
information, see COUNT (Transact-SQL). 


Count distinct Returns the number of unique nonnull values in a group. 


Minimum Returns the minimum value in a group. For more 
information, see MIN (Transact-SQL). In contrast to the 
Transact-SQL MIN function, this operation can be used only 
with numeric, date, and time data types. 


Maximum Returns the maximum value in a group. For more 
information, see MAX (Transact-SQL). In contrast to the 
Transact-SQL MAX function, this operation can be used only 
with numeric, date, and time data types. 


The Aggregate transformation handles null values in the same way as the SQL Server relational database 
engine. The behavior is defined in the SQL-92 standard. The following rules apply: 


e Ina GROUP BY clause, nulls are treated like other column values. If the grouping column contains more 
than one null value, the null values are put into a single group. 


e@ Inthe COUNT (column name) and COUNT (DISTINCT column name) functions, nulls are ignored and the 
result excludes rows that contain null values in the named column. 


e@ Inthe COUNT (*) function, all rows are counted, including rows with null values. 


Big Numbers in Aggregates 


A column may contain numeric values that require special consideration because of their large value or 
precision requirements. The Aggregation transformation includes the IsBig property, which you can set on 
output columns to invoke special handling of big or high-precision numbers. If a column value may exceed 4 
billion or a precision beyond a float data type is required, IsBig should be set to 1. 


Setting the IsBig property to 1 affects the output of the aggregation transformation in the following ways: 
e The DT_R8 data type is used instead of the DT_R4 data type. 
e Count results are stored as the DT_UI8 data type. 


e Distinct count results are stored as the DT_UI4 data type. 





NOTE 


You cannot set IsBig to 1 on columns that are used in the GROUP BY, Maximum, or Minimum operations. 











Performance Considerations 


The Aggregate transformation includes a set of properties that you can set to enhance the performance of the 
transformation. 


e When performing a Group by operation, set the Keys or KeysScale properties of the component and the 
component outputs. Using Keys, you can specify the exact number of keys the transformation is expected 
to handle. (In this context, Keys refers to the number of groups that are expected to result from a Group 
by operation.) Using KeysScale, you can specify an approximate number of keys. When you specify an 
appropriate value for Keys or KeyScale, you improve performance because the tranformation is able to 


allocate adequate memory for the data that the transformation caches. 


e When performing a Distinct count operation, set the CountDistinctKeys or CountDistinctScale 
properties of the component. Using CountDistinctKeys, you can specify the exact number of keys the 
transformation is expected to handle for a count distinct operation. (In this context, CountDistinctKeys 
refers to the number of distinct values that are expected to result from a Distinct count operation.) 
Using CountDistinctScale, you can specify an approximate number of keys for a count distinct operation. 
When you specify an appropriate value for CountDistinctkeys or CountDistinctScale, you improve 
performance because the transformation is able to allocate adequate memory for the data that the 
transformation caches. 


Aggregate Transformation Configuration 


You configure the Aggregate transformation at the transformation, output, and column levels. 


e At the transformation level, you configure the Aggregate transformation for performance by specifying 
the following values: 


o The number of groups that are expected to result from a Group by operation. 
o The number of distinct values that are expected to result from a Count distinct operation. 
o The percentage by which memory can be extended during the aggregation. 


The Aggregate transformation can also be configured to generate a warning instead of failing when the 
value of a divisor is zero. 


e At the output level, you configure the Aggregate transformation for performance by specifying the 


number of groups that are expected to result from a Group by operation. The Aggregate transformation 
supports multiple outputs, and each can be configured differently. 


e At the column level, you specify the following values: 

© The aggregation that the column performs. 

© The comparison options of the aggregation. 
You can also configure the Aggregate transformation for performance by specifying these values: 
e The number of groups that are expected to result from a Group by operation on the column. 


e The number of distinct values that are expected to result from a Count distinct operation on the 
column. 


You can also identify columns as IsBig if a column contains large numeric values or numeric values with high 
precision. 


The Aggregate transformation is asynchronous, which means that it does not consume and publish data row by 
row. Instead it consumes the whole rowset, performs its groupings and aggregations, and then publishes the 
results. 


This transformation does not pass through any columns, but creates new columns in the data flow for the data it 
publishes. Only the input columns to which aggregate functions apply or the input columns the transformation 
uses for grouping are copied to the transformation output. For example, an Aggregate transformation input 
might have three columns: CountryRegion, City, and Population. The transformation groups by the 
CountryRegion column and applies the Sum function to the Population column. Therefore the output does 
not include the City column. 


You can also add multiple outputs to the Aggregate transformation and direct each aggregation to a different 
output. For example, if the Aggregate transformation applies the Sum and the Average functions, each 
aggregation can be directed to a different output. 


You can apply multiple aggregations to a single input column. For example, if you want the sum and average 
values for an input column named Sales, you can configure the transformation to apply both the Sum and 
Average functions to the Sales column. 


The Aggregate transformation has one input and one or more outputs. It does not support an error output. 
You can set properties through SSIS Designer or programmatically. 


The Advanced Editor dialog box reflects the properties that can be set programmatically. For more 
information about the properties that you can set in the Advanced Editor dialog box or programmatically, click 
one of the following topics: 


e Common Properties 

e Transformation Custom Properties 

For more information about how to set properties, click one of the following topics: 
e Aggregate Values in a Dataset by Using the Aggregate Transformation 

e Set the Properties of a Data Flow Component 


e Sort Data for the Merge and Merge Join Transformations 


Related Tasks 


Aggregate Values in a Dataset by Using the Aggregate Transformation 


Aggregate Transformation Editor (Aggregations Tab) 


Use the Aggregations tab of the Aggregate Transformation Editor dialog box to specify columns for 
aggregation and aggregation properties. You can apply multiple aggregations. This transformation does not 
generate an error output. 


NOTE 


The options for key count, key scale, distinct key count, and distinct key scale apply at the component level when specified 
on the Advanced tab, at the output level when specified in the advanced display of the Aggregations tab, and at the 


column level when specified in the column list at the bottom of the Aggregations tab. 


In the Aggregate transformation, Keys and Keys scale refer to the number of groups that are expected to result from a 
Group by operation. Count distinct keys and Count distinct scale refer to the number of distinct values that are 


expected to result from a Distinct count operation. 











Options 

Advanced / Basic 

Display or hide options to configure multiple aggregations for multiple outputs. By default, the Advanced 
options are hidden. 


Aggregation Name 
In the Advanced display, type a friendly name for the aggregation. 


Group By Columns 
In the Advanced display, select columns for grouping by using the Available Input Columns list as described 
below. 


Key Scale 

In the Advanced display, optionally specify the approximate number of keys that the aggregation can write. By 
default, the value of this option is Unspecified. If both the Key Scale and Keys properties are set, the value of 
Keys takes precedence. 


VALUE DESCRIPTION 

Unspecified The Key Scale property is not used. 

Low Aggregation can write approximately 500,000 keys. 

Medium Aggregation can write approximately 5,000,000 keys. 

High Aggregation can write more than 25,000,000 keys. 
Keys 


In the Advanced display, optionally specify the exact number of keys that the aggregation can write. If both Key 
Scale and Keys are specified, Keys takes precedence. 


Available Input Columns 
Select from the list of available input columns by using the check boxes in this table. 


Input Column 
Select from the list of available input columns. 


Output Alias 
Type an alias for each column. The default is the name of the input column; however, you can choose any unique, 


descriptive name. 


Operation 
Choose from the list of available operations, using the following table as a guide. 


OPERATION DESCRIPTION 

GroupBy Divides datasets into groups. Columns with any data type 
can be used for grouping. For more information, see GROUP 
BY. 

Sum Sums the values in a column. Only columns with numeric 


data types can be summed. For more information, see SUM. 


Average Returns the average of the column values in a column. Only 
columns with numeric data types can be averaged. For more 
information, see AVG. 


Count Returns the number of items in a group. For more 
information, see COUNT. 


CountDistinct Returns the number of unique nonnull values in a group. For 
more information, see COUNT and Distinct. 


Minimum Returns the minimum value in a group. Restricted to numeric 
data types. 
Maximum Returns the maximum value in a group. Restricted to 


numeric data types. 


Comparison Flags 
If you choose Group By, use the check boxes to control how the transformation performs the comparison. For 
information on the string comparison options, see Comparing String Data. 


Count Distinct Scale 

Optionally specify the approximate number of distinct values that the aggregation can write. By default, the 
value of this option is Unspecified. If both CountDistinctScale and CountDistinctKeys are specified, 
CountDistinctKeys takes precedence. 


VALUE DESCRIPTION 

Unspecified The CountDistinctScale property is not used. 

Low Aggregation can write approximately 500,000 distinct 
values. 

Medium Aggregation can write approximately 5,000,000 distinct 
values. 

High Aggregation can write more than 25,000,000 distinct values. 


Count Distinct Keys 
Optionally specify the exact number of distinct values that the aggregation can write. If both 
CountDistinctScale and CountDistinctKeys are specified, CountDistinctKeys takes precedence. 


Aggregate Transformation Editor (Advanced Tab) 


Use the Advanced tab of the Aggregate Transformation Editor dialog box to set component properties, 


specify aggregations, and set properties of input and output columns. 


NOTE 
The options for key count, key scale, distinct key count, and distinct key scale apply at the component level when specified 
on the Advanced tab, at the output level when specified in the advanced display of the Aggregations tab, and at the 


column level when specified in the column list at the bottom of the Aggregations tab. 


In the Aggregate transformation, Keys and Keys scale refer to the number of groups that are expected to result from a 
Group by operation. Count distinct keys and Count distinct scale refer to the number of distinct values that are 


expected to result from a Distinct count operation. 





Options 

Keys scale 

Optionally specify the approximate number of keys that the aggregation expects. The transformation uses this 
information to optimize its initial cache size. By default, the value of this option is Unspecified. If both Keys 
scale and Number of keys are specified, Number of keys takes precedence. 


VALUE DESCRIPTION 

Unspecified The Keys scale property is not used. 

Low Aggregation can write approximately 500,000 keys. 
Medium Aggregation can write approximately 5,000,000 keys. 
High Aggregation can write more than 25,000,000 keys. 


Number of keys 

Optionally specify the exact number of keys that the aggregation expects. The transformation uses this 
information to optimize its initial cache size. If both Keys scale and Number of keys are specified, Number 
of keys takes precedence. 


Count distinct scale 

Optionally specify the approximate number of distinct values that the aggregation can write. By default, the 
value of this option is Unspecified. If both Count distinct scale and Count distinct keys are specified, 
Count distinct keys takes precedence. 


VALUE DESCRIPTION 

Unspecified The CountDistinctScale property is not used. 

Low Aggregation can write approximately 500,000 distinct 
values. 

Medium Aggregation can write approximately 5,000,000 distinct 
values. 

High Aggregation can write more than 25,000,000 distinct values. 


Count distinct keys 
Optionally specify the exact number of distinct values that the aggregation can write. If both Count distinct 
scale and Count distinct keys are specified, Count distinct keys takes precedence. 


Auto extend factor 





Use a value between 1 and 100 to specify the percentage by which memory can be extended during the 
aggregation. By default, the value of this option is 25%. 


See Also 


Data Flow 


Integration Services Transformations 
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Applies to: Q sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


To add and configure an Aggregate transformation, the package must already include at least one Data Flow 
task and one source. 


To aggregate values in a dataset 


1. In SQL Server Data Tools (SSDT), open the Integration Services project that contains the package you 
want. 


2. In Solution Explorer, double-click the package to open it. 


3. Click the Data Flow tab, and then, from the Toolbox, drag the Aggregate transformation to the design 
surface. 


4. Connect the Aggregate transformation to the data flow by dragging a connector from the source or the 
previous transformation to the Aggregate transformation. 


5. Double-click the transformation. 
6. In the Aggregate Transformation Editor dialog box, click the Aggregations tab. 


7. Inthe Available Input Columns list, select the check box by the columns on which you want to 
aggregate values. The selected columns appear in the table. 


NOTE 


You can select a column multiple times, applying multiple transformations to the column. To uniquely identify 


aggregations, a number is appended to the default name of the output alias of the column. 





8. Optionally, modify the value in the Output Alias columns. 


9. To change the default aggregation operation, Group by, select a different operation in the Operation 
list. 


10. To change the default comparison, select the individual comparison flags listed in the Comparison 
Flags column. By default, a comparison ignores case, kana type, non-spacing characters, and character 
width. 


11. Optionally, for the Count distinct aggregation, specify an exact number of distinct values in the Count 
Distinct Keys column, or select an approximate count in the Count Distinct Scale column. 





NOTE 


Providing the number of distinct values, exact or approximate, optimizes performance, because the transformation 
can preallocate an appropriate amount of memory to do its work. 








12. Optionally, click Advanced and update the name of the Aggregate transformation output. If the 
aggregations include a Group By operation, you can select an approximate count of grouping key values 


in the Keys Scale column or specify an exact number of grouping key values in the Keys column. 


NOTE 


Providing the number of distinct values, exact or approximate, optimizes performance, because the transformation 


can preallocate an appropriate amount of memory to do its work. 


NOTE 
The Keys Scale and Keys options are mutually exclusive. If you enter values in both columns, the larger value in 
either Keys Scale or Keys is used. 








13. Optionally, click the Advanced tab and set the attributes that apply to optimizing all the operations that 
the Aggregate transformation performs. 


14. Click OK. 


15. To save the updated package, click Save Selected Items on the File menu. 


See Also 


Aggregate Transformation 
Integration Services Transformations 
Integration Services Paths 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


The Audit transformation enables the data flow in a package to include data about the environment in which the 
package runs. For example, the name of the package, computer, and operator can be added to the data flow. 
Microsoft SQL Server Integration Services includes system variables that provide this information. 


System Variables 
The following table describes the system variables that the Audit transformation can use. 


SYSTEM VARIABLE INDEX DESCRIPTION 


ExecutionInstanceGUID 0 The GUID that identifies the execution 
instance of the package. 


PackagelD 1 The unique identifier of the package. 
PackageName 2 The package name. 

VersionID 3 The version of the package. 
ExecutionStartTime 4 The time the package started to run. 
MachineName D The computer name. 

UserName 6 The login name of the person who 


started the package. 


TaskName 7 The name of the Data Flow task with 
which the Audit transformation is 
associated. 

Taskld 8 The unique identifier of the Data Flow 
task. 


Configuration of the Audit Transformation 


You configure the Audit transformation by providing the name of a new output column to add to the 
transformation output, and then mapping the system variable to the output column. You can map a single 
system variable to multiple columns. 


This transformation has one input and one output. It does not support an error output. 
You can set properties through SSIS Designer or programmatically. 


The Advanced Editor dialog box reflects the properties that can be set programmatically. For more 
information about the properties that you can set in the Advanced Editor dialog box or programmatically, click 
one of the following topics: 


@ Common Properties 


e Transformation Custom Properties 


For more information about how to set properties, see Set the Properties of a Data Flow Component. 


Audit Transformation Editor 


The Audit transformation enables the data flow in a package to include data about the environment in which the 


package runs. For example, the name of the package, computer, and operator can be added to the data flow. 


Integration Services includes system variables that provide this information. 


Options 


Output column name 


Provide the name for a new output column that will contain the audit information. 


Audit type 


Select an available system variable to supply the audit information. 


VALUE 


Execution instance GUID 


Package ID 


Package name 


Version ID 


Execution start time 


Machine name 


User name 


Task name 


Task ID 


DESCRIPTION 


Insert the GUID that uniquely identifies the execution 
instance of the package. 


Insert the GUID that uniquely identifies the package. 


Insert the package name. 


Insert the GUID that uniquely identifies the version of the 
package. 


Insert the time at which package execution started. 


Insert the name of the computer on which the package was 
launched. 


Insert the login name of the user who launched the package. 


Insert the name of the Data Flow task with which the Audit 
transformation is associated. 


Insert the GUID that uniquely identifies the Data Flow task 
with which the Audit transformation is associated. 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


The Balanced Data Distributor (BDD) transformation takes advantage of concurrent processing capability of 
modern CPUs. It distributes buffers of incoming rows uniformly across outputs on separate threads. By using 
separate threads for each output path, the BDD component improves the performance of an SSIS package on 
multi-core or multi-processor machines. 


The following diagram shows a simple example of using the BDD transformation. In this example, the BDD 
transformation picks one pipeline buffer at a time from the input data from a flat file source and sends it down 
one of the three output paths in a round robin fashion. In SQL Server Data Tools, you can check the values of a 
DefaultBufferSize(default size of the pipeline buffer) and DefaultBufferMaxRows(default maximum number of 
rows in a pipeline buffer) in the Properties window displaying properties of a data flow task. 


= Flat File Source 
B 


aS Balanced Data Distributor 
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The Balanced Data Distributor transformation helps improve performance of a package in a scenario that 
satisfies the following conditions: 


1. There is large amount of data coming into the BDD transformation. If the data size is small and only one 
buffer can hold the data, there is no point in using the BDD transformation. If the data size is large and 
several buffers are required to hold the data, BDD can efficiently process buffers of data in parallel by 
using separate threads. 


2. The data can be read faster than the rest of the data flow can process it. In this scenario, the 
transformations that are performed on the data run slowly compared to the rate at which data is coming. 
If the bottleneck is at the destination, the destination must be parallelizable though. 


3. The data does not need to be ordered. For example, if the data needs to stay sorted, you should not split 
the data using the BDD transformation. 


Note that if the bottleneck in an SSIS package is due to the rate at which data can be read from the source, the 
BDD component does not help improve the performance. If the bottleneck in an SSIS package is because the 
destination does not support parallelism, the BDD does not help; however, you can perform all the 


transformations in parallel and use the Union All transformation to combine the output data coming out of 
different output paths of the BDD transformation before sending the data to the destination. 





IMPORTANT 


See the Balanced Data Distributor video on the TechNet Library for a presentation with a demo on using the 


transformation. 
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The Character Map transformation applies string functions, such as conversion from lowercase to uppercase, to 
character data. This transformation operates only on column data with a string data type. 


The Character Map transformation can convert column data in place or add a column to the transformation 
output and put the converted data in the new column. You can apply different sets of mapping operations to the 
same input column and put the results in different columns. For example, you can convert the same column to 
uppercase and lowercase and put the results in two different columns. 


Mapping can, under some circumstances, cause data to be truncated. For example, truncation can occur when 
single-byte characters are mapped to characters with a multibyte representation. The Character Map 
transformation includes an error output, which can be used to direct truncated data to separate output. For 
more information, see Error Handling in Data. 


This transformation has one input, one output, and one error output. 


Mapping Operations 


The following table describes the mapping operations that the Character Map transformation supports. 


OPERATION DESCRIPTION 

Byte reversal Reverses byte order. 

Full width Maps half-width characters to full-width characters. 
Half width Maps full-width characters to half-width characters. 
Hiragana Maps katakana characters to hiragana characters. 
Katakana Maps hiragana characters to katakana characters. 
Linguistic casing Applies linguistic casing instead of the system rules. 


Linguistic casing refers to functionality provided by the 
Win32 API for Unicode simple case mapping of Turkic and 
other locales. 


Lowercase Converts characters to lowercase. 

Simplified Chinese Maps traditional Chinese characters to simplified Chinese 
characters. 

Traditional Chinese Maps simplified Chinese characters to traditional Chinese 
characters. 


Uppercase Converts characters to uppercase. 


Mutually Exclusive Mapping Operations 


More than one operation can be performed in a transformation. However, some mapping operations are 
mutually exclusive. The following table lists restrictions that apply when you use multiple operations on the 
same column. Operations in the columns Operation A and Operation B are mutually exclusive. 


OPERATION A OPERATION B 

Lowercase Uppercase 

Hiragana Katakana 

Half width Full width 

Traditional Chinese Simplified Chinese 

Lowercase Hiragana, katakana, half width, full width 
Uppercase Hiragana, katakana, half width, full width 


Configuration of the Character Map Transformation 


You configure the Character Map transformation in the following ways: 
e Specify the columns to convert. 

e Specify the operations to apply to each column. 

You can set properties through SSIS Designer or programmatically. 


The Advanced Editor dialog box reflects the properties that can be set programmatically. For more 
information about the properties that you can set in the Advanced Editor dialog box or programmatically, click 
one of the following topics: 


@ Common Properties 

e Transformation Custom Properties 

For more information about how to set properties, click one of the following topics: 
e Set the Properties of a Data Flow Component 


e Sort Data for the Merge and Merge Join Transformations 


Character Map Transformation Editor 


Use the Character Map Transformation Editor dialog box to select the string functions to apply to column 
data and to specify whether mapping is an in-place change or added as a new column. 


Options 
Available Input Columns 


Use the check boxes to select the columns to transform using string functions. Your selections appear in the 
table below. 


Input Column 
View input columns selected from the table above. You can also change or remove a selection by using the list of 
available input columns. 


Destination 
Specify whether to save the results of the string operations in place, using the existing column, or to save the 
modified data as a new column. 


VALUE DESCRIPTION 


New column Save the data in a new column. Assign the column name 
under Output Alias. 


In-place change Save the modified data in the existing column. 


Operation 
Select from the list the string functions to apply to column data. 


VALUE DESCRIPTION 

Lowercase Convert to lower case. 

Uppercase Convert to upper case. 

Byte reversal Convert by reversing byte order. 

Hiragana Convert Japanese katakana characters to hiragana. 

Katakana Convert Japanese hiragana characters to katakana. 

Half width Convert full-width characters to half width. 

Full width Convert half-width characters to full width. 

Linguistic casing Apply linguistic rules of casing (Unicode simple case mapping 


for Turkic and other locales) instead of the system rules. 


Simplified Chinese Convert traditional Chinese characters to simplified Chinese. 
Traditional Chinese Convert simplified Chinese characters to traditional Chinese. 
Output Alias 


Type an alias for each output column. The default is Copy of followed by the input column name; however, you 
can choose any unique, descriptive name. 


Configure Error Output 
Use the Configure Error Output dialog box to specify error handling options for this transformation. 


(@o)aToli(oyar-lmes) olan le-larsie)sant-luela 


11/23/2021 * 3 minutes to read « Edit Online 





Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


The Conditional Split transformation can route data rows to different outputs depending on the content of the 
data. The implementation of the Conditional Split transformation is similar to a CASE decision structure in a 
programming language. The transformation evaluates expressions, and based on the results, directs the data 
row to the specified output. This transformation also provides a default output, so that if a row matches no 
expression it is directed to the default output. 


Configuration of the Conditional Split Transformation 


You can configure the Conditional Split transformation in the following ways: 
e Provide an expression that evaluates to a Boolean for each condition you want the transformation to test. 


e Specify the order in which the conditions are evaluated. Order is significant, because a row is sent to the 
output corresponding to the first condition that evaluates to true. 


e Specify the default output for the transformation. The transformation requires that a default output be 
specified. 


Each input row can be sent to only one output, that being the output for the first condition that evaluates to true. 
For example, the following conditions direct any rows in the FirstName column that begin with the letter A to 
one output, rows that begin with the letter B to a different output, and all other rows to the default output. 


Output 1 
SUBSTRING(FirstName,1,1) == "A" 
Output 2 
SUBSTRING(FirstName,1,1) == "B" 


Integration Services includes functions and operators that you can use to create the expressions that evaluate 
input data and direct output data. For more information, see Integration Services (SSIS) Expressions. 


The Conditional Split transformation includes the FriendlyExpression custom property. This property can be 
updated by a property expression when the package is loaded. For more information, see Use Property 
Expressions in Packages and Transformation Custom Properties. 


This transformation has one input, one or more outputs, and one error output. 
You can set properties through SSIS Designer or programmatically. 


The Advanced Editor dialog box reflects the properties that can be set programmatically. For more 
information about the properties that you can set in the Advanced Editor dialog box or programmatically, click 
one of the following topics: 


e Common Properties 
e Transformation Custom Properties 


For more information about how to set properties, click one of the following topics: 


e Split a Dataset by Using the Conditional Split Transformation 


e Set the Properties of a Data Flow Component 


Related Tasks 


Split a Dataset by Using the Conditional Split Transformation 


Conditional Split Transformation Editor 


Use the Conditional Split Transformation Editor dialog box to create expressions, set the order in which 
expressions are evaluated, and name the outputs of a conditional split. This dialog box includes mathematical, 
string, and date/time functions and operators that you can use to build expressions. The first condition that 
evaluates as true determines the output to which a row is directed. 


NOTE 


The Conditional Split transformation directs each input row to one output only. If you enter multiple conditions, the 
transformation sends each row to the first output for which the condition is true and disregards subsequent conditions 
for that row. If you need to evaluate several conditions successively, you may need to concatenate multiple Conditional 


Split transformations in the data flow. 











Options 
Order 
Select a row and use the arrow keys at right to change the order in which to evaluate expressions. 


Output Name 
Provide an output name. The default is a numbered list of cases; however, you can choose any unique, 


descriptive name. 


Condition 
Type an expression or build one by dragging from the list of available columns, variables, functions, and 
operators. 


The value of this property can be specified by using a property expression. 


Related topics: Integration Services (SSIS) Expressions, Operators (SSIS Expression), and Functions (SSIS 
Expression) 


Default output name 
Type a name for the default output, or use the default. 


Configure error output 
Specify how to handle errors by using the Configure Error Output dialog box. 


See Also 


Data Flow 
Integration Services Transformations 


Split a Dataset by Using the Conditional Split 
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To add and configure a Conditional Split transformation, the package must already include at least one Data 
Flow task and a source. 


To conditionally split a dataset 


1. In SQL Server Data Tools (SSDT), open the Integration Services project that contains the package you 
want. 


2. In Solution Explorer, double-click the package to open it. 


3. Click the Data Flow tab, and, from the Toolbox, drag the Conditional Split transformation to the design 
surface. 


4. Connect the Conditional Split transformation to the data flow by dragging the connector from the data 
source or the previous transformation to the Conditional Split transformation. 


5. Double-click the Conditional Split transformation. 


6. In the Conditional Split Transformation Editor, build the expressions to use as conditions by 
dragging variables, columns, functions, and operators to the Condition column in the grid. Or, you can 
type the expression in the Condition column. 





NOTE 


A variable or column can be used in multiple expressions. 








NOTE 


If the expression is not valid, the expression text is highlighted and a ToolTip on the column describes the errors. 








7. Optionally, modify the values in the Output Name column. The default names are Case 1, Case 2, and so 
forth. 


8. To modify the sequence in which the conditions are evaluated, click the up arrow or down arrow. 





NOTE 


Place the conditions that are most likely to be encountered at the top of the list. 








9. Optionally, modify the name of the default output for data rows that do not match any condition. 


10. To configure an error output, click Configure Error Output. For more information, see Debugging Data 
Flow. 


11. Click OK. 


12. To save the updated package, click Save Selected Items on the File menu. 


See Also 


Conditional Split Transformation 
Integration Services Transformations 
Integration Services Paths 

Integration Services Data Types 

Data Flow Task 

Integration Services (SSIS) Expressions 
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The Copy Column transformation creates new columns by copying input columns and adding the new columns 
to the transformation output. Later in the data flow, different transformations can be applied to the column 
copies. For example, you can use the Copy Column transformation to create a copy of a column and then 
convert the copied data to uppercase characters by using the Character Map transformation, or apply 
aggregations to the new column by using the Aggregate transformation. 


Configuration of the Copy Column Transformation 


You configure the Copy Column transformation by specifying the input columns to copy. You can create multiple 
copies of a column, or create copies of multiple columns in one operation. 


This transformation has one input and one output. It does not support an error output. 
You can set properties through the SSIS Designer or programmatically. 


The Advanced Editor dialog box reflects the properties that can be set programmatically. For more 
information about the properties that you can set in the Advanced Editor dialog box or programmatically, click 
one of the following topics: 


@ Common Properties 
e Transformation Custom Properties 


For more information about how to set properties, see Set the Properties of a Data Flow Component. 


Copy Column Transformation Editor 


Use the Copy Column Transformation Editor dialog box to select columns to copy and to assign names for 
the new output columns. 





NOTE 


When you are simply copying all of your source data to a destination, it may not be necessary to use the Copy Column 
transformation. In some scenarios, you can connect a source directly to a destination, when no data transformation is 
required. In these circumstances it is often preferable to use the SQL Server Import and Export Wizard to create your 
package for you. Later you can enhance and reconfigure the package as needed. For more information, see SQL Server 
Import and Export Wizard. 





Options 
Available Input Columns 
Select columns to copy by using the check boxes. Your selections add input columns to the table below. 


Input Column 
Select columns to copy from the list of available input columns. Your selections are reflected in the check box 
selections in the Available Input Columns table. 


Output Alias 
Type an alias for each new output column. The default is Copy of, followed by the name of the input column; 





however, you can choose any unique, descriptive name. 


See Also 


Data Flow 


Integration Services Transformations 
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The Data Conversion transformation converts the data in an input column to a different data type and then 
copies it to a new output column. For example, a package can extract data from multiple sources, and then use 
this transformation to convert columns to the data type required by the destination data store. You can apply 
multiple conversions to a single input column. 


Using this transformation, a package can perform the following types of data conversions: 


e Change the data type. For more information, see Integration Services Data Types. 


NOTE 


If you are converting data to a date or a datetime data type, the date in the output column is in the ISO format, 
although the locale preference may specify a different format. 





e Set the column length of string data and the precision and scale on numeric data. For more information, 
see Precision, Scale, and Length (Transact-SQL). 


e Specify a code page. For more information, see Comparing String Data. 





NOTE 


When copying between columns with a string data type, the two columns must use the same code page. 





If the length of an output column of string data is shorter than the length of its corresponding input column, the 
output data is truncated. For more information, see Error Handling in Data. 


This transformation has one input, one output, and one error output. 


Related Tasks 


You can set properties through the SSIS Designer or programmatically. For information about using the Data 
Conversion Transformation in the SSIS Designer, see Convert Data to a Different Data Type by Using the Data 
Conversion Transformation. For information about setting properties of this transformation programmatically, 
see Common Properties and Transformation Custom Properties. 


Related Content 


Blog entry, Performance Comparison between Data Type Conversion Techniques in SSIS 2008, on 
blogs.msdn.com. 


Data Conversion Transformation Editor 


Use the Data Conversion Transformation Editor dialog box to select the columns to convert, select the data 
type to which the column is converted, and set conversion attributes. 





NOTE 
The FastParse property of the output columns of the Data Conversion transformation is not available in the Data 
Conversion Transformation Editor, but can be set by using the Advanced Editor. For more information on this 


property, see the Data Conversion Transformation section of Transformation Custom Properties. 





Options 
Available Input Columns 
Select columns to convert by using the check boxes. Your selections add input columns to the table below. 


Input Column 
Select columns to convert from the list of available input columns. Your selections are reflected in the check box 
selections above. 


Output Alias 
Type an alias for each new column. The default is Copy of followed by the input column name; however, you 
can choose any unique, descriptive name. 


Data Type 
Select an available data type from the list. For more information, see Integration Services Data Types. 


Length 
Set the column length for string data. 


Precision 


Set the precision for numeric data. 


Scale 
Set the scale for numeric data. 


Code page 
Select the appropriate code page for columns of type DT_STR. 


Configure error output 
Specify how to handle row-level errors by using the Configure Error Output dialog box. 


See Also 


Fast Parse 
Data Flow 


Integration Services Transformations 





Convert Data Type with Data Conversion 
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To add and configure a Data Conversion transformation, the package must already include at least one Data 


Flow task and one source. 


To convert data to a different data type 


1. 


10. 


11. 


12. 


In SQL Server Data Tools (SSDT), open the Integration Services project that contains the package you 
want. 


. In Solution Explorer, double-click the package to open it. 


. Click the Data Flow tab, and then, from the Toolbox, drag the Data Conversion transformation to the 


design surface. 


. Connect the Data Conversion transformation to the data flow by dragging a connector from the source or 


the previous transformation to the Data Conversion transformation. 


. Double-click the Data Conversion transformation. 


. Inthe Data ConversionTransformation Editor dialog box, in the Available Input Columns table, 


select the check box next to the columns whose data type you want to convert. 





NOTE 


You can apply multiple data conversions to an input column. 





. Optionally, modify the default values in the Output Alias column. 


. Inthe Data Type list, select the new data type for the column. The default data type is the data type of the 


input column. 


. Optionally, depending on the selected data type, update the values in the Length, the Precision, the 


Scale, and the Code Page columns. 


To configure the error output, click Configure Error Output. For more information, see Debugging Data 
Flow. 


Click OK. 


To save the updated package, click Save Selected Items on the File menu. 


See Also 


Data Conversion Transformation 


Integration Services Transformations 


Integration Services Paths 


Integration Services Data Types 
Data Flow Task 
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The Data Mining Query transformation performs prediction queries against data mining models. This 
transformation contains a query builder for creating Data Mining Extensions (DMX) queries. The query builder 
lets you create custom statements for evaluating the transformation input data against an existing mining 
model using the DMX language. For more information, see Data Mining Extensions (DMX) Reference. 


One transformation can execute multiple prediction queries if the models are built on the same data mining 
structure. For more information, see Data Mining Query Tools. 


Configuration of the Data Mining Query Transformation 


The Data Mining Query transformation uses an Analysis Services connection manager to connect to the 
Analysis Services project or the instance of Analysis Services that contains the mining structure and mining 
models. For more information, see Analysis Services Connection Manager. 


This transformation has one input and one output. It does not support an error output. 
You can set properties through SSIS Designer or programmatically. 


The Advanced Editor dialog box reflects the properties that can be set programmatically. For more 
information about the properties that you can set in the Advanced Editor dialog box or programmatically, click 
one of the following topics: 


@ Common Properties 
e Transformation Custom Properties 


For more information about how to set properties, see Set the Properties of a Data Flow Component. 


Data Mining Query Transformation Editor (Mining Model Tab) 


Use the Mining Model tab of the Data Mining Query Transformation Editor dialog box to select the data 
mining structure and its mining models. 


Options 

Connection 

Select an existing Analysis Services connection by using the list box, or create a new connection by using the 
New button described as follows. 


New 
Create a new connection by using the Add Analysis Services Connection Manager dialog box. 


Mining structure 
Select from the list of available mining model structures. 


Mining models 
View the list of mining models associated with the selected data mining structure. 


Data Mining Query Transformation Editor (Query Tab) 


Use the Query tab of the Data Mining Query Transformation Editor dialog box to create a prediction 
query. 
Options 


Data mining query 
Type a Data Mining Extensions (DMX) query directly into the text box. 


Build New Query 
Click Build New Query to create a Data Mining Extensions (DMX) query by using the graphical query builder. 


DQS Cleansing Transformation 
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The DQS Cleansing transformation uses Data Quality Services (DQS) to correct data from a connected data 
source, by applying approved rules that were created for the connected data source or a similar data source. For 
more information about data correction rules, see DQS Knowledge Bases and Domains. For more information 
DQS, see Data Quality Services Concepts. 


To determine whether the data has to be corrected, the DQS Cleansing transformation processes data from an 
input column when the following conditions are true: 


@ The column is selected for data correction. 
e The column data type is supported for data correction. 
e@ The column is mapped a domain that has a compatible data type. 


The transformation also includes an error output that you configure to handle row-level errors. To configure the 
error output, use the DQS Cleansing Transformation Editor. 


You can include the Fuzzy Grouping Transformation in the data flow to identify rows of data that are likely to be 
duplicates. 


Data Quality Projects and Values 


When you process data with the DQS Cleansing transformation, a cleansing project is created on the Data 
Quality Server. You use the Data Quality Client to manage the project. In addition, you can use the Data Quality 
Client to import the project values into a DQS knowledge base domain. You can import the values only to a 
domain (or linked domain) that the DQS Cleansing transformation was configured to use. 


Related Tasks 
e@ Open Integration Services Projects in Data Quality Client 
e@ Import Cleansing Project Values into a Domain 


e Apply Data Quality Rules to Data Source 


Related Content 


@ Open, Unlock, Rename, and Delete a Data Quality Project 


e Article, Cleansing complex data using composite domains, on social.technet.microsoft.com. 


DQS Cleansing Transformation Editor Dialog Box 


Use the DQS Cleansing Transformation Editor dialog box to correct data using Data Quality Services (DQS). 
For more information, see Data Quality Services Concepts. 


What do you want to do? 


e Open the DQS Cleansing Transformation Editor 


e Set options on the Connection Manager tab 


Set options on the Mapping tab 


e Set options on the Advanced tab 


Set the options in the DQS Cleansing Connection Manager dialog box 


Open the DQS Cleansing Transformation Editor 
1. Add the DQS Cleansing Transformation to Integration Services package, in SQL Server Data Tools (SSDT). 


2. Right-click the component and then click Edit. 


Set options on the Connection Manager tab 


Data quality connection manager 
Select an existing DQS connection manager from the list, or create a new connection by clicking New. 


New 
Create a new connection manager by using the DQS Cleansing Connection Manager dialog box. See Set the 
options in the DQS Cleansing Connection Manager dialog box 


Data Quality Knowledge Base 
Select an existing DQS knowledge base for the connected data source. For more information about the DQS 
knowledge base, see DQS Knowledge Bases and Domains. 


Encrypt connection 
Specify whether to encrypt the connection, in order to encrypt the data transfer between the DQS Server and 
Integration Services. 


Available domains 
Lists the available domains for the selected knowledge base. There are two types of domains: single domains, 
and composite domains that contain two or more single domains. 


For information on how to map columns to composite domains, see Map Columns to Composite Domains. 
For more information about domains, see DQS Knowledge Bases and Domains. 


Configure Error Output 
Specify how to handle row-level errors. Errors can occur when the transformation corrects data from the 


connected data source, due to unexpected data values or validation constraints. 
The following are the valid values: 


e Fail Component, which indicates that the transformation fails and the input data is not inserted into the 
Data Quality Services database. This is the default value. 


e Redirect Row, which indicates that the input data is not inserted into the Data Quality Services database 


and is redirected to the error output. 


Set options on the Mapping tab 


For information on how to map columns to composite domains, see Map Columns to Composite Domains. 


Available Input Columns 
Lists the columns from the connected data source. Select one or more columns that contain data that you want 
to correct. 


Input Column 
Lists an input column that you selected in the Available Input Columns area. 


Domain 


Select a domain to map to the input column. 


Source Alias 


Lists the source column that contains the original column value. 
Click in the field to modify the column name. 


Output Alias 
Lists the column that is outputted by the DQS Cleansing Transformation. The column contains the original 
column value or the corrected value. 


Click in the field to modify the column name. 


Status Alias 
Lists the column that contains status information for the corrected data. Click in the field to modify the column 
name. 


Set options on the Advanced tab 


Standardize output 
Indicate whether to output the data in the standardized format based on the output format defined for domains. 
For more information about standardized format, see Data Cleansing. 


Confidence 

Indicate whether to include the confidence level for corrected data. The confidence level indicates the extend of 
certainty of DQS for the correction or suggestion. For more information about confidence levels, see Data 
Cleansing. 


Reason 
Indicate whether to include the reason for the data correction. 


Appended Data 
Indicate whether to output additional data that is received from an existing reference data provider. For more 
information, see Reference Data Services in DQS. 


Appended Data Schema 
Indicate whether to output the data schema. For more information, see Attach Domain or Composite Domain to 
Reference Data. 


Set the options in the DQS Cleansing Connection Manager dialog box 


Server name 
Select or type the name of the DQS server that you want to connect to. For more information about the server, 
see DQS Administration. 


Test Connection 
Click to confirm that the connection that you specified is viable. 


You can also open the DQS Cleansing Connection Manager dialog box from the connections area, by doing 
the following: 


1. In SQL Server Data Tools (SSDT), open an existing Integration Services project or create a new one. 
2. Right-click in the connections area, click New Connection, and then click DQS. 


3. Click Add. 
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A DQS Cleansing connection manager enables a package to connect to a Data Quality Services server. The DQS 
Cleansing transformation uses the DQS Cleansing connection manager. 


For more information about Data Quality Services, see Data Quality Services Concepts. 


IMPORTANT 


The DQS Cleansing connection manager supports only Windows Authentication. 





Related Tasks 


You can set properties through SSIS Designer or programmatically. For more information about the properties 
that you can set in SSIS Designer, see DQS Cleansing Transformation Editor Dialog Box. 


For information about configuring a connection manager programmatically, see documentation for the 
ConnectionManager class in the Developer Guide. 


Apply Data Quality Rules to Data Source 
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You can use Data Quality Services (DQS) to correct data in the package data flow by connecting the DQS 
Cleansing transformation to the data source. For more information about DQS, see Data Quality Services 
Concepts. For more information about the transformation, see DQS Cleansing Transformation. 


When you process data with the DQS Cleansing transformation, a data quality project is created on the Data 
Quality Server. You use the Data Quality Client to manage the project. For more information, see Open, Unlock, 
Rename, and Delete a Data Quality Project. 


To correct data in the data flow 


1. Create a package. 


2. Add and configure the DQS Cleansing transformation. For more information, see DQS Cleansing 
Transformation Editor Dialog Box. 


3. Connect the DQS Cleansing transformation to a data source. 
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A composite domain consists of two or more single domains. You can map multiple columns to the domain, or 
you can map a single column with delimited values to the domain. 


When you have multiple columns, you must map a column to each single domain in the composite domain to 
apply the composite domain rules to data cleansing. You select the single domains contained in the composite 


domain, in the Data Quality Client. For more information, see Create a Composite Domain. 


When you have a single column with delimited values, you must map the single column to the composite 
domain. The values must appear in the same order as the single domains appear in the composite domain. The 
delimiter in the data source must match the delimiter that is used to parse the composite domain values. You 
select the delimiter for the composite domain, as well as set other properties, in the Data Quality Client. For 
more information, see Create a Composite Domain. 


To map multiple columns to a composite domain 


1. Right-click the DQS Cleansing transformation, and then click Edit. 


2. On the Connection Manager tab, confirm that the composite domain appears in the list of available 
domains. 


3. On the Mapping tab, select the columns in the Available Input Columns area. 


4. For each column listed in the Input Column field, select a single domain in the Domain field. Select only 
single domains that are in the composite domain. 


5. As needed, modify the names that appear in the Source Alias, Output Alias, and Status Alias fields. 


6. As needed, set properties on the Advanced tab. For more information about the properties, see DQS 
Cleansing Transformation Editor Dialog Box. 


To map a column with delimited values to a composite domain 


1. Right-click the DQS Cleansing transformation, and then click Edit. 


2. On the Connection Manager tab, confirm that the composite domain appears in the list of available 
domains. 


3. On the Mapping tab, select the column in the Available Input Columns area. 
4. For the column listed in the Input Column field, select the composite domain in the Domain field. 
5. As needed, modify the names that appear in the Source Alias, Output Alias, and Status Alias fields. 


6. As needed, set properties on the Advanced tab. For more information about the properties, see DQS 
Cleansing Transformation Editor Dialog Box. 


See Also 


DQS Cleansing Transformation 
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Applies to: Q sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


The Derived Column transformation creates new column values by applying expressions to transformation 
input columns. An expression can contain any combination of variables, functions, operators, and columns from 
the transformation input. The result can be added as a new column or inserted into an existing column as a 
replacement value. The Derived Column transformation can define multiple derived columns, and any variable 


or input columns can appear in multiple expressions. 
You can use this transformation to perform the following tasks: 


e Concatenate data from different columns into a derived column. For example, you can combine values 
from the FirstName and LastName columns into a single derived column named FullName, by using 
the expression FirstName + " " + LastName . 


e Extract characters from string data by using functions such as SUBSTRING, and then store the result in a 
derived column. For example, you can extract a person's initial from the FirstName column, by using the 
expression SUBSTRING(FirstName,1,1) . 


e Apply mathematical functions to numeric data and store the result in a derived column. For example, you 
can change the length and precision of a numeric column, SalesTax, to a number with two decimal 
places, by using the expression ROUND(SalesTax, 2) . 


e Create expressions that compare input columns and variables. For example, you can compare the variable 
Version against the data in the column ProductVersion, and depending on the comparison result, use 
the value of either Version or ProductVersion, by using the expression 


ProductVersion == @Version? ProductVersion : @Version . 


e Extract parts of a datetime value. For example, you can use the GETDATE and DATEPART functions to 
extract the current year, by using the expression DATEPART("year",GETDATE()) . 


e Convert date strings to a specific format using an expression. 


Configuration of the Derived Column Transformation 
You can configure the Derived column transformation in the following ways: 


e Provide an expression for each input column or new column that will be changed. For more information, 


see Integration Services (SSIS) Expressions. 





NOTE 


If an expression references an input column that is overwritten by the Derived Column transformation, the 
expression uses the original value of the column, not the derived value. 








e If adding results to new columns and the data type is string, specify a code page. For more information, 
see Comparing String Data. 


The Derived Column transformation includes the FriendlyExpression custom property. This property can be 
updated by a property expression when the package is loaded. For more information, see Use Property 
Expressions in Packages, and Transformation Custom Properties. 


This transformation has one input, one regular output, and one error output. 
You can set properties through SSIS Designer or programmatically. 


The Advanced Editor dialog box reflects the properties that can be set programmatically. For more 
information about the properties that you can set in the Advanced Editor dialog box or programmatically, click 
one of the following topics: 


@ Common Properties 
e Transformation Custom Properties 
For more information about how to set properties, click one of the following topics: 


e Set the Properties of a Data Flow Component 


Related Tasks 


e Derive Column Values by Using the Derived Column Transformation 


Derived Column Transformation Editor 


Use the Derived Column Transformation Editor dialog box to create expressions that populate new or 
replacement columns. 


Options 

Variables and Columns 

Build an expression that uses a variable or an input column by dragging the variable or column from the list of 
available variables and columns to an existing table row in the pane below, or to a new row at the bottom of the 
list. 


Functions and Operators 
Build an expression that uses a function or an operator to evaluate input data and direct output data by 
dragging functions and operators from the list to the pane below. 


Derived Column Name 
Provide a derived column name. The default is a numbered list of derived columns; however, you can choose 
any unique, descriptive name. 


Derived Column 
Select a derived column from the list. Choose whether to add the derived column as a new output column, or to 
replace the data in an existing column. 


Expression 
Type an expression or build one by dragging from the previous list of available columns, variables, functions, 
and operators. 


The value of this property can be specified by using a property expression. 


Related topics: Integration Services (SSIS) Expressions, Operators (SSIS Expression), and Functions (SSIS 
Expression) 


Data Type 

If adding data to a new column, the Derived Column TransformationEditor dialog box automatically 
evaluates the expression and sets the data type appropriately. The value of this column is read-only. For more 
information, see Integration Services Data Types. 


Length 
If adding data to a new column, the Derived Column TransformationEditor dialog box automatically 


evaluates the expression and sets the column length for string data. The value of this column is read-only. 


Precision 
If adding data to a new column, the Derived Column TransformationEditor dialog box automatically sets the 
precision for numeric data based on the data type. The value of this column is read-only. 


Scale 
If adding data to a new column, the Derived Column TransformationEditor dialog box automatically sets the 
scale for numeric data based on the data type. The value of this column is read-only. 


Code Page 
If adding data to a new column, the Derived Column TransformationEditor dialog box automatically sets 
code page for the DT_STR data type. You can update Code Page. 


Configure error output 
Specify how to handle errors by using the Configure Error Output dialog box. 


Related Content 


Technical article, SSIS Expression Examples, on social.technet.microsoft.com 
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Applies to: Qsal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


To add and configure a Derived Column transformation, the package must already include at least one Data 
Flow task and one source. 


The Derived Column transformation uses expressions to update the values of existing or to add values to new 
columns. When you choose to add values to new columns, the Derived Column Transformation Editor 
dialog box evaluates the expression and defines the metadata of the columns accordingly. For example, if an 
expression concatenates two columns-each with the DT_WSTR data type and a length of 50-with a space 
between the two column values, the new column has the DT_WSTR data type and a length of 101. You can 
update the data type of new columns. The only requirement is that data type be compatible with the inserted 
data. For example, the Derived Column Transformation Editor dialog box generates a validation error when 
you assign a date value to a column with an integer data type. Depending on the data type that you selected, 
you can specify the length, precision, scale, and code page of the column. 


To derive column values 


1. In SQL Server Data Tools (SSDT), open the Integration Services project that contains the package you 
want. 


2. In Solution Explorer, double-click the package to open it. 


3. Click the Data Flow tab, and then, from the Toolbox, drag the Derived Column transformation to the 
design surface. 


4. Connect the Derived Column transformation to the data flow by dragging the connector from the source 
or the previous transformation to the Derived Column transformation. 


5. Double-click the Derived Column transformation. 


6. In the Derived Column Transformation Editor dialog box, build the expressions to use as conditions 
by dragging variables, columns, functions, and operators to the Expression column in the grid. 
Alternatively, you can type the expression in the Expression column. 





NOTE 


If the expression is not valid, the expression text is highlighted and a ToolTip on the column describes the errors. 





7. Inthe Derived Column list, select <add as new column> to write the evaluation result of the 


expression to a new column, or select an existing column to update with the evaluation result. 


If you chose to use a new column, the Derived Column Transformation Editor dialog box evaluates 
the expression and assigns a data type to the column, depending on the data type, length, precisions, 
scale, and code page. 


8. If using a new column, select a data type in the Data Type list. Depending on the selected data type, 
optionally update the values in the Length, Precision, Scale, and Code Page columns. Metadata of 
existing columns cannot be changed. 


9. Optionally, modify the values in the Derived Column Name column. 


10. To configure the error output, click Configure Error Output. For more information, see Debugging Data 
Flow. 


11. Click OK. 


12. To save the updated package, click Save Selected Items on the File menu. 


See Also 


Derived Column Transformation 
Integration Services Data Types 
Integration Services Transformations 
Integration Services Paths 

Data Flow Task 

Integration Services (SSIS) Expressions 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


The Export Column transformation reads data in a data flow and inserts the data into a file. For example, if the 
data flow contains product information, such as a picture of each product, you could use the Export Column 
transformation to save the images to files. 


Append and Truncate Options 


The following table describes how the settings for the append and truncate options affect results. 
APPEND TRUNCATE FILE EXISTS RESULTS 


False False No The transformation creates 
a new file and writes the 
data to the file. 


True False No The transformation creates 
a new file and writes the 
data to the file. 


False True No The transformation creates 
a new file and writes the 
data to the file. 


True True No The transformation fails 
design time validation. It is 
not valid to set both 
properties to true. 


False False Yes A run-time error occurs. 
The file exists, but the 
transformation cannot write 
to it. 


False True Yes The transformation deletes 
and re-creates the file and 
writes the data to the file. 


True False Yes The transformation opens 
the file and writes the data 
at the end of the file. 


True True Yes The transformation fails 
design time validation. It is 
not valid to set both 
properties to true. 


Configuration of the Export Column Transformation 


You can configure the Export Column transformation in the following ways: 


e Specify the data columns and the columns that contain the path of files to which to write the data. 
e Specify whether the data-insertion operation appends or truncates existing files. 


e Specify whether a byte-order mark (BOM) is written to the file. 





NOTE 


A BOM is written only when the data is not appended to an existing file and the data has the DT_NTEXT data type. 





The transformation uses pairs of input columns: One column contains a file name, and the other column 
contains data. Each row in the data set can specify a different file. As the transformation processes a row, the 
data is inserted into the specified file. At run time, the transformation creates the files, if they do not already 
exist, and then the transformation writes the data to the files. The data to be written must have a DT_TEXT, 
DT_NTEXT, or DT_IMAGE data type. For more information, see Integration Services Data Types. 


This transformation has one input, one output, and one error output. 
You can set properties through SSIS Designer or programmatically. 


The Advanced Editor dialog box reflects the properties that can be set programmatically. For more 
information about the properties that you can set in the Advanced Editor dialog box or programmatically, click 
one of the following topics: 


@ Common Properties 
e Transformation Custom Properties 


For more information about how to set properties, see Set the Properties of a Data Flow Component. 


Export Column Transformation Editor (Columns Page) 


Use the Columns page of the Export Column Transformation Editor dialog box to specify columns in the 
data flow to extract to files. You can specify whether the Export Column transformation appends data to a file or 


overwrites an existing file. 


Options 

Extract Column 

Select from the list of input columns that contain text or image data. All rows should have definitions for Extract 
Column and File Path Column. 


File Path Column 
Select from the list of input columns that contain file paths and file names. All rows should have definitions for 
Extract Column and File Path Column. 


Allow Append 
Specify whether the transformation appends data to existing files. The default is false. 


Force Truncate 
Specify whether the transformation deletes the contents of existing files before writing data. The default is false. 


Write BOM 
Specify whether to write a byte-order mark (BOM) to the file. A BOM is only written if the data has the 
DT_NTEXT or DT_WSTR data type and is not appended to an existing data file. 


Export Column Transformation Editor (Error Output Page) 


Use the Error Output page of the Export Column Transformation Editor dialog box to specify how to 


handle errors. 


Options 


Input/Output 
View the name of the output. Click the name to expand the view to include columns. 


Column 
View the output columns that you selected on the Columns page of the Export Column Transformation 
Editor dialog box. 


Error 
Specify what you want to happen if an error occurs: ignore the failure, redirect the row, or fail the component. 


Truncation 
Specify what you want to happen if a truncation occurs: ignore the failure, redirect the row, or fail the 


component. 


Description 
View the description of the operation. 


Set this value to selected cells 
Specify what should happen to all the selected cells when an error or truncation occurs: ignore the failure, 


redirect the row, or fail the component. 


Apply 
Apply the error handling option to the selected cells. 


Fuzzy Grouping Transformation 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


The Fuzzy Grouping transformation performs data cleaning tasks by identifying rows of data that are likely to be 
duplicates and selecting a canonical row of data to use in standardizing the data. 





NOTE 


For more detailed information about the Fuzzy Grouping transformation, including performance and memory limitations, 
see the white paper, Fuzzy Lookup and Fuzzy Grouping in SQL Server Integration Services 2005. 





The Fuzzy Grouping transformation requires a connection to an instance of SQL Server to create the temporary 
SQL Server tables that the transformation algorithm requires to do its work. The connection must resolve to a 
user who has permission to create tables in the database. 


To configure the transformation, you must select the input columns to use when identifying duplicates, and you 
must select the type of match-fuzzy or exact-for each column. An exact match guarantees that only rows that 
have identical values in that column will be grouped. Exact matching can be applied to columns of any 
Integration Services data type except DT_TEXT, DT_NTEXT, and DT_IMAGE. A fuzzy match groups rows that have 
approximately the same values. The method for approximate matching of data is based on a user-specified 
similarity score. Only columns with the DT_WSTR and DT_STR data types can be used in fuzzy matching. For 
more information, see Integration Services Data Types. 


The transformation output includes all input columns, one or more columns with standardized data, and a 
column that contains the similarity score. The score is a decimal value between 0 and 1. The canonical row has a 
score of 1. Other rows in the fuzzy group have scores that indicate how well the row matches the canonical row. 
The closer the score is to 1, the more closely the row matches the canonical row. If the fuzzy group includes rows 
that are exact duplicates of the canonical row, these rows also have a score of 1. The transformation does not 
remove duplicate rows; it groups them by creating a key that relates the canonical row to similar rows. 


The transformation produces one output row for each input row, with the following additional columns: 
e _key_in, a column that uniquely identifies each row. 


e _key_out, a column that identifies a group of duplicate rows. The __key_out column has the value of the 
_key_in column in the canonical data row. Rows with the same value in_key_out are part of the same 
group. The_key_outvalue for a group corresponds to the value of _key_in in the canonical data row. 


@ _score, a value between 0 and 1 that indicates the similarity of the input row to the canonical row. 


These are the default column names and you can configure the Fuzzy Grouping transformation to use other 
names. The output also provides a similarity score for each column that participates in a fuzzy grouping. 


The Fuzzy Grouping transformation includes two features for customizing the grouping it performs: token 
delimiters and similarity threshold. The transformation provides a default set of delimiters used to tokenize the 
data, but you can add new delimiters that improve the tokenization of your data. 


The similarity threshold indicates how strictly the transformation identifies duplicates. The similarity thresholds 
can be set at the component and the column levels. The column-level similarity threshold is only available to 
columns that perform a fuzzy match. The similarity range is 0 to 1. The closer to 1 the threshold is, the more 
similar the rows and columns must be to qualify as duplicates. You specify the similarity threshold among rows 





and columns by setting the MinSimilarity property at the component and column levels. To satisfy the similarity 
that is specified at the component level, all rows must have a similarity across all columns that is greater than or 
equal to the similarity threshold that is specified at the component level. 


The Fuzzy Grouping transformation calculates internal measures of similarity, and rows that are less similar than 
the value specified in MinSimilarity are not grouped. 


To identify a similarity threshold that works for your data, you may have to apply the Fuzzy Grouping 
transformation several times using different minimum similarity thresholds. At run time, the score columns in 
transformation output contain the similarity scores for each row in a group. You can use these values to identify 
the similarity threshold that is appropriate for your data. If you want to increase similarity, you should set 
MinSimilarity to a value larger than the value in the score columns. 


You can customize the grouping that the transformation performs by setting the properties of the columns in 
the Fuzzy Grouping transformation input. For example, the FuzzyComparisonFlags property specifies how the 
transformation compares the string data in a column, and the ExactFuzzy property specifies whether the 
transformation performs a fuzzy match or an exact match. 


The amount of memory that the Fuzzy Grouping transformation uses can be configured by setting the 
MaxMemoryUsage custom property. You can specify the number of megabytes (MB) or use the value 0 to allow 
the transformation to use a dynamic amount of memory based on its needs and the physical memory available. 
The MaxMemoryUsage custom property can be updated by a property expression when the package is loaded. 
For more information, see Integration Services (SSIS) Expressions, Use Property Expressions in Packages, and 
Transformation Custom Properties. 


This transformation has one input and one output. It does not support an error output. 


Row Comparison 


When you configure the Fuzzy Grouping transformation, you can specify the comparison algorithm that the 
transformation uses to compare rows in the transformation input. If you set the Exhaustive property to true, the 
transformation compares every row in the input to every other row in the input. This comparison algorithm 
may produce more accurate results, but it is likely to make the transformation perform more slowly unless the 
number of rows in the input is small. To avoid performance issues, it is advisable to set the Exhaustive property 
to true only during package development. 


Temporary Tables and Indexes 


At run time, the Fuzzy Grouping transformation creates temporary objects such as tables and indexes, 
potentially of significant size, in the SQL Server database that the transformation connects to. The size of the 
tables and indexes are proportional to the number of rows in the transformation input and the number of 


tokens created by the Fuzzy Grouping transformation. 


The transformation also queries the temporary tables. You should therefore consider connecting the Fuzzy 
Grouping transformation to a non-production instance of SQL Server, especially if the production server has 
limited disk space available. 


The performance of this transformation may improve if the tables and indexes it uses are located on the local 


computer. 


Configuration of the Fuzzy Grouping Transformation 


You can set properties through SSIS Designer or programmatically. 


For more information about the properties that you can set in the Advanced Editor dialog box or 
programmatically, click one of the following topics: 


@ Common Properties 


e Transformation Custom Properties 


Related Tasks 


For details about how to set properties of this task, click one of the following topics: 
e Identify Similar Data Rows by Using the Fuzzy Grouping Transformation 


e Set the Properties of a Data Flow Component 


Fuzzy Grouping Transformation Editor (Connection Manager Tab) 


Use the Connection Manager tab of the Fuzzy Grouping Transformation Editor dialog box to select an 


existing connection or create a new one. 





NOTE 
The server specified by the connection must be running SQL Server. The Fuzzy Grouping transformation creates 
temporary data objects in tempdb that may be as large as the full input to the transformation. While the transformation 


executes, it issues server queries against these temporary objects. This can affect overall server performance. 





Options 

OLE DB connection manager 

Select an existing OLE DB connection manager by using the list box, or create a new connection by using the 
New button. 


New 
Create a new connection by using the Configure OLE DB Connection Manager dialog box. 


Fuzzy Grouping Transformation Editor (Columns Tab) 


Use the Columns tab of the Fuzzy Grouping Transformation Editor dialog box to specify the columns used 


to group rows with duplicate values. 


Options 
Available Input Columns 
Select from this list the input columns used to group rows with duplicate values. 


Name 
View the names of available input columns. 


Pass Through 
Select whether to include the input column in the output of the transformation. All columns used for grouping 
are automatically copied to the output. You can include additional columns by checking this column. 


Input Column 
Select one of the input columns selected earlier in the Available Input Columns list. 


Output Alias 
Enter a descriptive name for the corresponding output column. By default, the output column name is the same 


as the input column name. 


Group Output Alias 
Enter a descriptive name for the column that will contain the canonical value for the grouped duplicates. The 
default name of this output column is the input column name with _clean appended. 





Match Type 

Select fuzzy or exact matching. Rows are considered duplicates if they are sufficiently similar across all columns 
with a fuzzy match type. If you also specify exact matching on certain columns, only rows that contain identical 
values in the exact matching columns are considered as possible duplicates. Therefore, if you know that a certain 
column contains no errors or inconsistencies, you can specify exact matching on that column to increase the 
accuracy of the fuzzy matching on other columns. 


Minimum Similarity 

Set the similarity threshold at the join level by using the slider. The closer the value is to 1, the closer the 
resemblance of the lookup value to the source value must be to qualify as a match. Increasing the threshold can 
improve the speed of matching since fewer candidate records need to be considered. 


Similarity Output Alias 
Specify the name for a new output column that contains the similarity scores for the selected join. If you leave 
this value empty, the output column is not created. 


Numerals 
Specify the significance of leading and trailing numerals in comparing the column data. For example, if leading 
numerals are significant, "123 Main Street" will not be grouped with "456 Main Street." 


VALUE DESCRIPTION 

Neither Leading and trailing numerals are not significant. 
Leading Only leading numerals are significant. 

Trailing Only trailing numerals are significant. 
LeadingAndtTrailing Both leading and trailing numerals are significant. 


Comparison Flags 


For information about the string comparison options, see Comparing String Data. 


Fuzzy Grouping Transformation Editor (Advanced Tab) 


Use the Advanced tab of the Fuzzy Grouping Transformation Editor dialog box to specify input and output 
columns, set similarity thresholds, and define delimiters. 


NOTE 
The Exhaustive and the MaxMemoryUsage properties of the Fuzzy Grouping transformation are not available in the 
Fuzzy Grouping Transformation Editor, but can be set by using the Advanced Editor. For more information on 


these properties, see the Fuzzy Grouping Transformation section of Transformation Custom Properties. 











Options 

Input key column name 

Specify the name of an output column that contains the unique identifier for each input row. The _key_in 
column has a value that uniquely identifies each row. 


Output key column name 
Specify the name of an output column that contains the unique identifier for the canonical row of a group of 


duplicate rows. The __key_out column corresponds to the _key_in value of the canonical data row. 


Similarity score column name 


Specify a name for the column that contains the similarity score. The similarity score is a value between 0 and 1 


that indicates the similarity of the input row to the canonical row. The closer the score is to 1, the more closely 
the row matches the canonical row. 


Similarity threshold 

Set the similarity threshold by using the slider. The closer the threshold is to 1, the more the rows must resemble 
each other to qualify as duplicates. Increasing the threshold can improve the speed of matching because fewer 
candidate records have to be considered. 


Token delimiters 
The transformation provides a default set of delimiters for tokenizing data, but you can add or remove 
delimiters as needed by editing the list. 


See Also 


Fuzzy Lookup Transformation 


Integration Services Transformations 


Identify Similar Data Rows with the Fuzzy Grouping 


sTeclasie)saaciilela 


11/23/2021 + 2 minutes to read * Edit Online 





Applies to: Q sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


To add and configure a Fuzzy Grouping transformation, the package must already include at least one Data Flow 
task and a source. 


To implement Fuzzy Grouping transformation in a data flow 


1. In SQL Server Data Tools (SSDT), open the Integration Services project that contains the package you 
want. 


2. In Solution Explorer, double-click the package to open it. 


3. Click the Data Flow tab, and then, from the Toolbox, drag the Fuzzy Grouping transformation to the 
design surface. 


4. Connect the Fuzzy Grouping transformation to the data flow by dragging the connector from the data 
source or a previous transformation to the Fuzzy Grouping transformation. 


5. Double-click the Fuzzy Grouping transformation. 


6. In the Fuzzy Grouping Transformation Editor dialog box, on the Connection Manager tab, select 
an OLE DB connection manager that connects to a SQL Server database. 





NOTE 


The transformation requires a connection to a SQL Server database to create temporary tables and indexes. 





7. Click the Columns tab and, in the Available Input Columns list, select the check box of the input 
columns to use to identify similar rows in the dataset. 


8. Select the check box in the Pass Through column to identify the input columns to pass through to the 
transformation output. Pass-through columns are not included in the process of identification of 
duplicate rows. 





NOTE 


Input columns that are used for grouping are automatically selected as pass-through columns, and they cannot 
be unselected while used for grouping. 








9. Optionally, update the names of output columns in the Output Alias column. 


10. Optionally, update the names of cleaned columns in the Group OutputAlias column. 





NOTE 


The default names of columns are the names of the input columns with a "_clean" suffix. 





11. Optionally, update the type of match to use in the Match Type column. 


12. 


13: 


14. 


1S. 


16. 


ee 


18. 


19. 


20. 





NOTE 


At least one column must use fuzzy matching. 





Specify the minimum similarity level columns in the Minimum Similarity column. The value must be 


between 0 and 1. The closer the value is to 1, the more similar the values in the input columns must be to 
form a group. A minimum similarity of 1 indicates an exact match. 


Optionally, update the names of similarity columns in the Similarity Output Alias column. 
To specify the handling of numbers in data values, update the values in the Numerals column. 


To specify how the transformation compares the string data in a column, modify the default selection of 
comparison options in the Comparison Flags column. 


Click the Advanced tab to modify the names of the columns that the transformation adds to the output 
for the unique row identifier (_key_in), the duplicate row identifier (_key_out), and the similarity value 
(_score). 


Optionally, adjust the similarity threshold by moving the slider bar. 
Optionally, clear the token delimiter check boxes to ignore delimiters in the data. 
Click OK. 


To save the updated package, click Save Selected Items on the File menu. 


See Also 


Fuzzy Grouping Transformation 


Integration Services Transformations 


Integration Services Paths 
Data Flow Task 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


The Fuzzy Lookup transformation performs data cleaning tasks such as standardizing data, correcting data, and 
providing missing values. 





NOTE 


For more detailed information about the Fuzzy Lookup transformation, including performance and memory limitations, 
see the white paper, Fuzzy Lookup and Fuzzy Grouping in SQL Server Integration Services 2005. 





The Fuzzy Lookup transformation differs from the Lookup transformation in its use of fuzzy matching. The 
Lookup transformation uses an equi-join to locate matching records in the reference table. It returns records 
with at least one matching record, and returns records with no matching records. In contrast, the Fuzzy Lookup 


transformation uses fuzzy matching to return one or more close matches in the reference table. 


A Fuzzy Lookup transformation frequently follows a Lookup transformation in a package data flow. First, the 
Lookup transformation tries to find an exact match. If it fails, the Fuzzy Lookup transformation provides close 
matches from the reference table. 


The transformation needs access to a reference data source that contains the values that are used to clean and 
extend the input data. The reference data source must be a table in a SQL Server database. The match between 
the value in an input column and the value in the reference table can be an exact match or a fuzzy match. 
However, the transformation requires at least one column match to be configured for fuzzy matching. If you 
want to use only exact matching, use the Lookup transformation instead. 


This transformation has one input and one output. 


Only input columns with the DT_WSTR and DT_STR data types can be used in fuzzy matching. Exact matching 
can use any DTS data type except DT_TEXT, DT_NTEXT, and DT_IMAGE. For more information, see Integration 
Services Data Types. Columns that participate in the join between the input and the reference table must have 
compatible data types. For example, it is valid to join a column with the DTS DT_WSTR data type to a column 
with the SQL Server nvarchar data type, but invalid to join a column with the DT_WSTR data type to a column 
with the int data type. 


You can customize this transformation by specifying the maximum amount of memory, the row comparison 
algorithm, and the caching of indexes and reference tables that the transformation uses. 


The amount of memory that the Fuzzy Lookup transformation uses can be configured by setting the 
MaxMemoryUsage custom property. You can specify the number of megabytes (MB), or use the value 0, which 
lets the transformation use a dynamic amount of memory based on its needs and the physical memory 
available. The MaxMemoryUsage custom property can be updated by a property expression when the package 
is loaded. For more information, see Integration Services (SSIS) Expressions, Use Property Expressions in 
Packages, and Transformation Custom Properties. 


Controlling Fuzzy Matching Behavior 


The Fuzzy Lookup transformation includes three features for customizing the lookup it performs: maximum 
number of matches to return per input row, token delimiters, and similarity thresholds. 





The transformation returns zero or more matches up to the number of matches specified. Specifying a 
maximum number of matches does not guarantee that the transformation returns the maximum number of 
matches; it only guarantees that the transformation returns at most that number of matches. If you set the 
maximum number of matches to a value greater than 1, the output of the transformation may include more 


than one row per lookup and some of the rows may be duplicates. 


The transformation provides a default set of delimiters used to tokenize the data, but you can add token 
delimiters to suit the needs of your data. The Delimiters property contains the default delimiters. Tokenization is 
important because it defines the units within the data that are compared to each other. 


The similarity thresholds can be set at the component and join levels. The join-level similarity threshold is only 
available when the transformation performs a fuzzy match between columns in the input and the reference 
table. The similarity range is 0 to 1. The closer to 1 the threshold is, the more similar the rows and columns must 
be to qualify as duplicates. You specify the similarity threshold by setting the MinSimilarity property at the 
component and join levels. To satisfy the similarity that is specified at the component level, all rows must have a 
similarity across all matches that is greater than or equal to the similarity threshold that is specified at the 
component level. That is, you cannot specify a very close match at the component level unless the matches at 


the row or join level are equally close. 


Each match includes a similarity score and a confidence score. The similarity score is a mathematical measure of 
the textural similarity between the input record and the record that Fuzzy Lookup transformation returns from 
the reference table. The confidence score is a measure of how likely it is that a particular value is the best match 
among the matches found in the reference table. The confidence score assigned to a record depends on the 
other matching records that are returned. For example, matching St and Sa/ntreturns a low similarity score 
regardless of other matches. If Sa/ntis the only match returned, the confidence score is high. If both Saintand St 
appear in the reference table, the confidence in Sz is high and the confidence in Saintis low. However, high 
similarity may not mean high confidence. For example, if you are looking up the value Chapter 4, the returned 
results Chapter 7, Chapter 2,and Chapter 3 have a high similarity score but a low confidence score because it is 
unclear which of the results is the best match. 


The similarity score is represented by a decimal value between 0 and 1, where a similarity score of 1 means an 
exact match between the value in the input column and the value in the reference table. The confidence score, 
also a decimal value between 0 and 1, indicates the confidence in the match. If no usable match is found, 
similarity and confidence scores of 0 are assigned to the row, and the output columns copied from the reference 


table will contain null values. 


Sometimes, Fuzzy Lookup may not locate appropriate matches in the reference table. This can occur if the input 
value that is used in a lookup is a single, short word. For example, Ae/o is not matched with the value he//oin a 


reference table when no other tokens are present in that column or any other column in the row. 


The transformation output columns include the input columns that are marked as pass-through columns, the 


selected columns in the lookup table, and the following additional columns: 
e Similarity, a column that describes the similarity between values in the input and reference columns. 
e _Confidence, a column that describes the quality of the match. 


The transformation uses the connection to the SQL Server database to create the temporary tables that the 
fuzzy matching algorithm uses. 


Running the Fuzzy Lookup Transformation 


When the package first runs the transformation, the transformation copies the reference table, adds a key with 
an integer data type to the new table, and builds an index on the key column. Next, the transformation builds an 
index, called a match index, on the copy of the reference table. The match index stores the results of tokenizing 
the values in the transformation input columns, and the transformation then uses the tokens in the lookup 


operation. The match index is a table in a SQL Server database. 


When the package runs again, the transformation can either use an existing match index or create a new index. If 
the reference table is static, the package can avoid the potentially expensive process of rebuilding the index for 
repeat sessions of data cleaning. If you choose to use an existing index, the index is created the first time that the 
package runs. If multiple Fuzzy Lookup transformations use the same reference table, they can all use the same 
index. To reuse the index, the lookup operations must be identical; the lookup must use the same columns. You 
can name the index and select the connection to the SQL Server database that saves the index. 


If the transformation saves the match index, the match index can be maintained automatically. This means that 
every time a record in the reference table is updated, the match index is also updated. Maintaining the match 
index can save processing time, because the index does not have to be rebuilt when the package runs. You can 
specify how the transformation manages the match index. 


The following table describes the match index options. 
OPTION DESCRIPTION 


GenerateAndMaintainNewIndex Create a new index, save it, and maintain it. The 
transformation installs triggers on the reference table to 
keep the reference table and index table synchronized. 


GenerateAndPersistNewIndex Create a new index and save it, but do not maintain it. 
GenerateNew!ndex Create a new index, but do not save it. 
ReuseExistingIndex Reuse an existing index. 


Maintenance of the Match Index Table 


The GenerateAndMaintainNew!Index option installs triggers on the reference table to keep the match index 
table and the reference table synchronized. If you have to remove the installed trigger, you must run the 
sp_FuzzyLookupTableMaintenanceUnInstall stored procedure, and provide the name specified in the 
MatchIndexName property as the input parameter value. 


You should not delete the maintained match index table before running the 
sp_FuzzyLookupTableMaintenanceUnInstall stored procedure. If the match index table is deleted, the 
triggers on the reference table will not execute correctly. All subsequent updates to the reference table will fail 
until you manually drop the triggers on the reference table. 


The SQL TRUNCATE TABLE command does not invoke DELETE triggers. If the TRUNCATE TABLE command is 
used on the reference table, the reference table and the match index will no longer be synchronized and the 
Fuzzy Lookup transformation fails. While the triggers that maintain the match index table are installed on the 
reference table, you should use the SQL DELETE command instead of the TRUNCATE TABLE command. 


NOTE 


When you select Maintain stored index on the Reference Table tab of the Fuzzy Lookup Transformation Editor, 
the transformation uses managed stored procedures to maintain the index. These managed stored procedures use the 
common language runtime (CLR) integration feature in SQL Server. By default, CLR integration in SQL Server is not 
enabled. To use the Maintain stored index functionality, you must enable CLR integration. For more information, see 
Enabling CLR Integration. 


Because the Maintain stored index option requires CLR integration, this feature works only when you select a 


reference table on an instance of SQL Server where CLR integration is enabled. 








Row Comparison 


When you configure the Fuzzy Lookup transformation, you can specify the comparison algorithm that the 
transformation uses to locate matching records in the reference table. If you set the Exhaustive property to True, 
the transformation compares every row in the input to every row in the reference table. This comparison 
algorithm may produce more accurate results, but it is likely to make the transformation perform more slowly 
unless the number of rows is the reference table is small. If the Exhaustive property is set to True, the entire 
reference table is loaded into memory. To avoid performance issues, it is advisable to set the Exhaustive 


property to True during package development only. 


If the Exhaustive property is set to False, the Fuzzy Lookup transformation returns only matches that have at 
least one indexed token or substring (the substring is called a g-gram) in common with the input record. To 
maximize the efficiency of lookups, only a subset of the tokens in each row in the table is indexed in the inverted 
index structure that the Fuzzy Lookup transformation uses to locate matches. When the input dataset is small, 
you can set Exhaustive to True to avoid missing matches for which no common tokens exist in the index table. 


Caching of Indexes and Reference Tables 


When you configure the Fuzzy Lookup transformation, you can specify whether the transformation partially 
caches the index and reference table in memory before the transformation does its work. If you set the 
WarmCaches property to True, the index and reference table are loaded into memory. When the input has many 
rows, setting the WarmCaches property to True can improve the performance of the transformation. When the 
number of input rows is small, setting the WarmCaches property to False can make the reuse of a large index 
faster. 


Temporary Tables and Indexes 


At run time, the Fuzzy Lookup transformation creates temporary objects, such as tables and indexes, in the SQL 
Server database that the transformation connects to. The size of these temporary tables and indexes is 
proportionate to the number of rows and tokens in the reference table and the number of tokens that the Fuzzy 
Lookup transformation creates; therefore, they could potentially consume a significant amount of disk space. 
The transformation also queries these temporary tables. You should therefore consider connecting the Fuzzy 
Lookup transformation to a non-production instance of a SQL Server database, especially if the production 
server has limited disk space available. 


The performance of this transformation may improve if the tables and indexes it uses are located on the local 
computer. If the reference table that the Fuzzy Lookup transformation uses is on the production server, you 
should consider copying the table to a non-production server and configuring the Fuzzy Lookup transformation 
to access the copy. By doing this, you can prevent the lookup queries from consuming resources on the 
production server. In addition, if the Fuzzy Lookup transformation maintains the match index-that is, if 
MatchIndexOptionsis set to GenerateAndMaintainNew!Index-the transformation may lock the reference table 
for the duration of the data cleaning operation and prevent other users and applications from accessing the 
table. 


Configuring the Fuzzy Lookup Transformation 


You can set properties through SSIS Designer or programmatically. 


For more information about the properties that you can set in the Advanced Editor dialog box or 
programmatically, click one of the following topics: 


@ Common Properties 


e Transformation Custom Properties 


Related Tasks 


For details about how to set properties of a data flow component, see Set the Properties of a Data Flow 
Component. 


Fuzzy Lookup Transformation Editor (Reference Table Tab) 


Use the Reference Table tab of the Fuzzy Lookup Transformation Editor dialog box to specify the source 


table and the index to use for the lookup. The reference data source must be a table in a SQL Server database. 





NOTE 


that updates the working table and the lookup index table based on changes to the reference table. 


NOTE 


these properties, see the Fuzzy Lookup Transformation section of Transformation Custom Properties. 





Options 
OLE DB connection manager 
Select an existing OLE DB connection manager from the list, or create a new connection by clicking New. 


New 
Create a new connection by using the Configure OLE DB Connection Manager dialog box. 


Generate new index 


Specify that the transformation should create a new index to use for the lookup. 


Reference table name 
Select the existing table to use as the reference (lookup) table. 


Store new index 


Select this option if you want to save the new lookup index. 


New index name 


If you have chosen to save the new lookup index, type a descriptive name for the index. 


Maintain stored index 


The Fuzzy Lookup transformation creates a working copy of the reference table. The indexes described below are created 
on this working table by using a special table, not an ordinary SQL Server index. The transformation does not modify the 


existing source tables unless you select Maintain stored index. In this case, it creates a trigger on the reference table 


The Exhaustive and the MaxMemoryUsage properties of the Fuzzy Lookup transformation are not available in the 
Fuzzy Lookup Transformation Editor, but can be set by using the Advanced Editor. In addition, a value greater 
than 100 for MaxOutputMatchesPerInput can be specified only in the Advanced Editor. For more information on 





If you have chosen to save the new lookup index, specify whether you also want SQL Server to maintain the 


index. 





NOTE 

When you select Maintain stored index on the Reference Table tab of the Fuzzy Lookup Transformation Editor, 
the transformation uses managed stored procedures to maintain the index. These managed stored procedures use the 
common language runtime (CLR) integration feature in SQL Server. By default, CLR integration in SQL Server is not 
enabled. To use the Maintain stored index functionality, you must enable CLR integration. For more information, see 


Enabling CLR Integration. 


Because the Maintain stored index option requires CLR integration, this feature works only when you select a 


reference table on an instance of SQL Server where CLR integration is enabled. 





Use existing index 
Specify that the transformation should use an existing index for the lookup. 


Name of an existing index 


Select a previously created lookup index from the list. 


Fuzzy Lookup Transformation Editor (Columns Tab) 


Use the Columns tab of the Fuzzy Lookup Transformation Editor dialog box to set properties for input and 


output columns. 


Options 

Available Input Columns 

Drag input columns to connect them to available lookup columns. These columns must have matching, 
supported data types. Select a mapping line and right-click to edit the mappings in the Create Relationships 
dialog box. 


Name 
View the names of the available input columns. 


Pass Through 
Specify whether to include the input columns in the output of the transformation. 


Available Lookup Columns 
Use the check boxes to select columns on which to perform fuzzy lookup operations. 


Lookup Column 

Select lookup columns from the list of available reference table columns. Your selections are reflected in the 
check box selections in the Available Lookup Columns table. Selecting a column in the Available Lookup 
Columns table creates an output column that contains the reference table column value for each matching row 


returned. 


Output Alias 
Type an alias for the output for each lookup column. The default is the name of the lookup column with a 


numeric index value appended; however, you can choose any unique, descriptive name. 


Fuzzy Lookup Transformation Editor (Advanced Tab) 


Use the Advanced tab of the Fuzzy Lookup Transformation Editor dialog box to set parameters for the 
fuzzy lookup. 


Options 
Maximum number of matches to output per lookup 
Specify the maximum number of matches the transformation can return for each input row. The default is 1. 





Similarity threshold 

Set the similarity threshold at the component level by using the slider. The closer the value is to 1, the closer the 
resemblance of the lookup value to the source value must be to qualify as a match. Increasing the threshold can 
improve the speed of matching since fewer candidate records need to be considered. 


Token delimiters 
Specify the delimiters that the transformation uses to tokenize column values. 


See Also 


Lookup Transformation 
Fuzzy Grouping Transformation 


Integration Services Transformations 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


The Import Column transformation reads data from files and adds the data to columns in a data flow. Using this 
transformation, a package can add text and images stored in separate files to a data flow. For example, a data 
flow that loads data into a table that stores product information can include the Import Column transformation 
to import customer reviews of each product from files and add the reviews to the data flow. 


You can configure the Import Column transformation in the following ways: 
e Specify the columns to which the transformation adds data. 


e Specify whether the transformation expects a byte-order mark (BOM). 





NOTE 
A BOM is only expected if the data has the DT_NTEXT data type. 





A column in the transformation input contains the names of files that hold the data. Each row in the dataset can 
specify a different file. When the Import Column transformation processes a row, it reads the file name, opens 
the corresponding file in the file system, and loads the file content into an output column. The data type of the 
output column must be DT_TEXT, DT_NTEXT, or DT_IMAGE. For more information, see Integration Services Data 
Types. 


This transformation has one input, one output, and one error output. 


Configuration of the Import Column Transformation 


You can set properties through SSIS Designer or programmatically. 


The Advanced Editor dialog box reflects the properties that can be set programmatically. For more 
information about the properties that you can set in the Advanced Editor dialog box or programmatically, click 
one of the following topics: 


e Common Properties 


e Transformation Custom Properties 


Related Tasks 


For information about how to set properties of this component, see Set the Properties of a Data Flow 
Component. 


See Also 


Export Column Transformation 
Data Flow 


Integration Services Transformations 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


The Lookup transformation performs lookups by joining data in input columns with columns in a reference 
dataset. You use the lookup to access additional information in a related table that is based on values in 
common columns. 


The reference dataset can be a cache file, an existing table or view, a new table, or the result of an SQL query. The 
Lookup transformation uses either an OLE DB connection manager or a Cache connection manager to connect 
to the reference dataset. For more information, see OLE DB Connection Manager and Cache Connection 
Manager 


You can configure the Lookup transformation in the following ways: 


e Select the connection manager that you want to use. If you want to connect to a database, select an OLE 
DB connection manager. If you want to connect to a cache file, select a Cache connection manager. 


e Specify the table or view that contains the reference dataset. 

e Generate a reference dataset by specifying an SQL statement. 

e Specify joins between the input and the reference dataset. 

e Add columns from the reference dataset to the Lookup transformation output. 

e Configure the caching options. 

The Lookup transformation supports the following database providers for the OLE DB connection manager: 
e SQL Server 

e Oracle 


e DB2 


The Lookup transformation tries to perform an equi-join between values in the transformation input and values 
in the reference dataset. (An equi-join means that each row in the transformation input must match at least one 
row from the reference dataset.) If an equi-join is not possible, the Lookup transformation takes one of the 
following actions: 


e If there is no matching entry in the reference dataset, no join occurs. By default, the Lookup 
transformation treats rows without matching entries as errors. However, you can configure the Lookup 
transformation to redirect such rows to a no match output. 


e If there are multiple matches in the reference table, the Lookup transformation returns only the first 
match returned by the lookup query. If multiple matches are found, the Lookup transformation generates 
an error or warning only when the transformation has been configured to load all the reference dataset 
into the cache. In this case, the Lookup transformation generates a warning when the transformation 
detects multiple matches as the transformation fills the cache. 


The join can be a composite join, which means that you can join multiple columns in the transformation input to 
columns in the reference dataset. The transformation supports join columns with any data type, except for 
DT_R4, DT_R8, DT_TEXT, DT_NTEXT, or DT_IMAGE. For more information, see Integration Services Data Types. 


Typically, values from the reference dataset are added to the transformation output. For example, the Lookup 
transformation can extract a product name from a table using a value from an input column, and then add the 
product name to the transformation output. The values from the reference table can replace column values or 
can be added to new columns. 


The lookups performed by the Lookup transformation are case sensitive. To avoid lookup failures that are 
caused by case differences in data, first use the Character Map transformation to convert the data to uppercase 
or lowercase. Then, include the UPPER or LOWER functions in the SQL statement that generates the reference 
table. For more information, see Character Map Transformation, UPPER (Transact-SQL), and LOWER (Transact- 
SQL). 


The Lookup transformation has the following inputs and outputs: 
e Input. 


e Match output. The match output handles the rows in the transformation input that match at least one 
entry in the reference dataset. 


e No Match output. The no match output handles rows in the input that do not match at least one entry in 
the reference dataset. If you configure the Lookup transformation to treat the rows without matching 
entries as errors, the rows are redirected to the error output. Otherwise, the transformation would 
redirect those rows to the no match output. 


e Error output. 


Caching the Reference Dataset 


An in-memory cache stores the reference dataset and stores a hash table that indexes the data. The cache 
remains in memory until the execution of the package is completed. You can persist the cache to a cache file 
(.caw). 


When you persist the cache to a file, the system loads the cache faster. This improves the performance of the 
Lookup transformation and the package. Remember, that when you use a cache file, you are working with data 
that is not as current as the data in the database. 


The following are additional benefits of persisting the cache to a file: 


e Share the cache file between multiple packages. For more information, see |mplement a 
Lookup Transformation in Full Cache Mode Using the Cache Connection Manager . 


e Deploy the cache file with a package. You can then use the data on multiple computers. For more 
information, see Create and Deploy a Cache for the Lookup Transformation. 


e Use the Raw File source to read data from the cache file. You can then use other data flow components to 
transform or move the data. For more information, see Raw File Source. 





NOTE 


The Cache connection manager does not support cache files that are created or modified by using the Raw File 


destination. 








e Perform operations and set attributes on the cache file by using the File System task. For more 
information, see and File System Task. 


The following are the caching options: 


e The reference dataset is generated by using a table, view, or SQL query and loaded into cache, before the 
Lookup transformation runs. You use the OLE DB connection manager to access the dataset. 


This caching option is compatible with the full caching option that is available for the Lookup 
transformation in SQL Server 2005 Integration Services (SSIS). 


e The reference dataset is generated from a connected data source in the data flow or from a cache file, and 
is loaded into cache before the Lookup transformation runs. You use the Cache connection manager, and, 
optionally, the Cache transformation, to access the dataset. For more information, see Cache Connection 
Manager and Cache Transform. 


e The reference dataset is generated by using a table, view, or SQL query during the execution of the 
Lookup transformation. The rows with matching entries in the reference dataset and the rows without 
matching entries in the dataset are loaded into cache. 


When the memory size of the cache is exceeded, the Lookup transformation automatically removes the 
least frequently used rows from the cache. 


This caching option is compatible with the partial caching option that is available for the Lookup 
transformation in SQL Server 2005 Integration Services (SSIS). 


e The reference dataset is generated by using a table, view, or SQL query during the execution of the 
Lookup transformation. No data is cached. 


This caching option is compatible with the no caching option that is available for the Lookup 
transformation in SQL Server 2005 Integration Services (SSIS). 


Integration Services and SQL Server differ in the way they compare strings. If the Lookup transformation is 
configured to load the reference dataset into cache before the Lookup transformation runs, Integration Services 
does the lookup comparison in the cache. Otherwise, the lookup operation uses a parameterized SQL statement 
and SQL Server does the lookup comparison. This means that the Lookup transformation might return a 
different number of matches from the same lookup table depending on the cache type. 


Related Tasks 


You can set properties through SSIS Designer or programmatically. For more details, see the following topics. 
e Implement a Lookup in No Cache or Partial Cache Mode 

e Implement a Lookup Transformation in Full Cache Mode Using the Cache Connection Manager 

e Implement a Lookup Transformation in Full Cache Mode Using the OLE DB Connection Manager 


e Set the Properties of a Data Flow Component 


Related Content 


e Video, How to: Implement a Lookup Transformation in Full Cache Mode, on msdn.microsoft.com 
e Blog entry, Best Practices for Using the Lookup Transformation Cache Modes, on blogs.msdn.com 


e Blog entry, Lookup Pattern: Case Insensitive, on blogs.msdn.com 


Lookup Transformation Editor (General Page) 


Use the General page of the Lookup Transformation Editor dialog box to select the cache mode, select the 
connection type, and specify how to handle rows with no matching entries. 


Options 
Full cache 
Generate and load the reference dataset into cache before the Lookup transformation is executed. 


Partial cache 
Generate the reference dataset during the execution of the Lookup transformation. Load the rows with matching 


entries in the reference dataset and the rows with no matching entries in the dataset into cache. 


No cache 
Generate the reference dataset during the execution of the Lookup transformation. No data is loaded into cache. 


Cache connection manager 
Configure the Lookup transformation to use a Cache connection manager. This option is available only if the Full 
cache option is selected. 


OLE DB connection manager 
Configure the Lookup transformation to use an OLE DB connection manager. 


Specify how to handle rows with no matching entries 
Select an option for handling rows that do not match at least one entry in the reference dataset. 


When you select Redirect rows to no match output, the rows are redirected to a no match output and are 
not handled as errors. The Error option on the Error Output page of the Lookup Transformation Editor 
dialog box is not available. 


When you select any other option in the Specify how to handle rows with no matching entries list box, 
the rows are handled as errors. The Error option on the Error Output page is available. 


External Resources 


Blog entry, Lookup cache modes on blogs.msdn.com 


Lookup Transformation Editor (Connection Page) 


Use the Connection page of the Lookup Transformation Editor dialog box to select a connection manager. If 
you select an OLE DB connection manager, you also select a query, table, or view to generate the reference 
dataset. 


Options 
The following options are available when you select Full cache and Cache connection manager on the 
General page of the Lookup Transformation Editor dialog box. 


Cache connection manager 
Select an existing Cache connection manager from the list, or create a new connection by clicking New. 


New 
Create a new connection by using the Cache Connection Manager Editor dialog box. 


The following options are available when you select Full cache, Partial cache, or No cache, and OLE DB 
connection manager, on the General page of the Lookup Transformation Editor dialog box. 


OLE DB connection manager 
Select an existing OLE DB connection manager from the list, or create a new connection by clicking New. 


New 
Create a new connection by using the Configure OLE DB Connection Manager dialog box. 


Use a table or view 


Select an existing table or view from the list, or create a new table by clicking New. 





NOTE 
If you specify a SQL statement on the Advanced page of the Lookup Transformation Editor, that SQL statement 
overrides and replaces the table name selected here. For more information, see Lookup Transformation Editor (Advanced 


Page). 





New 
Create a new table by using the Create Table dialog box. 


Use results of an SQL query 
Choose this option to browse to a preexisting query, build a new query, check query syntax, and preview query 
results. 


Build query 
Create the Transact-SQL statement to run by using Query Builder, a graphical tool that is used to create 
queries by browsing through data. 


Browse 
Use this option to browse to a preexisting query saved as a file. 


Parse Query 
Check the syntax of the query. 


Preview 
Preview results by using the Preview Query Results dialog box. This option displays up to 200 rows. 


External Resources 


Blog entry, Lookup cache modes on blogs.msdn.com 


Lookup Transformation Editor (Columns Page) 


Use the Columns page of the Lookup Transformation Editor dialog box to specify the join between the 
source table and the reference table, and to select lookup columns from the reference table. 


Options 

Available Input Columns 

View the list of available input columns. The input columns are the columns in the data flow from a connected 
source. The input columns and lookup column must have matching data types. 


Use a drag-and-drop operation to map available input columns to lookup columns. 


You can also map input columns to lookup columns using the keyboard, by highlighting a column in the 
Available Input Columns table, pressing the Application key, and then clicking Edit Mappings. 


Available Lookup Columns 
View the list of lookup columns. The lookup columns are columns in the reference table in which you want to 
look up values that match the input columns. 


Use a drag-and-drop operation to map available lookup columns to input columns. 
Use the check boxes to select lookup columns in the reference table on which to perform lookup operations. 


You can also map lookup columns to input columns using the keyboard, by highlighting a column in the 
Available Lookup Columns table, pressing the Application key, and then clicking Edit Mappings. 


Lookup Column 
View the selected lookup columns. The selections are reflected in the check box selections in the Available 





Lookup Columns table. 


Lookup Operation 
Select a lookup operation from the list to perform on the lookup column. 


Output Alias 
Type an alias for the output for each lookup column. The default is the name of the lookup column; however, you 
can select any unique, descriptive name. 


Lookup Transformation Editor (Advanced Page) 


Use the Advanced page of the Lookup Transformation Editor dialog box to configure partial caching and to 
modify the SQL statement for the Lookup transformation. 


Options 
Cache size (32-bit) 
Adjust the cache size (in megabytes) for 32-bit computers. The default value is 5 megabytes. 


Cache size (64-bit) 
Adjust the cache size (in megabytes) for 64-bit computers. The default value is 5 megabytes. 


Enable cache for rows with no matching entries 


Cache rows with no matching entries in the reference dataset. 


Allocation from cache 
Specify the percentage of the cache to allocate for rows with no matching entries in the reference dataset. 


Modify the SQL statement 
Modify the SQL statement that is used to generate the reference dataset. 


NOTE 

The optional SQL statement that you specify on this page overrides and replaces the table name that you specified on the 
Connection page of the Lookup Transformation Editor. For more information, see Lookup Transformation Editor 
(Connection Page). 











Set Parameters 
Map input columns to parameters by using the Set Query Parameters dialog box. 


External Resources 


Blog entry, Lookup cache modes on blogs.msdn.com 


See Also 


Fuzzy Lookup Transformation 

Term Lookup Transformation 

Data Flow 

Integration Services Transformations 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 
You can configure the Lookup transformation to use the partial cache or no cache mode: 
e Partial cache 


The rows with matching entries in the reference dataset and, optionally, the rows without matching 
entries in the dataset are stored in cache. When the memory size of the cache is exceeded, the Lookup 
transformation automatically removes the least frequently used rows from the cache. 


e Nocache 
No data is loaded into cache. 


Whether you select partial cache or no cache, you use an OLE DB connection manager to connect to the 
reference dataset. The reference dataset is generated by using a table, view, or SQL query during the execution 
of the Lookup transformation 


To implement a Lookup transformation in no cache or partial cache mode 


1. In SQL Server Data Tools (SSDT), open the Integration Services project that contains the package you 
want, and then open the package. 


2. On the Data Flow tab, add a Lookup transformation. 


3. Connect the Lookup transformation to the data flow by dragging a connector from a source or a previous 


transformation to the Lookup transformation. 





NOTE 


A Lookup transformation that is configured to use the no cache mode might not validate if that transformation 
connects to a flat file that contains an empty date field. Whether the transformation validates depends on whether 
the connection manager for the flat file has been configured to retain null values. To ensure that the Lookup 
transformation validates, in the Flat File Source Editor, on the Connection Manager Page, select the Retain 
null values from the source as null values in the data flow option. 








4. Double-click the source or previous transformation to configure the component. 


5. Double-click the Lookup transformation, and then in the Lookup Transformation Editor, on the 
General page, select Partialcache or No cache. 


6. For Specify how to handle rows with no matching entries list, select an error handling option from 
the list. 


7. On the Connection page, select a connection manager from the OLE DB connection manager list or 
click New to create a new connection manager. For more information, see OLE DB Connection Manager. 


8. Do one of the following steps: 


e@ Click Use a table or a view, and then either select a table or view, or click New to create a table 
or view. 


10. 


1A 


12. 


13; 


14. 


e Click Use results of an SQL query, and then build a query in the SQL Command window. 
-or- 
Click Build Query to build a query by using the graphical tools that the Query Builder provides. 
-or- 
Click Browse to import an SQL statement from a file. 
To validate the SQL query, click Parse Query. 


To view a sample of the data, click Preview. 


. Click the Columns page, and then drag at least one column from the Available Input Columns list to a 


column in the Available Lookup Column list. 


NOTE 


The Lookup transformation automatically maps columns that have the same name and the same data type. 


NOTE 


Columns must have matching data types to be mapped. For more information, see Integration Services Data 


Types. 





Include lookup columns in the output by doing the following steps: 
a. From the Available Lookup Columns list, select columns. 


b. In Lookup Operation list, specify whether the values from the lookup columns replace values in 
the input column or are written to a new column. 


If you selected Partial cache in step 5, on the Advanced page, set the following cache options: 
e From the Cache size (32-bit) list, select the cache size for 32-bit environments. 
e From the Cache size (64-bit) list, select the cache size for 64-bit environments. 


e To cache the rows without matching entries in the reference, select Enable cache for rows with 
no matching entries. 


e From the Allocation from cache list, select the percentage of the cache to use to store the rows 
without matching entries. 


To modify the SQL statement that generates the reference dataset, select Modify the SQL statement, 
and change the SQL statement displayed in the text box. 


If the statement includes parameters, click Parameters to map the parameters to input columns. 








NOTE 


The optional SQL statement that you specify on this page overrides and replaces the table name that you 
specified on the Connection page of the Lookup Transformation Editor. 








To configure the error output, click the Error Output page and set the error handling options. For more 
information, see Lookup Transformation Editor (Error Output Page). 


Click OK to save your changes to the Lookup transformation, and then run the package. 


See Also 


Integration Services Transformations 


Lookup Transformation Full Cache Mode - Cache 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


You can configure the Lookup transformation to use full cache mode and a Cache connection manager. In full 
cache mode, the reference dataset is loaded into cache before the Lookup transformation runs. 


NOTE 


The Cache connection manager does not support the Binary Large Object (BLOB) data types DT_TEXT, DT_NTEXT, and 
DT_IMAGE. If the reference dataset contains a BLOB data type, the component will fail when you run the package. You can 
use the Cache Connection Manager Editor to modify column data types. For more information, see Cache 
Connection Manager Editor. 











The Lookup transformation performs lookups by joining data in input columns from a connected data source 
with columns in a reference dataset. For more information, see Lookup Transformation. 


You use one of the following to generate a reference dataset: 
e@ Cache file (.caw) 

You configure the Cache connection manager to read data from an existing cache file. 
e Connected data source in the data flow 


You use a Cache Transform transformation to write data from a connected data source in the data flow to 
a Cache connection manager. The data is always stored in memory. 


You must add the Lookup transformation to a separate data flow. This enables the Cache Transform to 
populate the Cache connection manager before the Lookup transformation is executed. The data flows 
can be in the same package or in two separate packages. 


If the data flows are in the same package, use a precedence constraint to connect the data flows. This 
enables the Cache Transform to run before the Lookup transformation runs. 


If the data flows are in separate packages, you can use the Execute Package task to call the child package 
from the parent package. You can call multiple child packages by adding multiple Execute Package tasks 
to a Sequence Container task in the parent package. 


You can share the reference dataset stored in cache, between multiple Lookup transformations by using one of 
the following methods: 


e Configure the Lookup transformations in a single package to use the same Cache connection manager. 
e Configure the Cache connection managers in different packages to use the same cache file. 

For more information, see the following topics: 

@ Cache Transform 

@ Cache Connection Manager 


e@ Precedence Constraints 


e@ Execute Package Task 
e Sequence Container 


For a video that demonstrates how to implement a Lookup transformation in Full Cache mode using the Cache 
connection manager, see How to: Implement a Lookup Transformation in Full Cache Mode (SQL Server Video). 


To implement a Lookup transformation in full cache mode in one package by using Cache connection 
manager and a data source in the data flow 


1. In SQL Server Data Tools (SSDT), open a Integration Services project, and then open a package. 


2. On the Control Flow tab, add two Data Flow tasks, and then connect the tasks by using a green 
connector: 


3. In the first data flow, add a Cache Transform transformation, and then connect the transformation to a 
data source. 


Configure the data source as needed. 


4. Double-click the Cache Transform, and then in the Cache Transformation Editor, on the Connection 
Manager page, click New to create a new Cache connection manager. 


5. Click the Columns tab of the Cache Connection Manager Editor dialog box, and then specify which 
columns are the index columns by using the Index Position option. 


For non-index columns, the index position is 0. For index columns, the index position is a sequential, 
positive number. 





NOTE 


When the Lookup transformation is configured to use a Cache connection manager, only index columns in the 


reference dataset can be mapped to input columns. Also, all index columns must be mapped. For more 


information, see Cache Connection Manager Editor. 








6. To save the cache to a file, in the Cache Connection Manager Editor, on the General tab, configure 
the Cache connection manager by setting the following options: 


e Select Use file cache. 
e For File name, either type the file path or click Browse to select the file. 


If you type a path for a file that does not exist, the system creates the file when you run the 
package. 


NOTE 
The protection level of the package does not apply to the cache file. If the cache file contains sensitive information, 
use an access control list (ACL) to restrict access to the location or folder in which you store the file. You should 


enable access only to certain accounts. For more information, see Access to Files Used by Packages. 








7. Configure the Cache Transform as needed. For more information, see Cache Transformation Editor 
(Connection Manager Page) and Cache Transformation Editor (Mappings Page). 


8. In the second data flow, add a Lookup transformation, and then configure the transformation by doing 
the following tasks: 


a. Connect the Lookup transformation to the data flow by dragging a connector from a source or a 


j. 


previous transformation to the Lookup transformation. 


NOTE 

A Lookup transformation might not validate if that transformation connects to a flat file that contains an 
empty date field. Whether the transformation validates depends on whether the connection manager for 
the flat file has been configured to retain null values. To ensure that the Lookup transformation validates, 
in the Flat File Source Editor, on the Connection Manager Page, select the Retain null values 
from the source as null values in the data flow option. 











Double-click the source or previous transformation to configure the component. 


Double-click the Lookup transformation, and then in the Lookup Transformation Editor, on the 
General page, select Full cache. 


In the Connection type area, select Cache connection manager. 


From the Specify how to handle rows with no matching entries list, select an error handling 
option. 


. On the Connection page, from the Cache connection manager list, select a Cache connection 


Manager. 


. Click the Columns page, and then drag at least one column from the Available Input Columns 


list to a column in the Available Lookup Column list. 


NOTE 
The Lookup transformation automatically maps columns that have the same name and the same data 


type. 


NOTE 
Columns must have matching data types to be mapped. For more information, see Integration Services 


Data Types. 





. In the Available Lookup Columns list, select columns. Then in the Lookup Operation list, 


specify whether the values from the lookup columns replace values in the input column or are 


written to a new column. 


. To configure the error output, click the Error Output page and set the error handling options. For 


more information, see Lookup Transformation Editor (Error Output Page). 


Click OK to save your changes to the Lookup transformation. 


9. Run the package. 


To implement a Lookup transformation in full cache mode in two packages by using Cache connection 
manager and a data source in the data flow 


1. In SQL Server Data Tools (SSDT), open a Integration Services project, and then open two packages. 


2. On the Control Flow tab in each package, add a Data Flow task. 


3. In the parent package, add a Cache Transform transformation to the data flow, and then connect the 


transformation to a data source. 


Configure the data source as needed. 





4. Double-click the Cache Transform, and then in the Cache Transformation Editor, on the Connection 


10. 


Manager page, click New to create a new Cache connection manager. 


. Inthe Cache Connection Manager Editor, on the General tab, configure the Cache connection 
manager by setting the following options: 


e Select Use file cache. 
e For File name, either type the file path or click Browse to select the file. 


If you type a path for a file that does not exist, the system creates the file when you run the 
package. 





NOTE 


The protection level of the package does not apply to the cache file. If the cache file contains sensitive information, 
use an access control list (ACL) to restrict access to the location or folder in which you store the file. You should 


enable access only to certain accounts. For more information, see Access to Files Used by Packages. 








Click the Columns tab, and then specify which columns are the index columns by using the Index 
Position option. 


For non-index columns, the index position is 0. For index columns, the index position is a sequential, 
positive number. 





NOTE 


When the Lookup transformation is configured to use a Cache connection manager, only index columns in the 


reference dataset can be mapped to input columns. Also, all index columns must be mapped. For more 


information, see Cache Connection Manager Editor. 








. Configure the Cache Transform as needed. For more information, see Cache Transformation Editor 


(Connection Manager Page) and Cache Transformation Editor (Mappings Page). 


. Do one of the following to populate the Cache connection manager that is used in the second package: 


e Run the parent package. 


e Double-click the Cache connection manager you created in step 4, click Columns, select the rows, 
and then press CTRL+C to copy the column metadata. 


. In the child package, create a Cache connection manager by right-clicking in the Connection Managers 


area, clicking New Connection, selecting CACHE in the Add SSIS Connection Manager dialog box, 
and then clicking Add. 


The Connection Managers area appears on the bottom of the Control Flow, Data Flow, and Event 
Handlers tabs of Integration Services Designer. 


In the Cache Connection Manager Editor, on the General tab, configure the Cache connection 
manager to read the data from the cache file that you selected by setting the following options: 


e Select Use file cache. 


e For File name, either type the file path or click Browse to select the file. 





NOTE 


The protection level of the package does not apply to the cache file. If the cache file contains sensitive information, 


use an access control list (ACL) to restrict access to the location or folder in which you store the file. You should 


enable access only to certain accounts. For more information, see Access to Files Used by Packages. 








11. If you copied the column metadata in step 8, click Columns, select the empty row, and then press 
CTRL+V to paste the column metadata. 


12. Add a Lookup transformation, and then configure the transformation by doing the following: 


a. Connect the Lookup transformation to the data flow by dragging a connector from a source or a 
previous transformation to the Lookup transformation. 





NOTE 


A Lookup transformation might not validate if that transformation connects to a flat file that contains an 
empty date field. Whether the transformation validates depends on whether the connection manager for 
the flat file has been configured to retain null values. To ensure that the Lookup transformation validates, 
in the Flat File Source Editor, on the Connection Manager Page, select the Retain null values 
from the source as null values in the data flow option. 











b. Double-click the source or previous transformation to configure the component. 


c. Double-click the Lookup transformation, and then select Full cache on the General page of the 
Lookup Transformation Editor. 


d. Select Cache connection manager in the Connection type area. 


e. Select an error handling option for rows without matching entries from the Specify how to 
handle rows with no matching entries list. 


f. On the Connection page, from the Cache connection manager list, select the Cache 
connection manager that you added. 


g. Click the Columns page, and then drag at least one column from the Available Input Columns 
list to a column in the Available Lookup Column list. 





NOTE 
The Lookup transformation automatically maps columns that have the same name and the same data 


type. 








NOTE 


Columns must have matching data types to be mapped. For more information, see Integration Services 


Data Types. 








h. In the Available Lookup Columns list, select columns. Then in the Lookup Operation list, 
specify whether the values from the lookup columns replace values in the input column or are 
written to a new column. 


i. To configure the error output, click the Error Output page and set the error handling options. For 
more information, see Lookup Transformation Editor (Error Output Page). 


j. Click OK to save your changes to the Lookup transformation. 


13. Open the parent package, add an Execute Package task to the control flow, and then configure the task to 


call the child package. For more information, see Execute Package Task. 


14. Run the packages. 


To implement a Lookup transformation in full cache mode by using Cache connection manager and an 
existing cache file 


1. 


2. 


In SQL Server Data Tools (SSDT), open a Integration Services project, and then open a package. 
Right-click in the Connection Managers area, and then click New Connection. 


The Connection Managers area appears on the bottom of the Control Flow, Data Flow, and Event 
Handlers tabs of Integration Services Designer. 


. Inthe Add SSIS Connection Manager dialog box, select CACHE, and then click Add to add a Cache 


connection manager. 


. Double-click the Cache connection manager to open the Cache Connection Manager Editor. 


. Inthe Cache Connection Manager Editor, on the General tab, configure the Cache connection 


manager by setting the following options: 
e Select Use file cache. 


e For File name, either type the file path or click Browse to select the file. 





NOTE 


The protection level of the package does not apply to the cache file. If the cache file contains sensitive information, 
use an access control list (ACL) to restrict access to the location or folder in which you store the file. You should 


enable access only to certain accounts. For more information, see Access to Files Used by Packages. 








Click the Columns tab, and then specify which columns are the index columns by using the Index 
Position option. 


For non-index columns, the index position is 0. For index columns, the index position is a sequential, 


positive number. 





NOTE 


When the Lookup transformation is configured to use a Cache connection manager, only index columns in the 
reference dataset can be mapped to input columns. Also, all index columns must be mapped. For more 
information, see Cache Connection Manager Editor. 








On the Control Flow tab, add a Data Flow task to the package, and then add a Lookup transformation to 
the data flow. 


Configure the Lookup transformation by doing the following: 


a. Connect the Lookup transformation to the data flow by dragging a connector from a source or a 
previous transformation to the Lookup transformation. 





NOTE 

A Lookup transformation might not validate if that transformation connects to a flat file that contains an 
empty date field. Whether the transformation validates depends on whether the connection manager for 
the flat file has been configured to retain null values. To ensure that the Lookup transformation validates, 
in the Flat File Source Editor, on the Connection Manager Page, select the Retain null values 
from the source as null values in the data flow option. 





b. Double-click the source or previous transformation to configure the component. 


c. Double-click the Lookup transformation, and then in the Lookup Transformation Editor, on the 
General page, select Full cache. 


d. Select Cache connection manager in the Connection type area. 


e. Select an error handling option for rows without matching entries from the Specify how to 
handle rows with no matching entries list. 


f. On the Connection page, from the Cache connection manager list, select the Cache 
connection manager that you added. 


g. Click the Columns page, and then drag at least one column from the Available Input Columns 
list to a column in the Available Lookup Column list. 








NOTE 
The Lookup transformation automatically maps columns that have the same name and the same data 


type. 








NOTE 
Columns must have matching data types to be mapped. For more information, see Integration Services 


Data Types. 











h. In the Available Lookup Columns list, select columns. Then in the Lookup Operation list, 
specify whether the values from the lookup columns replace values in the input column or are 


written to a new column. 


. To configure the error output, click the Error Output page and set the error handling options. For 


more information, see Lookup Transformation Editor (Error Output Page). 
j. Click OK to save your changes to the Lookup transformation. 


9. Run the package. 


See Also 


Implement a Lookup Transformation in Full Cache Mode Using the OLE DB Connection Manager 
Implement a Lookup in No Cache or Partial Cache Mode 
Integration Services Transformations 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


You can configure the Lookup transformation to use full cache mode and an OLE DB connection manager. In the 
full cache mode, the reference dataset is loaded into cache before the Lookup transformation runs. 


The Lookup transformation performs lookups by joining data in input columns from a connected data source 
with columns in a reference dataset. For more information, see Lookup Transformation. 


When you configure the Lookup transformation to use an OLE DB connection manager, you select a table, view, 
or SQL query to generate the reference dataset. 


To implement a Lookup transformation in full cache mode by using OLE DB connection manager 


1. In SQL Server Data Tools (SSDT), open the Integration Services project that contains the package you 
want, and then double-click the package in Solution Explorer. 


2. On the Data Flow tab, from the Toolbox, drag the Lookup transformation to the design surface. 


3. Connect the Lookup transformation to the data flow by dragging a connector from a source or a previous 


transformation to the Lookup transformation. 





NOTE 


A Lookup transformation might not validate if that transformation connects to a flat file that contains an empty 
date field. Whether the transformation validates depends on whether the connection manager for the flat file has 
been configured to retain null values. To ensure that the Lookup transformation validates, in the Flat File Source 
Editor, on the Connection Manager Page, select the Retain null values from the source as null values 
in the data flow option. 








4. Double-click the source or previous transformation to configure the component. 


5. Double-click the Lookup transformation, and then in the Lookup Transformation Editor, on the 
General page, select Full cache. 


6. In the Connection type area, select OLE DB connection manager. 


7. In the Specify how to handle rows with no matching entries list, select an error handling option 
for rows without matching entries. 


8. On the Connection page, select a connection manager from the OLE DB connection manager list or 


click New to create a new connection manager. For more information, see OLE DB Connection Manager. 
9. Do one of the following tasks: 


e Click Use a table or a view, and then either select a table or view, or click New to create a table 
or view. 


-or- 


e Click Use results of an SQL query, and then build a query in the SQL Command window, or 
click Build Query to build a query by using the graphical tools that the Query Builder provides. 


10. 


-or- 
e Alternatively, click Browse to import an SQL statement from a file. 
To validate the SQL query, click Parse Query. 

To view a sample of the data, click Preview. 


Click the Columns page, and then from the Available Input Columns list, drag at least one column to 


a column in the Available Lookup Column list. 





NOTE 


The Lookup transformation automatically maps columns that have the same name and the same data type. 





NOTE 


Columns must have matching data types to be mapped. For more information, see Integration Services Data 


Types. 








11. Include lookup columns in the output by doing the following tasks: 
a. In the Available Lookup Columns list. select columns. 
b. In Lookup Operation list, specify whether the values from the lookup columns replace values in 

the input column or are written to a new column. 

12. To configure the error output, click the Error Output page and set the error handling options. For more 
information, see Lookup Transformation Editor (Error Output Page). 

13. Click OK to save your changes to the Lookup transformation, and then run the package. 

See Also 


Implement a Lookup Transformation in Full Cache Mode Using the Cache Connection Manager 


Implement a Lookup in No Cache or Partial Cache Mode 
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You can create and deploy a cache file (.caw) for the Lookup transformation. The reference dataset is stored in 
the cache file. 


The Lookup transformation performs lookups by joining data in input columns from a connected data source 
with columns in the reference dataset. 


You create a cache file by using a Cache connection manager and a Cache Transform transformation. For more 
information, see Cache Connection Manager and Cache Transform. 


To learn more about the Lookup transformation and cache files, see Lookup Transformation. 


To create a cache file 


1. In SQL Server Data Tools (SSDT), open the Integration Services project that contains the package you 
want, and then open the package. 


2. On the Control Flow tab, add a Data Flow task. 


3. On the Data Flow tab, add a Cache Transform transformation to the data flow, and then connect the 
transformation to a data source. 


Configure the data source as needed. 


4. Double-click the Cache Transform, and then in the Cache Transformation Editor, on the Connection 
Manager page, click New to create a new Cache connection manager. 


5. In the Cache Connection Manager Editor, on the General tab, configure the Cache connection 
manager to save the cache by selecting the following options: 


a. Select Use file cache. 
b. For File name, type the file path. 


The system creates the file when you run the package. 





NOTE 


The protection level of the package does not apply to the cache file. If the cache file contains sensitive information, 
use an access control list (ACL) to restrict access to the location or folder in which you store the file. You should 


enable access only to certain accounts. For more information, see Access to Files Used by Packages. 








6. Click the Columns tab, and then specify which columns are the index columns by using the Index 
Position option. 


For non-index columns, the index position is 0. For index columns, the index position is a sequential, 
positive number. 





NOTE 


When the Lookup transformation is configured to use a Cache connection manager, only index columns in the 


reference dataset can be mapped to input columns. Also all index columns must be mapped. 








For more information, see Cache Connection Manager Editor. 
7. Configure the Cache Transform as needed. 


For more information, see Cache Transformation Editor (Connection Manager Page) and Cache 
Transformation Editor (Mappings Page). 


8. Run the package. 


To deploy a cache file 


1. In SQL Server Data Tools (SSDT), open the Integration Services project that contains the package you 
want, and then open the package. 


2. Optionally, create a package configuration. For more information, see Create Package Configurations. 
3. Add the cache file to the project by doing the following: 

a. In Solution Explorer, select the project you opened in step 1. 

b. On the Project menu, click AddExisting Item. 

c. Select the cache file, and then click Add. 

The file appears in the Miscellaneous folder in Solution Explorer. 


4. Configure the project to create a deployment utility, and then build the project. For more information, see 
Create a Deployment Utility. 


A manifest file, < project name> .SS|SDeploymentManifest.xml, is created that lists the miscellaneous files 
in the project, the packages, and the package configurations. 


5. Deploy the package to the file system. For more information, see Deploy Packages by Using the 


Deployment Utility. 


See Also 


Create a Deployment Utility 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Use the Create Relationships dialog box to edit mappings between the source columns and the lookup table 
columns that you configured in the Fuzzy Lookup Transformation Editor, the Lookup Transformation Editor, and 
the Term Lookup Transformation Editor. 


NOTE 


The Create Relationships dialog box displays only the Input Column and Lookup Column lists when invoked from 
the Term Lookup Transformation Editor. 











To learn more about the transformations that use the Create Relationships dialog box, see Fuzzy Lookup 
Transformation, Lookup Transformation, and Term Lookup Transformation. 


Options 


Input Column 
Select from the list of available input columns. 


Lookup Column 
Select from the list of available lookup columns. 


Mapping Type 
Select fuzzy or exact matching. 


When you use fuzzy matching, rows are considered duplicates if they are sufficiently similar across all columns 
that have a fuzzy match type. To obtain better results from fuzzy matching, you can specify that some columns 
should use exact matching instead of fuzzy matching. For example, if you know that a certain column contains 
no errors or inconsistencies, you can specify exact matching on that column, so that only rows which contain 
identical values in this column are considered as possible duplicates. This increases the accuracy of fuzzy 
matching on other columns. 


Comparison Flags 
For information about the string comparison options, see Comparing String Data. 


Minimum Similarity 

Set the similarity threshold at the column level by using the slider. The closer the value is to 1, the more the 
lookup value must resemble the source value to qualify as a match. Increasing the threshold can improve the 
speed of matching because fewer candidate records have to be considered. 


Similarity Output Alias 
Specify the name for a new output column that contains the similarity scores for the selected column. If you 
leave this value empty, the output column is not created. 


See Also 


Integration Services Error and Message Reference 
Fuzzy Lookup Transformation Editor (Columns Tab) 
Lookup Transformation Editor (Columns Page) 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


The Cache Transform transformation generates a reference dataset for the Lookup Transformation by writing 
data from a connected data source in the data flow to a Cache connection manager. The Lookup transformation 
performs lookups by joining data in input columns from a connected data source with columns in the reference 
database. 


You can use the Cache connection manager when you want to configure the Lookup Transformation to run in 
the full cache mode. In this mode, the reference dataset is loaded into cache before the Lookup Transformation 
runs. 


For instructions on how to configure the Lookup transformation in full cache mode with the Cache connection 
manager and Cache Transform transformation, see Implement a Lookup Transformation in Full Cache Mode 
Using the Cache Connection Manager. 


For more information on caching the reference dataset, see Lookup Transformation. 





NOTE 


The Cache Transform writes only unique rows to the Cache connection manager. 





In a single package, only one Cache Transform can write data to the same Cache connection manager. If the 


package contains multiple Cache Transforms, the first Cache Transform that is called when the package runs, 
writes the data to the connection manager. The write operations of subsequent Cache Transforms fail. 


For more information, see Cache Connection Manager. 


Configuration of the Cache Transform 

You can configure the Cache connection manager to save the data to a cache file (.caw). 
You can configure the Cache Transform in the following ways: 

e Specify the Cache connection manager. 


e Map the input columns in the Cache Transform to destination columns in the Cache connection manager. 





NOTE 


Each input column must be mapped to a destination column, and the column data types must match. Otherwise, 
Integration Services Designer displays an error message. 








You can use the Cache Connection Manager Editor to modify column data types, names, and other 
column properties. 


You can set properties through Integration Services Designer. For more information about the properties that 
you can set in the Advanced Editor dialog box, see Transformation Custom Properties. 


For more information about how to set properties, see Set the Properties of a Data Flow Component. 


Cache Transformation Editor (Connection Manager Page) 


Use the Connection Manager page of the Cache Transformation Editor dialog box to select an existing 
Cache connection manager or create a new one. 


To learn more about the Cache connection manager, see Cache Connection Manager. 


Options 
Cache connection manager 


Select an existing Cache connection manager by using the list, or create a new connection by using the New 
button. 


New 
Create a new connection by using the Cache Connection Manager Editor dialog box. 


Edit 


Modify an existing connection. 


See Also 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


The Cache connection manager reads data from the Cache transform or from a cache file (.caw), and can save 
the data to a cache file. Whether you configure the Cache connection manager to use a cache file, the data is 
always stored in memory. 


The Cache Transform transformation writes data from a connected data source in the data flow to a Cache 
connection manager. The Lookup transformation in a package performs lookups on the data. 


NOTE 

The Cache connection manager does not support the Binary Large Object (BLOB) data types DT_TEXT, DT_NTEXT, and 
DT_IMAGE. If the reference dataset contains a BLOB data type, the component will fail when you run the package. You can 
use the Cache Connection Manager Editor to modify column data types. For more information, see Cache 
Connection Manager Editor. 








NOTE 
The protection level of the package does not apply to the cache file. If the cache file contains sensitive information, use an 
access control list (ACL) to restrict access to the location or folder in which you store the file. You should enable access 


only to certain accounts. For more information, see Access to Files Used by Packages. 





Configuration of the Cache Connection Manager 


You can configure the Cache connection manager in the following ways: 
e Indicate whether to use a cache file. 


If you configure the cache connection manager to use a cache file, the connection manager will do one of 
the following actions: 


o Save data to the file when a Cache Transform transformation is configured to write data from a 
data source in the data flow to the Cache connection manager. 


o Read data from the cache file. 
For more information, see Cache Transform. 
e Change metadata for the columns stored in the cache. 


e Update the cache file name at runtime by using an expression to set the ConnectionString property. For 
more information, see Use Property Expressions in Packages. 


You can set properties through Integration Services Designer or programmatically. 


For information about how to configure a connection manager programmatically, see ConnectionManager and 


Adding Connections Programmatically. 


Cache Connection Manager Editor 





The Cache connection manager reads a reference dataset from the Cache transform or from a cache file (.caw), 
and can save the data to a cache file. The data is always stored in memory. 





NOTE 


The Cache connection manager does not support the Binary Large Object (BLOB) data types DT_TEXT, DT_NTEXT, and 
DT_IMAGE. If the reference dataset contains a BLOB data type, the component will fail when you run the package. You can 
use the Cache Connection Manager Editor to modify column data types. 





The Lookup transformation performs lookups on the reference dataset. 
The Cache Connection ManagerEditor dialog box includes the following tabs: 


General Tab 


Use the General tab of the Cache Connection ManagerEditor dialog box to indicate whether to read the 
cache from a file or save the cache to a file. 


Options 

Connection manager name 

Provide a unique name for the cache connection in the workflow. The name provided will be displayed within 
SSIS Designer. 


Description 
Describe the connection. As a best practice, describe the connection according to its purpose, to make packages 
self-documenting and easier to maintain. 


Use file cache 
Indicate whether to use a cache file. 








NOTE 
The protection level of the package does not apply to the cache file. If the cache file contains sensitive information, use an 
access control list (ACL) to restrict access to the location or folder in which you store the file. You should enable access 


only to certain accounts. For more information, see Access to Files Used by Packages. 





If you configure the cache connection manager to use a cache file, the connection manager will do one of the 
following actions: 


e Save data to the file when a Cache Transform transformation is configured to write data from a data 
source in the data flow to the Cache connection manager. For more information, see Cache Transform. 


e Read data from the cache file. 


File name 
Type the path and file name of the cache file. 


Browse 


Locate the cache file. 


Refresh Metadata 
Delete the column metadata in the Cache connection manager and repopulate the Cache connection manager 
with column metadata from a selected cache file. 


Columns Tab 


Use the Columns tab of the Cache Connection Manager Editor dialog box to configure the properties of 
each column in the cache. 





Options 
Column 
Specify the column name. 


Index Position 
Specify which columns are index columns by specifying the index position of each column. The index is a 


collection of one or more columns. 
For non-index columns, the index position is 0. 


For index columns, the index position is a sequential, positive number. This number indicates the order in which 
the Lookup transformation compares rows in the reference dataset to rows in the input data source. The column 
with the most unique values should have the lowest index position. 


NOTE 


When the Lookup transformation is configured to use a Cache connection manager, only index columns in the reference 


dataset can be mapped to input columns. Also, all index columns must be mapped. 











Type 
Specify the data type of the column. 


Length 
Specifies the column data type. If applicable to the data type, you can update Length. 


Precision 
Specifies the precision for certain column data types. Precision is the number of digits in a number. If applicable 
to the data type, you can update Precision. 


Scale 
Specifies the scale for certain column data types. Scale is the number of digits to the right of the decimal point in 
a number. If applicable to the data type, you can update Scale. 


Code Page 
Specifies the code page for the column type. If applicable to the data type, you can update Code Page. 


Related Tasks 


Implement a Lookup Transformation in Full Cache Mode Using the Cache Connection Manager 


Merge Transformation 
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The Merge transformation combines two sorted datasets into a single dataset. The rows from each dataset are 
inserted into the output based on values in their key columns. 


By including the Merge transformation in a data flow, you can perform the following tasks: 
e Merge data from two data sources, such as tables and files. 

e Create complex datasets by nesting Merge transformations. 

e Remerge rows after correcting errors in the data. 


The Merge transformation is similar to the Union All transformations. Use the Union All transformation instead 
of the Merge transformation in the following situations: 


e The transformation inputs are not sorted. 
e The combined output does not need to be sorted. 


e The transformation has more than two inputs. 


Input Requirements 


The Merge Transformation requires sorted data for its inputs. For more information about this important 
requirement, see Sort Data for the Merge and Merge Join Transformations. 


The Merge transformation also requires that the merged columns in its inputs have matching metadata. For 
example, you cannot merge a column that has a numeric data type with a column that has a character data type. 
If the data has a string data type, the length of the column in the second input must be less than or equal to the 
length of the column in the first input with which it is merged. 


In the SSIS Designer, the user interface for the Merge transformation automatically maps columns that have the 
same metadata. You can then manually map other columns that have compatible data types. 


This transformation has two inputs and one output. It does not support an error output. 


Configuration of the Merge Transformation 

You can set properties through the SSIS Designer or programmatically. 

For more information about the properties that you can programmatically, click one of the following topics: 
e Common Properties 


e Transformation Custom Properties 


Related Tasks 
For details about how to set properties, see the following topics: 


e Set the Properties of a Data Flow Component 


e Sort Data for the Merge and Merge Join Transformations 


Merge Transformation Editor 


Use the Merge Transformation Editor to specify columns from two sorted sets of data to be merged. 





IMPORTANT 


The Merge Transformation requires sorted data for its inputs. For more information about this important requirement, 


see Sort Data for the Merge and Merge Join Transformations. 











Options 
Output Column Name 
Specify the name of the output column. 


Merge Input 1 
Select the column to merge as Merge Input 1. 


Merge Input 2 
Select the column to merge as Merge Input 2. 


See Also 


Merge Join Transformation 
Union All Transformation 
Data Flow 


Integration Services Transformations 


Merge Join Transformation 
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The Merge Join transformation provides an output that is generated by joining two sorted datasets using a 
FULL, LEFT, or INNER join. For example, you can use a LEFT join to join a table that includes product information 
with a table that lists the country/region in which a product was manufactured. The result is a table that lists all 
products and their country/region of origin. 


You can configure the Merge Join transformation in the following ways: 
e Specify the join is a FULL, LEFT, or INNER join. 
e Specify the columns the join uses. 


e Specify whether the transformation handles null values as equal to other nulls. 


NOTE 


If null values are not treated as equal values, the transformation handles null values like the SQL Server Database 
Engine does. 





This transformation has two inputs and one output. It does not support an error output. 


Input Requirements 


The Merge Join Transformation requires sorted data for its inputs. For more information about this important 
requirement, see Sort Data for the Merge and Merge Join Transformations. 


Join Requirements 


The Merge Join transformation requires that the joined columns have matching metadata. For example, you 
cannot join a column that has a numeric data type with a column that has a character data type. If the data has a 
string data type, the length of the column in the second input must be less than or equal to the length of the 
column in the first input with which it is merged. 


Buffer Throttling 


You no longer have to configure the value of the MaxBuffersPerlnput property because Microsoft has made 
changes that reduce the risk that the Merge Join transformation will consume excessive memory. This problem 
sometimes occurred when the multiple inputs of the Merge Join produced data at uneven rates. 


Related Tasks 

You can set properties through the SSIS Designer or programmatically. 

For information about how to set properties of this transformation, click one of the following topics: 
e Extend a Dataset by Using the Merge Join Transformation 


e Set the Properties of a Data Flow Component 


e Sort Data for the Merge and Merge Join Transformations 


Merge Join Transformation Editor 


Use the Merge Join Transformation Editor dialog box to specify the join type, the join columns, and the 
output columns for merging two inputs combined by a join. 


IMPORTANT 


The Merge Join Transformation requires sorted data for its inputs. For more information about this important 


requirement, see Sort Data for the Merge and Merge Join Transformations. 





Options 


Join type 
Specify whether you want to use an inner join, left outer join, or full join. 


Swap Inputs 
Switch the order between inputs by using the Swap Inputs button. This selection may be useful with the Left 
outer join option. 


Input 
For each column that you want in the merged output, first select from the list of available inputs. 


Inputs are displayed in two separate tables. Select columns to include in the output. Drag columns to create a 
join between the tables. To delete a join, select it and then press the DELETE key. 


Input Column 
Select a column to include in the merged output from the list of available columns on the selected input. 


Output Alias 
Type an alias for each output column. The default is the name of the input column; however, you can choose any 
unique, descriptive name. 


See Also 


Merge Transformation 
Union All Transformation 


Integration Services Transformations 


Extend a Dataset by Using the Merge Join 
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To add and configure a Merge Join transformation, the package must already include at least one Data Flow task 
and two data flow components that provide inputs to the Merge Join transformation. 


The Merge Join transformation requires two sorted inputs. For more information, see Sort Data for the Merge 
and Merge Join Transformations. 


To extend a dataset 


1. In SQL Server Data Tools (SSDT), open the Integration Services project that contains the package you 
want. 


2. In Solution Explorer, double-click the package to open it. 


3. Click the Data Flow tab, and then, from the Toolbox, drag the Merge Join transformation to the design 
surface. 


4. Connect the Merge Join transformation to the data flow by dragging the connector from a data source or 
a previous transformation to the Merge Join transformation. 


5. Double-click the Merge Join transformation. 


6. In the Merge Join Transformation Editor dialog box, select the type of join to use in the Join type list. 


NOTE 


If you select the Left outer join type, you can click Swap Inputs to switch the inputs and convert the left outer 


join to a right outer join. 





7. Drag columns in the left input to columns in the right input to specify the join columns. If the columns 
have the same name, you can select the Join Key check box and the Merge Join transformation 
automatically creates the join. 





NOTE 

You can create joins only between columns that have the same sort position, and the joins must be created in the 
order specified by the sort position. If you attempt to create the joins out of order, the Merge Join 
Transformation Editor prompts you to create additional joins for the skipped sort order positions. 








NOTE 


By default, the output is sorted on the join columns. 








8. In the left and right inputs, select the check boxes of additional columns to include in the output. Join 
columns are included by default. 


9. Optionally, update the names of output columns in the Output Alias column. 


10. Click OK. 


11. To save the updated package, click Save Selected Items on the File menu. 


See Also 


Merge Join Transformation 
Integration Services Transformations 
Integration Services Paths 

Data Flow Task 


Sort Data for the Merge and Merge Join 
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In Integration Services, the Merge and Merge Join transformations require sorted data for their inputs. The input 
data must be sorted physically, and sort options must be set on the outputs and the output columns in the 
source or in the upstream transformation. If the sort options indicate that the data is sorted, but the data is not 
actually sorted, the results of the merge or merge join operation are unpredictable. 


Sorting the Data 
You can sort this data by using one of the following methods: 
e Inthe source, use an ORDER BY clause in the statement that is used to load the data. 


e Inthe data flow, insert a Sort transformation before the Merge or Merge Join transformation. 


If the data is string data, both the Merge and Merge Join transformations expect the string values to have been 
sorted by using Windows collation. To provide string values to the Merge and Merge Join transformations that 
are sorted by using Windows collation, use the following procedure. 


To provide string values that are sorted by using Windows collation 


e Use a Sort transformation to sort the data. 
The Sort transformation uses Windows collation to sort string values. 


-or- 


e Use the Transact-SQL CAST operator to first cast varchar values to nvarchar values, and then use the 
Transact-SQL ORDER BY clause to sort the data. 





IMPORTANT 


You cannot use the ORDER BY clause alone because the ORDER BY clause uses a SQL Server collation to sort 
string values. The use of the SQL Server collation might result in a different sort order than Windows collation, 
which can cause the Merge or Merge Join transformation to produce unexpected results. 








Setting Sort Options on the Data 


There are two important sort properties that must be set for the source or upstream transformation that 
supplies data to the Merge and Merge Join transformations: 


e ThelsSorted property of the output that indicates whether the data has been sorted. This property must 
be set to True. 





IMPORTANT 


Setting the value of the IsSorted property to True does not sort the data. This property only provides a hint to 
downstream components that the data has been previously sorted. 








e The SortKeyPosition property of output columns that indicates whether a column is sorted, the 
column's sort order, and the sequence in which multiple columns are sorted. This property must be set 
for each column of sorted data. 


If you use a Sort transformation to sort the data, the Sort transformation sets both of these properties as 
required by the Merge or Merge Join transformation. That is, the Sort transformation sets the IsSorted 
property of its output to True, and sets the SortKeyPosition properties of its output columns. 


However, if you do not use a Sort transformation to sort the data, you must set these sort properties manually 
on the source or the upstream transformation. To manually set the sort properties on the source or upstream 
transformation, use the following procedure. 


To manually set sort attributes on a source or transformation component 


1. In SQL Server Data Tools (SSDT), open the Integration Services project that contains the package you 
want. 


2. In Solution Explorer, double-click the package to open it. 


3. On the Data Flow tab, locate the appropriate source or upstream transformation, or drag it from the 
Toolbox to the design surface. 


4. Right-click the component and click Show Advanced Editor. 
5. Click the Input and Output Properties tab. 


6. Click <component name> Output, and set the IsSorted property to True. 





NOTE 


If you manually set the IsSorted property of the output to True and the data is not sorted, there might be 
missing data or bad data comparisons in the downstream Merge or Merge Join transformation when you run the 


package. 








7. Expand Output Columns. 


8. Click the column that you want to indicate is sorted and set its SortKeyPosition property to a nonzero 
integer value by following these guidelines: 


e The integer value must represent a numeric sequence, starting with 1 and incremented by 1. 
e A positive integer value indicates an ascending sort order. 


e Anegative integer value indicates a descending sort order. (If set to a negative number, the 
absolute value of the number determines the column's position in the sort sequence.) 


e The default value of 0 indicates that the column is not sorted. Leave the value of 0 for output 
columns that do not participate in the sort. 


As an example of how to set the SortKeyPosition property, consider the following Transact-SQL 
statement that loads data in a source: 


SELECT * FROM MyTable ORDER BY ColumnA, ColumnB DESC, ColumnC 
For this statement, you would set the SortKeyPosition property for each column as follows: 


e Set the SortKeyPosition property of ColumnA to 1. This indicates that ColumnA is the first 
column to be sorted and is sorted in ascending order. 


e Set the SortKeyPosition property of ColumnB to -2. This indicates that ColumnB is the second 
column to be sorted and is sorted in descending order 


e Set the SortKeyPosition property of ColumnC to 3. This indicates that ColumnC is the third 
column to be sorted and is sorted in ascending order. 


9. Repeat step 8 for each sorted column. 
10. Click OK. 


11. To save the updated package, click Save Selected Items on the File menu. 


See Also 


Merge Transformation 

Merge Join Transformation 
Integration Services Transformations 
Integration Services Paths 

Data Flow Task 
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The Multicast transformation distributes its input to one or more outputs. This transformation is similar to the 
Conditional Split transformation. Both transformations direct an input to multiple outputs. The difference 
between the two is that the Multicast transformation directs every row to every output, and the Conditional Split 
directs a row to a single output. For more information, see Conditional Split Transformation. 


You configure the Multicast transformation by adding outputs. 


Using the Multicast transformation, a package can create logical copies of data. This capability is useful when the 
package needs to apply multiple sets of transformations to the same data. For example, one copy of the data is 
aggregated and only the summary information is loaded into its destination, while another copy of the data is 
extended with lookup values and derived columns before it is loaded into its destination. 


This transformation has one input and multiple outputs. It does not support an error output. 


Configuration of the Multicast Transformation 


You can set properties through SSIS Designer or programmatically. 


For information about the properties that you can set programmatically, see Common Properties. 


Related Tasks 


For information about how to set properties of this component, see Set the Properties of a Data Flow 
Component. 


Multicast Transformation Editor 


Use the Multicast Transformation Editor dialog box to view and set the properties for each transformation 
output. 

Options 

Outputs 


Select an output on the left to view its properties in the table on the right. 


Properties 
All output properties listed are read-only except Name and Description. 


See Also 


Data Flow 


Integration Services Transformations 
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The OLE DB Command transformation runs an SQL statement for each row in a data flow. For example, you can 
run an SQL statement that inserts, updates, or deletes rows in a database table. 


You can configure the OLE DB Command Transformation in the following ways: 
e Provide the SQL statement that the transformation runs for each row. 

e Specify the number of seconds before the SQL statement times out. 

e Specify the default code page. 


Typically, the SQL statement includes parameters. The parameter values are stored in external columns in the 
transformation input, and mapping an input column to an external column maps an input column to a 
parameter. For example, to locate rows in the DimProduct table by the value in their ProductKey column and 
then delete them, you can map the external column named Param_0 to the input column named ProductKey, 
and then run the SQL statement DELETE FROM DimProduct WHERE ProductKey = ? .. Ihe OLE DB Command 
transformation provides the parameter names and you cannot modify them. The parameter names are 
Param_O, Param_1, and so on. 


If you configure the OLE DB Command transformation by using the Advanced Editor dialog box, the 
parameters in the SQL statement may be mapped automatically to external columns in the transformation input, 
and the characteristics of each parameter defined, by clicking the Refresh button. However, if the OLE DB 
provider that the OLE DB Command transformation uses does not support deriving parameter information 
from the parameter, you must configure the external columns manually. This means that you must add a column 
for each parameter to the external input to the transformation, update the column names to use names like 
Param_0, specify the value of the DBParamInfoFlags property, and map the input columns that contain 
parameter values to the external columns. 


The value of DBParamInfoFlags represents the characteristics of the parameter. For example, the value 1 
specifies that the parameter is an input parameter, and the value 65 specifies that the parameter is an input 
parameter and may contain a null value. The values must match the values in the OLE DB 
DBPARAMFLAGSENUM enumeration. For more information, see the OLE DB reference documentation. 


The OLE DB Command transformation includes the SQLCommand custom property. This property can be 
updated by a property expression when the package is loaded. For more information, see Integration Services 
(SSIS) Expressions, Use Property Expressions in Packages, and Transformation Custom Properties. 


This transformation has one input, one regular output, and one error output. 


Logging 

You can log the calls that the OLE DB Command transformation makes to external data providers. You can use 
this logging capability to troubleshoot the connections and commands to external data sources that the OLE DB 
Command transformation performs. To log the calls that the OLE DB Command transformation makes to 
external data providers, enable package logging and select the Diagnostic event at the package level. For more 
information, see Troubleshooting Tools for Package Execution. 


Related Tasks 


You can configure the transformation by either using the SSIS Designer or the object model. See the Developer 


Guide for details about programmatically configuring this transformation. 


Configure the OLE DB Command Transformation 


To add and configure an OLE DB Command transformation, the package must already include at least one Data 


Flow task and a source such as a Flat File source or an OLE DB source. This transformation is typically used for 


running parameterized queries. 


To configure the OLE DB Command transformation 


1. 


Malls 


12. 


13. 


In SQL Server Data Tools (SSDT), open the Integration Services project that contains the package you 
want. 


. In Solution Explorer, double-click the package to open it. 


. Click the Data Flow tab, and then, from the Toolbox, drag the OLE DB Command transformation to the 


design surface. 


. Connect the OLE DB Command transformation to the data flow by dragging a connector-the green or red 


arrow-from a data source or a previous transformation to the OLE DB Command transformation. 


. Right-click the component and select Edit or Show Advanced Editor. 


. On the Connection Managers tab, select an OLE DB connection manager in the Connection Manager 


list. For more information, see OLE DB Connection Manager. 


. Click the Component Properties tab and click the ellipsis button (...) in the SqlCommand box. 


. Inthe String Value Editor, type the parameterized SQL statement using a question mark (?) as the 


parameter marker for each parameter. 


. Click Refresh. When you click Refresh, the transformation creates a column for each parameter in the 


External Columns collection and sets the DBParamInfoFlags property. 


. Click the Input and Output Properties tab. 


Expand OLE DB Command Input, and then expand External Columns. 


Verify that External Columns lists a column for each parameter in the SQL statement. The column 


names are Param_O, Param_1, and so on. 


You should not change the column names. If you change the column names, Integration Services 


generates a validation error for the OLE DB Command transformation. 


Also, you should not change the data type. The DataType property of each column is set to the correct 
data type. 


If External Columns lists no columns you must add them manually. 
@ Click Add Column one time for each parameter in the SQL statement. 
e Update the column names to Param_0O, Param_1, and so on. 


e Specify a value in the DBParaminfoFlags property. The value must match a value in the OLE DB 
DBPARAMFLAGSENUM enumeration. For more information, see the OLE DB reference 
documentation. 


e Specify the data type of the column and, depending on the data type, specify the code page, length, 
precision, and scale of the column. 


e To delete an unused parameter, select the parameter in External Columns, and then click 


Remove Column. 


e Click Column Mappings and map columns in the Available Input Columns list to parameters 
in the Available Destination Columns list. 


14. Click OK. 


15. To save the updated package, click Save on the File menu. 


See Also 


Data Flow 
Integration Services Transformations 
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The Percentage Sampling transformation creates a sample data set by selecting a percentage of the 
transformation input rows. The sample data set is a random selection of rows from the transformation input, to 
make the resultant sample representative of the input. 


NOTE 


In addition to the specified percentage, the Percentage Sampling transformation uses an algorithm to determine whether 
a row should be included in the sample output. This means that the number of rows in the sample output may not 
exactly reflect the specified percentage. For example, specifying 10 percent for an input data set that has 25,000 rows may 
not generate a sample with 2,500 rows; the sample may have a few more or a few less rows. 











The Percentage Sampling transformation is especially useful for data mining. By using this transformation, you 
can randomly divide a data set into two data sets: one for training the data mining model, and one for testing 
the model. 


The Percentage Sampling transformation is also useful for creating sample data sets for package development. 
By applying the Percentage Sampling transformation to a data flow, you can uniformly reduce the size of the 
data set while preserving its data characteristics. The test package can then run more quickly because it uses a 
small, but representative, data set. 


Configuration the Percentage Sampling Transformation 


You can specify a sampling seed to modify the behavior of the random number generator that the 
transformation uses to select rows. If the same sampling seed is used, the transformation always creates the 
same sample output. If no seed is specified, the transformation uses the tick count of the operating system to 
create the random number. Therefore, you might choose to use a standard seed when you want to verify the 
transformation results during the development and testing of a package, and then change to use a random seed 
when the package is moved into production. 


This transformation is similar to the Row Sampling transformation, which creates a sample data set by selecting 


a specified number of the input rows. For more information, see Row Sampling Transformation. 


The Percentage Sampling transformation includes the SamplingValue custom property. This property can be 
updated by a property expression when the package is loaded. For more information, see Integration Services 
(SSIS) Expressions, Use Property Expressions in Packages, and Transformation Custom Properties. 


The transformation has one input and two outputs. It does not support an error output. 
You can set properties through SSIS Designer or programmatically. 


The Advanced Editor dialog box reflects the properties that can be set programmatically. For more 
information about the properties that you can set in the Advanced Editor dialog box or programmatically, click 
one of the following topics: 


@ Common Properties 


© Transformation Custom Properties 


For more information about how to set properties, see Set the Properties of a Data Flow Component. 


Percentage Sampling Transformation Editor 


Use the Percentage Sampling Transformation Editor dialog box to split part of an input into a sample using 
a specified percentage of rows. This transformation divides the input into two separate outputs. 


Options 
Percentage of rows 
Specify the percentage of rows in the input to use as a sample. 


The value of this property can be specified by using a property expression. 


Sample output name 
Provide a unique name for the output that will include the sampled rows. The name provided will be displayed 
within the SSIS Designer. 


Unselected output name 
Provide a unique name for the output that will contain the rows excluded from the sampling. The name 


provided will be displayed within the SSIS Designer. 


Use the following random seed 

Specify the sampling seed for the random number generator that the transformation uses to create a sample. 
This is only recommended for development and testing. The transformation uses the Microsoft Windows tick 
count if a random seed is not specified. 
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The Pivot transformation makes a normalized data set into a less normalized but more compact version by 
pivoting the input data on a column value. For example, a normalized Orders data set that lists customer name, 
product, and quantity purchased typically has multiple rows for any customer who purchased multiple products, 
with each row for that customer showing order details for a different product. By pivoting the data set on the 
product column, the Pivot transformation can output a data set with a single row per customer. That single row 
lists all the purchases by the customer, with the product names shown as column names, and the quantity 
shown as a value in the product column. Because not every customer purchases every product, many columns 
may contain null values. 


When a dataset is pivoted, input columns perform different roles in the pivoting process. A column can 
participate in the following ways: 


e The column is passed through unchanged to the output. Because many input rows can result only in one 
output row, the transformation copies only the first input value for the column. 


e@ The column acts as the key or part of the key that identifies a set of records. 


e The column defines the pivot. The values in this column are associated with columns in the pivoted 
dataset. 


e The column contains values that are placed in the columns that the pivot creates. 


This transformation has one input, one regular output, and one error output. 


Sort and Duplicate Rows 


To pivot data efficiently, which means creating as few records in the output dataset as possible, the input data 
must be sorted on the pivot column. If the data is not sorted, the Pivot transformation might generate multiple 
records for each value in the set key, which is the column that defines set membership. For example, if a dataset 
is pivoted on a Name column but the names are not sorted, the output dataset could have more than one row 
for each customer, because a pivot occurs every time that the value in Name changes. 


The input data might contain duplicate rows, which will cause the Pivot transformation to fail. "Duplicate rows" 
means rows that have the same values in the set key columns and the pivot columns. To avoid failure, you can 
either configure the transformation to redirect error rows to an error output or you can pre-aggregate values to 
ensure there are no duplicate rows. 


Options in the Pivot Dialog Box 


You configure the pivot operation by setting the options in the Pivot dialog box. To open the Pivot dialog box, 
add the Pivot transformation to the package in SQL Server Data Tools (SSDT), and then right-click the 
component and click Edit. 


The following list describes the options in the Pivot dialog box. 


Pivot Key 
Specifies the column to use for values across the top row (header row) of the table. 


Set Key 


Specifies the column to use for values in the left column of the table. The input date must be sorted on this 


column. 


Pivot Value 


Specifies the column to use for the table values, other than the values in the header row and the left column. 


Ignore un-matched Pivot Key values and report them after DataFlow execution 
Select this option to configure the Pivot transformation to ignore rows containing unrecognized values in the 
Pivot Key column and to output all of the pivot key values to a log message, when the package is run. 


You can also configure the transformation to output the values by setting the 
PassThroughUnmatchedPivotKeys custom property to True. 


Generate pivot output columns from values 
Enter the pivot key values in this box to enable the Pivot transformation to create output columns for each value. 


You can either enter the values prior to running the package, or do the following. 


1. Select the Ignore un-matched Pivot Key values and report them after DataFlow execution 
option, and then click OK in the Pivot dialog box to save the changes to the Pivot transformation. 


2. Run the package. 


3. When the package succeeds, click the Progress tab and look for the information log message from the 


Pivot transformation that contains the pivot key values. 
4. Right-click the message and click Copy Message Text. 
5. Click Stop Debugging on the Debug menu to switch to the design mode. 
6. Right-click the Pivot transformation, and then click Edit. 


7. Uncheck the Ignore un-matched Pivot Key values and report them after DataFlow execution 
option, and then paste the pivot key values in the Generate pivot output columns from values box 


using the following format. 
[value1],[value2],[value3] 


Generate Columns Now 
Click to create an output column for each pivot key value that is listed in the Generate pivot output columns 


from values box. 
The output columns appear in the Existing pivoted output columns box. 


Existing pivoted output columns 
Lists the output columns for the pivot key values 


The following table shows a data set before the data is pivoted on the Year column. 


YEAR PRODUCT NAME TOTAL 
2004 HL Mountain Tire 1504884.15 
2003 Road Tire Tube 35920.50 
2004 Water Bottle - 30 oz. 2805.00 
2002 Touring Tire 62364.225 


The following table shows a data set after the data has been pivoted on the Year column. 


PRODUCT NAME 2002 2003 2004 


HL Mountain Tire 141164.10 446297.775 1504884.15 
Road Tire Tube 3592.05 35920.50 89801.25 
Water Bottle - 30 oz. NULL NULL 2805.00 
Touring Tire 62364.225 375051.60 1041810.00 


To pivot the data on the Year column, as shown above, the following options are set in the Pivot dialog box. 
e Year is selected in the Pivot Key list box. 

e Product Name is selected in the Set Key list box. 

e Total is selected in the Pivot Value list box. 

e The following values are entered in the Generate pivot output columns from values box. 


[2002],[2003],[2004] 


Configuration of the Pivot Transformation 
You can set properties through SSIS Designer or programmatically. 


For more information about the properties that you can set in the Advanced Editor dialog box, click one of the 
following topics: 


@ Common Properties 


e Transformation Custom Properties 


Related Content 


For information about how to set the properties of this component, see Set the Properties of a Data Flow 
Component. 


See Also 


Unpivot Transformation 
Data Flow 


Integration Services Transformations 
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The Row Count transformation counts rows as they pass through a data flow and stores the final count ina 
variable. 


A SQL Server Integration Services package can use row counts to update the variables used in scripts, 
expressions, and property expressions. (For example, the variable that stores the row count can update the 
message text in an e-mail message to include the number of rows.) The variable that the Row Count 
transformation uses must already exist, and it must be in the scope of the Data Flow task to which the data flow 
with the Row Count transformation belongs. 


The transformation stores the row count value in the variable only after the last row has passed through the 
transformation. Therefore, the value of the variable is not updated in time to use the updated value in the data 
flow that contains the Row Count transformation. You can use the updated variable in a separate data flow. 


This transformation has one input and one output. It does not support an error output. 


Configuration of the Row Count Transformation 
You can set properties through SSIS Designer or programmatically. 


The Advanced Editor dialog box reflects the properties that can be set programmatically. For more 
information about the properties that you can set in the Advanced Editor dialog box or programmatically, click 
one of the following topics: 


e Common Properties 


© Transformation Custom Properties 


Related Tasks 


For information about how to set the properties of this component, see Set the Properties of a Data Flow 
Component. 


See Also 


Integration Services (SSIS) Variables 
Data Flow 


Integration Services Transformations 
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The Row Sampling transformation is used to obtain a randomly selected subset of an input dataset. You can 
specify the exact size of the output sample, and specify a seed for the random number generator. 


There are many applications for random sampling. For example, a company that wanted to randomly select 50 
employees to receive prizes in a lottery could use the Row Sampling transformation on the employee database 
to generate the exact number of winners. 


The Row Sampling transformation is also useful during package development for creating a small but 
representative dataset. You can test package execution and data transformation with richly representative data, 
but more quickly because a random sample is used instead of the full dataset. Because the sample dataset used 
by the test package is always the same size, using the sample subset also makes it easier to identify 
performance problems in the package. 


This transformation is similar to the Percentage Sampling transformation, which creates a sample dataset by 
selecting a percentage of the input rows. See Percentage Sampling Transformation. 


Configuring the Row Sampling Transformation 


The Row Sampling transformation creates a sample dataset by selecting a specified number of the 
transformation input rows. Because the selection of rows from the transformation input is random, the resultant 
sample is representative of the input. You can also specify the seed that is used by the random number 
generator, to affect how the transformation selects rows. 


Using the same random seed on the same transformation input always creates the same sample output. If no 
seed is specified, the transformation uses the tick count of the operating system to create the random number. 
Therefore, you could use the same seed during testing, to verify the transformation results during the 
development and testing of the package, and then change to a random seed when the package is moved into 
production. 


The Row Sampling transformation includes the SamplingValue custom property. This property can be updated 
by a property expression when the package is loaded. For more information, see Integration Services (SSIS) 
Expressions, Use Property Expressions in Packages, and Transformation Custom Properties. 


This transformation has one input and two outputs. It has no error output. 
You can set properties through SSIS Designer or programmatically. 


The Advanced Editor dialog box reflects the properties that can be set programmatically. For more 
information about the properties that you can set in the Advanced Editor dialog box or programmatically, click 
one of the following topics: 


e Common Properties 
e Transformation Custom Properties 


For more information about how to set properties, see. 


Row Sampling Transformation Editor (Sampling Page) 


Use the Row Sampling Transformation Editor dialog box to split a portion of an input into a sample using a 
specified number of rows. This transformation divides the input into two separate outputs. 


Options 
Number of rows 
Specify the number of rows from the input to use as a sample. 


The value of this property can be specified by using a property expression. 


Sample output name 
Provide a unique name for the output that will include the sampled rows. The name provided will be displayed 
within SSIS Designer. 


Unselected output name 
Provide a unique name for the output that will contain the rows excluded from the sampling. The name 


provided will be displayed within SSIS Designer. 


Use the following random seed 

Specify the sampling seed for the random number generator that the transformation uses to create a sample. 
This is only recommended for development and testing. The transformation uses the Microsoft Windows tick 
count as a seed if a random seed is not specified. 


Related Tasks 


Set the Properties of a Data Flow Component 


Script Component 
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The Script component hosts script and enables a package to include and run custom script code. You can use the 
Script component in packages for the following purposes: 


e Apply multiple transformations to data instead of using multiple transformations in the data flow. For 
example, a script can add the values in two columns and then calculate the average of the sum. 


e Access business rules in an existing .NET assembly. For example, a script can apply a business rule that 
specifies the range of values that are valid in an Income column. 


e Use custom formulas and functions in addition to the functions and operators that the Integration 
Services expression grammar provides. For example, validate credit card numbers that use the LUHN 
formula. 


e Validate column data and skip records that contain invalid data. For example, a script can assess the 
reasonableness of a postage amount and skip records with extremely high or low amounts. 


The Script component provides an easy and quick way to include custom functions in a data flow. However, if 
you plan to reuse the script code in multiple packages, you should consider programming a custom component 
instead of using the Script component. For more information, see Developing a Custom Data Flow Component. 


NOTE 


If the Script component contains a script that tries to read the value of a column that is NULL, the Script component fails 
when you run the package. We recommend that your script use the IsNull method to determine whether the column is 
NULL before trying to read the column value. 











The Script component can be used as a source, a transformation, or a destination. This component supports one 
input and multiple outputs. Depending on how the component is used, it supports either an input or outputs or 
both. The script is invoked by every row in the input or output. 


e If used as a source, the Script component supports multiple outputs. 

e If used as a transformation, the Script component supports one input and multiple outputs. 
e If used as a destination, the Script component supports one input. 

The Script component does not support error outputs. 


After you decide that the Script component is the appropriate choice for your package, you have to configure 
the inputs and outputs, develop the script that the component uses, and configure the component itself. 


Understanding the Script Component Modes 


In the SSIS Designer, the Script component has two modes: metadata-design mode and code-design mode. In 
metadata-design mode, you can add and modify the Script component inputs and outputs, but you cannot write 
code. After all the inputs and outputs are configured, you switch to code-design mode to write the script. The 
Script component automatically generates base code from the metadata of the inputs and outputs. If you 
change the metadata after the Script component generates the base code, your code may no longer compile 


because the updated base code may be incompatible with your code. 


Writing the Script that the Component Uses 


The Script component uses Microsoft Visual Studio Tools for Applications (VSTA) as the environment in which 
you write the scripts. You access VSTA from the Script Transformation Editor. For more information, see 
Script Transformation Editor (Script Page). 


The Script component provides a VSTA project that includes an auto-generated class, named ScriptMain, that 
represents the component metadata. For example, if the Script component is used as a transformation that has 


three outputs, ScriptMain includes a method for each output. ScriptMain is the entry point to the script. 


VSTA includes all the standard features of the Visual Studio environment, such as the color-coded Visual Studio 
editor, Intellisense, and Object Browser. The script that the Script component uses is stored in the package 
definition. When you are designing the package, the script code is temporarily written to a project file. 


VSTA supports the Microsoft Visual C# and Microsoft Visual Basic programming languages. 


For information about how to program the Script component, see Extending the Data Flow with the Script 
Component. For more specific information about how to configure the Script component as a source, 
transformation, or destination, see Developing Specific Types of Script Components. For additional examples 
such as an ODBC destination that demonstrate the use of the Script component, see Additional Script 
Component Examples. 


NOTE 
Unlike earlier versions where you could indicate whether the scripts were precompiled, all scripts are precompiled in SQL 
Server 2008 Integration Services (SSIS) and later versions. When a script is precompiled, the language engine is not 


loaded at run time and the package runs more quickly. However, precompiled binary files consume significant disk space. 











Configuring the Script Component 


You can configure the Script component in the following ways: 


e Select the input columns to reference. 





NOTE 


You can configure only one input when you use the SSIS Designer. 





Provide the script that the component runs. 


Specify the script language. 


Provide comma-separated lists of read-only and read/write variables. 


Add more outputs, and add output columns to which the script assigns. 
You can set properties through SSIS Designer or programmatically. 


Configuring the Script Component in the Designer 


For more information about how to set these properties in SSIS Designer, click the following topic: 
e Set the Properties of a Data Flow Component 


Configuring the Script Component Programmatically 


For more information about the properties that you can set in the Properties window or programmatically, 


click one of the following topics: 

@ Common Properties 

e Transformation Custom Properties 

For more information about how to set properties, click one of the following topics: 


e Set the Properties of a Data Flow Component 


Select Script Component Type 


Use the Select Script Component Type dialog box to specify whether to create a Script Transformation that is 
preconfigured for use as a source, a transformation, or a destination. 


To learn more about the Script component, see Configuring the Script Component in the Script Component 
Editor. To learn about programming the Script component, see Extending the Data Flow with the Script 
Component. 


Options 
Your selection of Source, Destination, or Transformation affects the configuration of the Script 
Transformation and the pages of the Script Transformation Editor. 


Script Transformation Editor (Connection Managers Page) 


Use the Connection Managers page of the Script Transformation Editor to specify any connections that 
will be used by the script. 


To learn more about the Script component, see Configuring the Script Component in the Script Component 
Editor. To learn about programming the Script component, see Extending the Data Flow with the Script 
Component. 


Options 
Connection managers 


View the list of connections available for use by the script. 


Name 
Type a unique and descriptive name for the connection. 


Connection Manager 
Select from the list of available connection managers, or select <New connection> to open the Add SSIS 
Connection Manager dialog box. 


Description 
Type a description for the connection. 


Add 
Add another connection to the Connection managers list. 


Remove 
Remove the selected connection from the Connection managers list. 


Script Transformation Editor (Input Columns Page) 


Use the Input Columns page of the Script Transformation Editor dialog box to set properties on input 
columns. 





NOTE 


The Input Columns page is not displayed for Source components, which have outputs but no inputs. 





To learn more about the Script component, see Configuring the Script Component in the Script Component 


Editor. To learn about programming the Script component, see Extending the Data Flow with the Script 
Component. 


Options 
Input name 
Select from the list of available inputs. 


Available Input Columns 
Using the check boxes, specify the columns that the script transformation will use. 


Input Column 
Select from the list of available input columns for each row. Your selections are reflected in the check box 
selections in the Available Input Columnstable. 


Output Alias 
Type an alias for each output column. The default is the name of the input column; however, you can choose any 


unique, descriptive name. 


Usage Type 
Specify whether the Script Transformation will treat each column as ReadOnly or ReadWrite. 


Script Transformation Editor (Inputs and Outputs Page) 


Use the Inputs and Outputs page of the Script Transformation Editor dialog box to add, remove, and 
configure inputs and outputs for the Script Transformation. 


NOTE 


Source components have outputs and no inputs, while destination components have inputs but no outputs. 


Transformations have both inputs and outputs. 





To learn more about the Script component, see Configuring the Script Component in the Script Component 
Editor. To learn about programming the Script component, see Extending the Data Flow with the Script 
Component. 


Options 

Inputs and outputs 

Select an input or output on the left to view its properties in the table on the right. Properties available for 
editing vary according to the selection. Many of the properties displayed are read-only. For more information on 
the individual properties, see the following topics. 


Common Properties 
Transformation Custom Properties 


Add Output 
Add an additional output to the list. 


Add Column 
Select a folder in which to place the new output column, and then add the column by clicking Add Column. 


Remove Output 
Select an output, and then remove it by clicking Remove Output. 


Remove Column 
Select a column, and then remove it by clicking Remove Column. 


Script Transformation Editor (Script Page) 
Use the Script tab of the Script Transformation Editor dialog box to specify a script and related properties. 


To learn more about the Script component, see Configuring the Script Component in the Script Component 
Editor. To learn about programming the Script component, see Extending the Data Flow with the Script 
Component. 


Options 

Properties 

View and modify the properties of the Script transformation. Many of the properties displayed are read-only. 
You can modify the following properties: 


VALUE DESCRIPTION 
Description Describe the script transformation in terms of its purpose. 
LocalelD Specify the locale to provide region-specific information for 


ordering, and for date and time conversion. 


Name Type a descriptive name for the component. 


ValidateExternalMetadata Indicate whether the Script transformation validates column 
metadata against external data sources at design time. A 
value of false delays validation until the time of execution. 


ReadOnlyVariables Type a comma-separated list of variables for read-only 
access by the Script transformation. 


Note: Variable names are case-sensitive. 


ReadWriteVariables Type a comma-separated list of variables for read/write 
access by the Script transformation. 


Note: Variable names are case-sensitive. 


ScriptLanguage Select the script language to be used by the Script 
component. 


To set the default script language for Script components and 
Script tasks, use the Scripting language option on the 
General page of the Options dialog box. 


UserComponentTypeName Specifies the ScriptComponentHost class and the 
Microsoft.SqlServer.TxScript assembly that support the 
SQL Server infrastructure. 


Edit Script 
Use Microsoft Visual Studio Tools for Applications (VSTA) to create or modify a script. 


Related Content 


Integration Services Transformations 


Extending the Data Flow with the Script Component 
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The Slowly Changing Dimension transformation coordinates the updating and inserting of records in data 
warehouse dimension tables. For example, you can use this transformation to configure the transformation 
outputs that insert and update records in the DimProduct table of the AdventureWorksDW2012 database 
with data from the Production.Products table in the AdventureWorks OLTP database. 





IMPORTANT 


The Slowly Changing Dimension Wizard only supports connections to SQL Server. 











The Slowly Changing Dimension transformation provides the following functionality for managing slowly 
changing dimensions: 


e Matching incoming rows with rows in the lookup table to identify new and existing rows. 
e Identifying incoming rows that contain changes when changes are not permitted. 
e Identifying inferred member records that require updating. 


e Identifying incoming rows that contain historical changes that require insertion of new records and the 
updating of expired records. 


e Detecting incoming rows that contain changes that require the updating of existing records, including 
expired ones. 


The Slowly Changing Dimension transformation supports four types of changes: changing attribute, historical 
attribute, fixed attribute, and inferred member. 


e@ Changing attribute changes overwrite existing records. This kind of change is equivalent to a Type 1 
change. The Slowly Changing Dimension transformation directs these rows to an output named 
Changing Attributes Updates Output. 


e Historical attribute changes create new records instead of updating existing ones. The only change that is 
permitted in an existing record is an update to a column that indicates whether the record is current or 
expired. This kind of change is equivalent to a Type 2 change. The Slowly Changing Dimension 
transformation directs these rows to two outputs: Historical Attribute Inserts Output and New 
Output. 


e Fixed attribute changes indicate the column value must not change. The Slowly Changing Dimension 
transformation detects changes and can direct the rows with changes to an output named Fixed 
Attribute Output. 


e Inferred member indicates that the row is an inferred member record in the dimension table. An inferred 
member exists when a fact table references a dimension member that is not yet loaded. A minimal 
inferred-member record is created in anticipation of relevant dimension data, which is provided in a 
subsequent loading of the dimension data. The Slowly Changing Dimension transformation directs these 
rows to an output named Inferred Member Updates. When data for the inferred member is loaded, 
you can update the existing record rather than create a new one. 





NOTE 
The Slowly Changing Dimension transformation does not support Type 3 changes, which require changes to the 
dimension table. By identifying columns with the fixed attribute update type, you can capture the data values that are 


candidates for Type 3 changes. 





At run time, the Slowly Changing Dimension transformation first tries to match the incoming row to a record in 
the lookup table. If no match is found, the incoming row is a new record; therefore, the Slowly Changing 
Dimension transformation performs no additional work, and directs the row to New Output. 


If a match is found, the Slowly Changing Dimension transformation detects whether the row contains changes. If 
the row contains changes, the Slowly Changing Dimension transformation identifies the update type for each 
column and directs the row to the Changing Attributes Updates Output, Fixed Attribute Output, 
Historical Attributes Inserts Output, or Inferred Member Updates Output. If the row is unchanged, the 
Slowly Changing Dimension transformation directs the row to the Unchanged Output. 


Slowly Changing Dimension Transformation Outputs 


The Slowly Changing Dimension transformation has one input and up to six outputs. An output directs a row to 
the subset of the data flow that corresponds to the update and the insert requirements of the row. This 
transformation does not support an error output. 


The following table describes the transformation outputs and the requirements of their subsequent data flows. 
The requirements describe the data flow that the Slowly Changing Dimension Wizard creates. 





OUTPUT 


Changing Attributes Updates 
Output 


Fixed Attribute Output 


Historical Attributes Inserts 
Output 


Inferred Member Updates Output 


New Output 


DESCRIPTION 


The record in the lookup table is 
updated. This output is used for 
changing attribute rows. 


The values in rows that must not 
change do not match values in the 
lookup table. This output is used for 
fixed attribute rows. 


The lookup table contains at least one 
matching row. The row marked as 
"current" must now be marked as 
"expired". This output is used for 
historical attribute rows. 


Rows for inferred dimension members 
are inserted. This output is used for 
inferred member rows. 


The lookup table contains no matching 
rows. The row is added to the 
dimension table. This output is used 
for new rows and changes to historical 
attributes rows. 


DATA FLOW REQUIREMENTS 


An OLE DB Command transformation 
updates the record using an UPDATE 
statement. 


No default data flow is created. If the 
transformation is configured to 
continue after it encounters changes 
to fixed attribute columns, you should 
create a data flow that captures these 
rows. 


Derived Column transformations 
create columns for the expired row and 
the current row indicators. An OLE DB 
Command transformation updates the 
record that must now be marked as 
"expired". The row with the new 
column values is directed to the New 
Output, where the row is inserted and 
marked as "current". 


An OLE DB Command transformation 
updates the record using an SQL 
UPDATE statement. 


A Derived Column transformation sets 
the current row indicator, and an OLE 
DB destination inserts the row. 


OUTPUT DESCRIPTION DATA FLOW REQUIREMENTS 


Unchanged Output The values in the lookup table match No default data flow is created because 
the row values. This output is used for the Slowly Changing Dimension 
unchanged rows. transformation performs no work. If 


you want to capture these rows, you 
should create a data flow for this 
output. 


Business Keys 
The Slowly Changing Dimension transformation requires at least one business key column. 


The Slowly Changing Dimension transformation does not support null business keys. If the data include rows in 
which the business key column is null, those rows should be removed from the data flow. You can use the 
Conditional Split transformation to filter rows whose business key columns contain null values. For more 
information, see Conditional Split Transformation. 


Optimizing the Performance of the Slowly Changing Dimension 
Transformation 


For suggestions on how to improve the performance of the Slowly Changing Dimension Transformation, see 
Data Flow Performance Features. 


Troubleshooting the Slowly Changing Dimension Transformation 


You can log the calls that the Slowly Changing Dimension transformation makes to external data providers. You 
can use this logging capability to troubleshoot the connections, commands, and queries to external data sources 
that the Slowly Changing Dimension transformation performs. To log the calls that the Slowly Changing 
Dimension transformation makes to external data providers, enable package logging and select the Diagnostic 
event at the package level. For more information, see Troubleshooting Tools for Package Execution. 


Configuring the Slowly Changing Dimension Transformation 


You can set properties through SSIS Designer or programmatically. 


For more information about the properties that you can set in the Advanced Editor dialog box or 
programmatically, click one of the following topics: 


e Common Properties 
e Transformation Custom Properties 


For more information about how to set properties, see Set the Properties of a Data Flow Component. 


Configuring the Slowly Changing Dimension Transformation Outputs 


Coordinating the update and insertion of records in dimension tables can be a complex task, especially if both 
Type 1 and Type 2 changes are used. SSIS Designer provides two ways to configure support for slowly changing 
dimensions: 


e The Advanced Editor dialog box, in which you to select a connection, set common and custom 
component properties, choose input columns, and set column properties on the six outputs. To complete 
the task of configuring support for a slowly changing dimension, you must manually create the data flow 
for the outputs that the Slowly Changing Dimension transformation uses. For more information, see Data 


Flow. 


e The Load Dimension Wizard, which guides you though the steps to configure the Slowly Changing 
Dimension transformation and build the data flow for transformation outputs. To change the 
configuration for slowly change dimensions, rerun the Load Dimension Wizard. For more information, 
see Configure Outputs Using the Slowly Changing Dimension Wizard. 


Related Tasks 


Set the Properties of a Data Flow Component 


Related Content 


e Handling Slowly Changing Dimensions in SSIS 
e Optimizing the Slowly Changing Dimension Wizard 


Configure Outputs Using the Slowly Changing 
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The Slowly Changing Dimension Wizard functions as the editor for the Slowly Changing Dimension 
transformation. Building and configuring the data flow for slowly changing dimension data can be a complex 
task. The Slowly Changing Dimension Wizard offers the simplest method of building the data flow for the 
Slowly Changing Dimension transformation outputs by guiding you through the steps of mapping columns, 
selecting business key columns, setting column change attributes, and configuring support for inferred 
dimension members. 


You must choose at least one business key column in the dimension table and map it to an input column. The 
value of the business key links a record in the source to a record in the dimension table. The transformation uses 
this mapping to locate the record in the dimension table and to determine whether a record is new or changing. 
The business key is typically the primary key in the source, but it can be an alternate key as long as it uniquely 
identifies a record and its value does not change. The business key can also be a composite key, consisting of 
multiple columns. The primary key in the dimension table is usually a surrogate key, which means a numeric 
value generated automatically by an identity column or by a custom solution such as a script. 


Before you can run the Slowly Changing Dimension Wizard, you must add a source and a Slowly Changing 
Dimension transformation to the data flow, and then connect the output from the source to the input of the 
Slowly Changing Dimension transformation. Optionally, the data flow can include other transformations 
between the data source and the Slowly Changing Dimension transformation. 


To open the Slowly Changing Dimension Wizard in SSIS Designer, double-click the Slowly Changing Dimension 
transformation. 


Creating Slowly Changing Dimension Outputs 


To create Slowly Changing Dimension transformation outputs 


1. Choose the connection manager to access the data source that contains the dimension table that you 
want to update. 


You can select from a list of connection managers that the package includes. 
2. Choose the dimension table or view you want to update. 

After you select the connection manager, you can select the table or view from the data source. 
3. Set key attributes on columns and map input columns to columns in the dimension table. 


You must choose at least one business key column in the dimension table and map it to an input column. 
Other input columns can be mapped to columns in the dimension table as non-key mappings. 


4. Choose the change type for each column. 
e Changing attribute overwrites existing values in records. 
e Historical attribute creates new records instead of updating existing records. 


e Fixed attribute indicates that the column value must not change. 


5. Set fixed and changing attribute options. 


If you configure columns to use the Fixed attribute change type, you can specify whether the Slowly 
Changing Dimension transformation fails when changes are detected in these columns. If you configure 
columns to use the Changing attribute change type, you can specify whether all matching records, 
including outdated records, are updated. 


6. Set historical attribute options. 


If you configure columns to use the Historical attribute change type, you must choose how to 
distinguish between current and expired records. You can use a current row indicator column or two date 
columns to identify current and expired rows. If you use the current row indicator column, you can set it 
to Current, True when current and Expired, or False when expired. You can also enter custom values. If 
you use two date columns, a start date and an end date, you can specify the date to use when setting the 
date column values by typing a date or by selecting a system variable and then using its value. 


7. Specify support for inferred members and choose the columns that the inferred member record contains. 


When loading measures into a fact table, you can create minimal records for inferred members that do 
not yet exist. Later, when meaningful data is available, the dimension records can be updated. The 
following types of minimal records can be created: 


e Arecord in which all columns with change types are null. 
e Arecord in which a Boolean column indicates the record is an inferred member. 


8. Review the configurations that the Slowly Changing Dimension Wizard builds. Depending on which 
change types are supported, different sets of data flow components are added to the package. 


The following diagram shows an example of a data flow that supports fixed attribute, changing attribute, 
and historical attribute changes, inferred members, and changes to matching records. 
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Updating Slowly Changing Dimension Outputs 


The simplest way to update the configuration of the Slowly Changing Dimension transformation outputs is to 
rerun the Slowly Changing Dimension Wizard and modify properties from the wizard pages. You can also 


update the Slowly Changing Dimension transformation using the Advanced Editor dialog box or 
programmatically. 


See Also 


Slowly Changing Dimension Transformation 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Use the Slowly Changing Dimension Wizard to configure the loading of data into various types of slowly 
changing dimensions. This section provides F1 Help for the pages of the Slowly Changing Dimension 
Wizard. The following table describes the topics in this section. 


To learn more about this wizard, see Slowly Changing Dimension Transformation. 


Welcome to the Slowly Changing Dimension Wizard 
Introduces the Slowly Changing Dimension Wizard. 


Select a Dimension Table and Keys (Slowly Changing Dimension Wizard) 
Select a slowly changing dimension table and specify its key columns. 


Slowly Changing Dimension Columns (Slowly Changing Dimension Wizard) 
Select the type of change for selected slowly changing dimension columns. 


Fixed and Changing Attribute Options (Slowly Changing Dimension Wizard 
Specify options for fixed and changing attribute dimension columns. 


Historical Attribute Options (Slowly Changing Dimension Wizard) 
Specify options for historical attribute dimension columns. 


Inferred Dimension Members (Slowly Changing Dimension Wizard) 
Specify options for inferred dimension members. 


Finish the Slowly Changing Dimension Wizard 
Displays the configuration options selected by the user. 


See Also 


Slowly Changing Dimension Transformation 
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Applies to: Q@sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Use the Slowly Changing Dimension Wizard to configure the loading of data into various types of slowly 
changing dimensions. 


To learn more about this wizard, see Slowly Changing Dimension Transformation. 


Options 
Don't show this page again 


Skip the welcome page the next time you open the wizard. 


See Also 


Configure Outputs Using the Slowly Changing Dimension Wizard 
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Applies to: Q sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Use the Select a Dimension Table and Keys page to select a dimension table to load. Map columns from the 
data flow to the columns that will be loaded. 


To learn more about this wizard, see Slowly Changing Dimension Transformation. 


Options 


Connection manager 
Select an existing OLE DB connection manager from the list, or click New to create an OLE DB connection 
manager. 





NOTE 


The Slowly Changing Dimension Wizard only supports OLE DB connection managers, and only supports connections to 
SQL Server. 











New 
Use the Configure OLE DB Connection Manager dialog box to select an existing connection manager, or 
click New to create a new OLE DB connection. 


Table or View 
Select a table or view from the list. 


Input Columns 
Select from the list of input columns for which you may specify mapping. 


Dimension Columns 


View all available dimension columns. 
Key Type 


Select one of the dimension columns to be the business key. You must have one business key. 


See Also 


Configure Outputs Using the Slowly Changing Dimension Wizard 
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Applies to: Q sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Use the Slowly Changing Dimensions Columns dialog box to select a change type for each slowly changing 
dimension column. 


To learn more about this wizard, see Slowly Changing Dimension Transformation. 


Options 
Dimension Columns 


Select a dimension column from the list. 


Change Type 

Select a Fixed Attribute, or select one of the two types of changing attributes. Use Fixed Attribute when the 
value in a column should not change; Integration Services then treats changes as errors. Use Changing 
Attribute to overwrite existing values with changed values. Use Historical Attribute to save changed values 
in new records, while marking previous records as outdated. 


Remove 


Select a dimension column, and remove it from the list of mapped columns by clicking Remove. 


See Also 


Configure Outputs Using the Slowly Changing Dimension Wizard 
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Changing Dimension Wizard 
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Applies to: Q sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Use the Fixed and Changing Attribute Options dialog box to specify how to respond to changes in fixed and 
changing attributes. 


To learn more about this wizard, see Slowly Changing Dimension Transformation. 


Options 


Fixed attributes 
For fixed attributes, indicate whether the task should fail if a change is detected in a fixed attribute. 


Changing attributes 

For changing attributes, indicate whether the task should change outdated or expired records, in addition to 
current records, when a change is detected in a changing attribute. An expired record is a record that has been 
replaced with a newer record by a change in a historical attribute (a Type 2 change). Selecting this option may 
impose additional processing requirements on a multidimensional object constructed on the relational data 
warehouse. 


See Also 


Configure Outputs Using the Slowly Changing Dimension Wizard 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Use the Historical Attributes Options dialog box to show historical attributes by start and end dates, or to 
record historical attributes in a column specially created for this purpose. 


To learn more about this wizard, see Slowly Changing Dimension Transformation. 


Options 


Use a single column to show current and expired records 
If you choose to use a single column to record the status of historical attributes, the following options are 


available: 
OPTION DESCRIPTION 
Column to indicate current record Select a column in which to indicate the current record. 
Value when current Use either True or Current to show whether the record is 
current. 
Expiration value Use either False or Expired to show whether the record is a 


historical value. 


Use start and end dates to identify current and expired records 
The dimension table for this option must include a date column. If you choose to show historical attributes by 
start and end dates, the following options are available: 


OPTION DESCRIPTION 
Start date column Select the column in the dimension table to contain the start 
date. 
End date column Select the column in the dimension table to contain the end 
date. 
Variable to set date values Select a date variable from the list. 
See Also 


Configure Outputs Using the Slowly Changing Dimension Wizard 
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Applies to: Q sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Use the Inferred Dimension Members dialog box to specify options for using inferred members. Inferred 
members exist when a fact table references dimension members that are not yet loaded. When data for the 
inferred member is loaded, you can update the existing record rather than create a new one. 


To learn more about this wizard, see Slowly Changing Dimension Transformation. 


Options 


Enable inferred member support 
If you choose to enable inferred members, you must select one of the two options that follow. 


All columns with a change type are null 
Specify whether to enter null values in all columns with a change type in the new inferred member record. 


Use a Boolean column to indicate whether the current record is an inferred member 
Specify whether to use an existing Boolean column to indicate whether the current record is an inferred 
member. 


Inferred member indicator 


If you have chosen to use a Boolean column to indicate inferred members as described above, select the column 
from the list. 


See Also 


Configure Outputs Using the Slowly Changing Dimension Wizard 
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Applies to: Q@ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Use the Finish the Slowly Changing Dimension Wizard dialog box to verify your choices before the wizard 
builds support for slowly changing dimensions. 


To learn more about this wizard, see Slowly Changing Dimension Transformation. 


Options 


The following outputs will be configured 
Confirm that the list of outputs is appropriate for your purposes. 


See Also 


Configure Outputs Using the Slowly Changing Dimension Wizard 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


The Sort transformation sorts input data in ascending or descending order and copies the sorted data to the 
transformation output. You can apply multiple sorts to an input; each sort is identified by a numeral that 
determines the sort order. The column with the lowest number is sorted first, the sort column with the second 
lowest number is sorted next, and so on. For example, if a column named CountryRegion has a sort order of 1 
and a column named City has a sort order of 2, the output is sorted by country/region and then by city. A 
positive number denotes that the sort is ascending, and a negative number denotes that the sort is descending. 
Columns that are not sorted have a sort order of 0. Columns that are not selected for sorting are automatically 
copied to the transformation output together with the sorted columns. 


The Sort transformation includes a set of comparison options to define how the transformation handles the 


string data in a column. For more information, see Comparing String Data. 


NOTE 


The Sort transformation does not sort GUIDs in the same order as the ORDER BY clause does in Transact-SQL. While the 
Sort transformation sorts GUIDs that start with 0-9 before GUIDs that start with A-F, the ORDER BY clause, as 
implemented in the SQL Server Database Engine, sorts them differently. For more information, see ORDER BY Clause 
(Transact-SQL). 








The Sort transformation can also remove duplicate rows as part of its sort. Duplicate rows are rows with the 
same sort key values. The sort key value is generated based on the string comparison options being used, which 
means that different literal strings may have the same sort key values. The transformation identifies rows in the 
input columns that have different values but the same sort key as duplicates. 


The Sort transformation includes the MaximumThreads custom property that can be updated by a property 
expression when the package is loaded. For more information, see Integration Services (SSIS) Expressions, Use 
Property Expressions in Packages, and Transformation Custom Properties. 


This transformation has one input and one output. It does not support error outputs. 


Configuration of the Sort Transformation 
You can set properties through the SSIS Designer or programmatically. 


The Advanced Editor dialog box reflects the properties that can be set programmatically. For more 
information about the properties that you can set in the Advanced Editor dialog box or programmatically, click 
one of the following topics: 


@ Common Properties 


e Transformation Custom Properties 


Related Tasks 


For more information about how to set properties of the component, see Set the Properties of a Data Flow 
Component. 


Sort Transformation Editor 


Use the Sort Transformation Editor dialog box to select the columns to sort, set the sort order, and specify 
whether duplicates are removed. 


Options 
Available Input Columns 
Using the check boxes, specify the columns to sort. 


Name 
View the name of each available input column. 


Passthrough 
Indicate whether to include the column in the sorted output. 


Input Column 
Select from the list of available input columns for each row. Your selections are reflected in the check box 
selections in the Available Input Columns table. 


Output Alias 
Type an alias for each output column. The default is the name of the input column; however, you can choose any 


unique, descriptive name. 


Sort Type 
Indicate whether to sort in ascending or descending order. 


Sort Order 
Indicate the order in which to sort columns. This must be set manually for each column. 


Comparison Flags 
For information about the string comparison options, see Comparing String Data. 


Remove rows with duplicate sort values 
Indicate whether the transformation copies duplicate rows to the transformation output, or creates a single 
entry for all duplicates, based on the specified string comparison options. 


See Also 


Data Flow 
Integration Services Transformations 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


The Term Extraction transformation extracts terms from text in a transformation input column, and then writes 
the terms to a transformation output column. The transformation works only with English text and it uses its 
own English dictionary and linguistic information about English. 


You can use the Term Extraction transformation to discover the content of a data set. For example, text that 
contains e-mail messages may provide useful feedback about products, so that you could use the Term 
Extraction transformation to extract the topics of discussion in the messages, as a way of analyzing the feedback. 


Extracted Terms and Data Types 


The Term Extraction transformation can extract nouns only, noun phrases only, or both nouns and noun phases. 
A noun is a single noun; a noun phrases is at least two words, of which one is a noun and the other is a noun or 
an adjective. For example, if the transformation uses the nouns-only option, it extracts terms like bicycle and 
landscape if the transformation uses the noun phrase option, it extracts terms like new blue bicycle, bicycle 
helmet, and boxed bicycles. 


Articles and pronouns are not extracted. For example, the Term Extraction transformation extracts the term 
bicycle from the text the bicycle, my bicycle, and that bicycle. 


The Term Extraction transformation generates a score for each term that it extracts. The score can be either a 
TFIDF value or the raw frequency, meaning the number of times the normalized term appears in the input. In 
either case, the score is represented by a real number that is greater than 0. For example, the TFIDF score might 
have the value 0.5, and the frequency would be a value like 1.0 or 2.0. 


The output of the Term Extraction transformation includes only two columns. One column contains the extracted 
terms and the other column contains the score. The default names of the columns are Term and Score. Because 
the text column in the input may contain multiple terms, the output of the Term Extraction transformation 
typically has more rows than the input. 


If the extracted terms are written to a table, they can be used by other lookup transformation such as the Term 
Lookup, Fuzzy Lookup, and Lookup transformations. 


The Term Extraction transformation can work only with text in a column that has either the DT_WSTR or the 
DT_NTEXT data type. If a column contains text but does not have one of these data types, the Data Conversion 
transformation can be used to add a column with the DT_WSTR or DT_NTEXT data type to the data flow and 
copy the column values to the new column. The output from the Data Conversion transformation can then be 
used as the input to the Term Extraction transformation. For more information, see Data Conversion 
Transformation. 


Exclusion Terms 


Optionally, the Term Extraction transformation can reference a column in a table that contains exclusion terms, 
meaning terms that the transformation should skip when it extracts terms from a data set. This is useful when a 
set of terms has already been identified as inconsequential in a particular business and industry, typically 
because the term occurs with such high frequency that it becomes a noise word. For example, when extracting 
terms from a data set that contains customer support information about a particular brand of cars, the brand 
name itself might be excluded because it is mentioned too frequently to have significance. Therefore, the values 


in the exclusion list must be customized to the data set you are working with. 


When you add a term to the exclusion list, all the terms-words or noun phrases-that contain the term are also 
excluded. For example, if the exclusion list includes the single word aata, then all the terms that contain this 
word, such as data, data mining, data integrity, and data validation will also be excluded. If you want to exclude 
only compounds that contain the word data, you must explicitly add those compound terms to the exclusion list. 
For example, if you want to extract incidences of data, but exclude data validation, you would add data validation 


to the exclusion list, and make sure that data is removed from the exclusion list. 


The reference table must be a table in a SQL Server or an Access database. The Term Extraction transformation 
uses a separate OLE DB connection to connect to the reference table. For more information, see OLE DB 
Connection Manager. 


The Term Extraction transformation works in a fully precached mode. At run time, the Term Extraction 
transformation reads the exclusion terms from the reference table and stores them in its private memory before 


it processes any transformation input rows. 


Extraction of Terms from Text 
To extract terms from text, the Term Extraction transformation performs the following tasks. 


Identification of Words 


First, the Term Extraction transformation identifies words by performing the following tasks: 


e Separating text into words by using spaces, line breaks, and other word terminators in the English 
language. For example, punctuation marks such as ?and - are word-breaking characters. 


e Preserving words that are connected by hyphens or underscores. For example, the words copy-protected 
and read-only remain one word. 


e Keeping intact acronyms that include periods. For example, the A.8.C Company would be tokenized as 
ABC and Company. 


e Splitting words on special characters. For example, the word date/time is extracted as date and time 
(bicycle) as bicycle, and C# is treated as C. Special characters are discarded and cannot be lexicalized. 


e@ Recognizing when special characters such as the apostrophe should not split words. For example, the 
word bicycle's is not split into two words, and yields the single term bicycle (noun). 


e Splitting time expressions, monetary expressions, e-mail addresses, and postal addresses. For example, 
the date January 31, 2004 is separated into the three tokens January, 37, and 2004. 


Tagged Words 


Second, the Term Extraction transformation tags words as one of the following parts of speech: 
e Anoun in the singular form. For example, bicycle and potato. 


e Anoun in the plural form. For example, bicycles and potatoes. All plural nouns that are not lemmatized 
are subject to stemming. 


e A proper noun in the singular form. For example, Apri/ and Peter. 


e A proper noun in the plural form. For example Apri/s and Peters. For a proper noun to be subject to 
stemming, it must be a part of the internal lexicon, which is limited to standard English words. 


e An adjective. For example, blue. 
e Acomparative adjective that compares two things. For example, A/gher and taller. 


e Asuperlative adjective that identifies a thing that has a quality above or below the level of at least two 


others. For example, highest and tallest. 


e Anumber. For example, 62 and 2004. 


Words that are not one of these parts of speech are discarded. For example, verbs and pronouns are discarded. 





NOTE 


The tagging of parts of speech is based on a statistical model and the tagging may not be completely accurate. 





If the Term Extraction transformation is configured to extract only nouns, only the words that are tagged as 
singular or plural forms of nouns and proper nouns are extracted. 


If the Term Extraction transformation is configured to extract only noun phrases, words that are tagged as nouns, 
proper nouns, adjectives, and numbers may be combined to make a noun phrase, but the phrase must include 
at least one word that is tagged as a singular or plural form of a noun or a proper noun. For example, the noun 
phrase highest mountain combines a word tagged as a superlative adjective (highest) and a word tagged as 
noun (mountain). 


If the Term Extraction is configured to extract both nouns and noun phrases, both the rules for nouns and the 
rules for noun phrases apply. For example, the transformation extracts bicycle and beautiful blue bicycle from 


the text many beautiful blue bicycles. 





NOTE 


The extracted terms remain subject to the maximum term length and frequency threshold that the transformation uses. 





Stemmed Words 


The Term Extraction transformation also stems nouns to extract only the singular form of a noun. For example, 
the transformation extracts man from men, mouse from mice, and bicycle from bicycles. The transformation 


uses its dictionary to stem nouns. Gerunds are treated as nouns if they are in the dictionary. 


The Term Extraction transformation stems words to their dictionary form as shown in these examples by using 


the dictionary internal to the Term Extraction transformation. 

e Removing s from nouns. For example, bicycles becomes bicycle. 

e Removing es from nouns. For example, stories becomes story. 

e Retrieving the singular form for irregular nouns from the dictionary. For example, geese becomes goose. 


Normalized Words 


The Term Extraction transformation normalizes terms that are capitalized only because of their position ina 
sentence, and uses their non-capitalized form instead. For example, in the phrases Dogs chase cats and 
Mountain paths are steep, Dogs and Mountain would be normalized to dog and mountain. 


The Term Extraction transformation normalizes words so that the capitalized and noncapitalized versions of 
words are not treated as different terms. For example, in the text You see many bicycles in Seattle and Bicycles 
are blue, bicycles and Bicycles are recognized as the same term and the transformation keeps only bicycle. 
Proper nouns and words that are not listed in the internal dictionary are not normalized. 


Case-Sensitive Normalization 


The Term Extraction transformation can be configured to consider lowercase and uppercase words as either 
distinct terms, or as different variants of the same term. 


e If the transformation is configured to recognize differences in case, terms like Method and method are 


extracted as two different terms. Capitalized words that are not the first word in a sentence are never 
normalized, and are tagged as proper nouns. 


e If the transformation is configured to be case-insensitive, terms like Method and method are recognized 
as variants of a single term. The list of extracted terms might include either Method or method, 
depending on which word occurs first in the input data set. If Methodis capitalized only because it is the 
first word in a sentence, it is extracted in normalized form. 


Sentence and Word Boundaries 


The Term Extraction transformation separates text into sentences using the following characters as sentence 
boundaries: 


e ASCII line-break characters OxOd (carriage return) and Ox0a (line feed). To use this character as a sentence 
boundary, there must be two or more line-break characters in a row. 


e Hyphens (-). To use this character as a sentence boundary, neither the character to the left nor to the right 
of the hyphen can be a letter. 


e Underscore (_). To use this character as a sentence boundary, neither the character to the left nor to the 
right of the hyphen can be a letter. 


e All Unicode characters that are less than or equal to 0x19, or greater than or equal to 0x7b. 


e Combinations of numbers, punctuation marks, and alphabetical characters. For example, A23B#99 
returns the term A238. 


# The characters, 4, @, 63,8," anne ti ey LG ee end 





NOTE 


Acronyms that include one or more periods (.) are not separated into multiple sentences. 





The Term Extraction transformation then separates the sentence into words using the following word 
boundaries: 


e Space 
e Tab 
e ASCII Ox0d (carriage return) 


e ASCII 0x0a (line feed) 





NOTE 
If an apostrophe is in a word that is a contraction, such as we’re or it's, the word is broken at the apostrophe; 
otherwise, the letters following the apostrophe are trimmed. For example, we’re is split into we and ‘re and 


bicycle’ is trimmed to bicycle. 








Configuration of the Term Extraction Transformation 


The Text Extraction transformation uses internal algorithms and statistical models to generate its results. You 
may have to run the Term Extraction transformation several times and examine the results to configure the 
transformation to generate the type of results that works for your text mining solution. 


The Term Extraction transformation has one regular input, one output, and one error output. 


You can set properties through SSIS Designer or programmatically. 


For more information about the properties that you can set in the Advanced Editor dialog box or 
programmatically, click one of the following topics: 


@ Common Properties 
e Transformation Custom Properties 


For more information about how to set properties, see Set the Properties of a Data Flow Component. 


Term Extraction Transformation Editor (Term Extraction Tab) 


Use the Term Extraction tab of the Term Extraction Transformation Editor dialog box to specify a text 


column that contains text to be extracted. 
Options 
Available Input Columns 


Using the check boxes, select a single text column to use for term extraction. 


Term 
Provide a name for the output column that will contain the extracted terms. 


Score 
Provide a name for the output column that will contain the score for each extracted term. 


Configure Error Output 
Use the Configure Error Output dialog box to specify error handling for rows that cause errors. 


Term Extraction Transformation Editor (Exclusion Tab) 


Use the Exclusion tab of the Term Extraction Transformation Editor dialog box to set up a connection to an 
exclusion table and specify the columns that contain exclusion terms. 


Options 
Use exclusion terms 


Indicate whether to exclude specific terms during term extraction by specifying a column that contains exclusion 


terms. You must specify the following source properties if you choose to exclude terms. 


OLE DB connection manager 
Select an existing OLE DB connection manager, or create a new connection by clicking New. 


New 
Create a new connection to a database by using the Configure OLE DB Connection Manager dialog box. 


Table or view 


Select the table or view that contains the exclusion terms. 


Column 
Select the column in the table or view that contains the exclusion terms. 


Configure Error Output 
Use the Configure Error Output dialog box to specify error handling for rows that cause errors. 


Term Extraction Transformation Editor (Advanced Tab) 


Use the Advanced tab of the Term Extraction Transformation Editor dialog box to specify properties for the 
extraction such as frequency, length, and whether to extract words or phrases. 


Options 
Noun 
Specify that the transformation extracts individual nouns only. 


Noun phrase 
Specify that the transformation extracts noun phrases only. 


Noun and noun phrase 
Specify that the transformation extracts both nouns and noun phrases. 


Frequency 
Specify that the score is the frequency of the term. 


TFIDF 

Specify that the score is the TFIDF value of the term. The TFIDF score is the product of Term Frequency and 
Inverse Document Frequency, defined as: TFIDF of a Term T = (frequency of T) * log( (#rows in Input) / (#rows 
having T) ) 


Frequency threshold 
Specify the number of times a word or phrase must occur before extracting it. The default value is 2. 


Maximum length of term 
Specify the maximum length of a phrase in words. This option affects noun phrases only. The default value is 12. 


Use case-sensitive term extraction 


Specify whether to make the extraction case-sensitive. The default is False. 


Configure Error Output 
Use the Configure Error Output dialog box to specify error handling for rows that cause errors. 


See Also 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


The Term Lookup transformation matches terms extracted from text in a transformation input column with 
terms in a reference table. It then counts the number of times a term in the lookup table occurs in the input data 
set, and writes the count together with the term from the reference table to columns in the transformation 
output. This transformation is useful for creating a custom word list based on the input text, complete with word 
frequency statistics. 


Before the Term Lookup transformation performs a lookup, it extracts words from the text in an input column 
using the same method as the Term Extraction transformation: 


e Text is broken into sentences. 
e Sentences are broken into words. 
e Words are normalized. 


To further customize which terms to match, the Term Lookup transformation can be configured to perform a 
case-sensitive match. 


Matches 


The Term Lookup performs a lookup and returns a value using the following rules: 


e If the transformation is configured to perform case-sensitive matches, matches that fail a case-sensitive 
comparison are discarded. For example, studentand STUDENT are treated as separate words. 





NOTE 


A non-capitalized word can be matched with a word that is capitalized at the beginning of a sentence. For 
example, the match between student and Student succeeds when Student is the first word in a sentence. 








e Ifa plural form of the noun or noun phrase exists in the reference table, the lookup matches only the 
plural form of the noun or noun phrase. For example, all instances of students would be counted 
separately from the instances of student. 


e If only the singular form of the word is found in the reference table, both the singular and the plural 
forms of the word or phrase are matched to the singular form. For example, if the lookup table contains 
student, and the transformation finds the words student and students, both words would be counted as a 
match for the lookup term student 


e lf the text in the input column is a lemmatized noun phrase, only the last word in the noun phrase is 
affected by normalization. For example, the lemmatized version of doctors appointments is doctors 
appointment. 


When a lookup item contains terms that overlap in the reference set-that is, a sub-term is found in more than 
one reference record-the Term Lookup transformation returns only one lookup result. The following example 
shows the result when a lookup item contains an overlapping sub-term. The overlapping sub-term in this case is 
Windows, which is found within two reference terms. However, the transformation does not return two results, 
but returns only a single reference term, Windows. The second reference term, Windows 7 Professional, is not 


returned. 


ITEM VALUE 

Input term Windows 7 Professional 

Reference terms Windows, Windows 7 Professional 
Output Windows 


The Term Lookup transformation can match nouns and noun phrases that contain special characters, and the 
data in the reference table may include these characters. The special characters are as follows: %, @, &, $, #, *,:,;, 


age ee Se ea LAG bt and 


Data Types 


The Term Lookup transformation can only use a column that has either the DT_WSTR or the DT_NTEXT data type. 
If a column contains text, but does not have one of these data types, the Data Conversion transformation can 
add a column with the DT_WSTR or DT_NTEXT data type to the data flow and copy the column values to the new 
column. The output from the Data Conversion transformation can then be used as the input to the Term Lookup 


transformation. For more information, see Data Conversion Transformation. 


Configuration the Term Lookup Transformation 


The Term Lookup transformation input columns includes the InputColumnType property, which indicates the use 
of the column. InputColumnType can contain the following values: 


e The value 0 indicates the column is passed through to the output only and is not used in the lookup. 
e The value 1 indicates the column is used in the lookup only. 
e@ The value 2 indicates the column is passed through to the output, and is also used in the lookup. 


Transformation output columns whose InputColumntType property is set to 0 or 2 include the CustomLineagelD 
property for a column, which contains the lineage identifier assigned to the column by an upstream data flow 


component. 


The Term Lookup transformation adds two columns to the transformation output, named by default Term and 
Frequency. Term contains a term from the lookup table and Frequency contains the number of times the 
term in the reference table occurs in the input data set. These columns do not include the CustomLineagelD 


property. 


The lookup table must be a table in a SQL Server or an Access database. If the output of the Term Extraction 
transformation is saved to a table, this table can be used as the reference table, but other tables can also be 
used. Text in flat files, Excel workbooks or other sources must be imported to a SQL Server database or an 
Access database before you can use the Term Lookup transformation. 


The Term Lookup transformation uses a separate OLE DB connection to connect to the reference table. For more 
information, see OLE DB Connection Manager. 


The Term Lookup transformation works in a fully precached mode. At run time, the Term Lookup transformation 
reads the terms from the reference table and stores them in its private memory before it processes any 


transformation input rows. 


Because the terms in an input column row may repeat, the output of the Term Lookup transformation typically 


has more rows than the transformation input. 


The transformation has one input and one output. It does not support error outputs. 
You can set properties through SSIS Designer or programmatically. 


For more information about the properties that you can set in the Advanced Editor dialog box or 
programmatically, click one of the following topics: 


e Common Properties 
e Transformation Custom Properties 


For more information about how to set properties, see Set the Properties of a Data Flow Component. 


Term Lookup Transformation Editor (Term Lookup Tab) 


Use the Term Lookup tab of the Term Lookup Transformation Editor dialog box to map an input column to 


a lookup column in a reference table and to provide an alias for each output column. 


Options 

Available Input Columns 

Using the check boxes, select input columns to pass through to the output unchanged. Drag an input column to 
the Available Reference Columns list to map it to a lookup column in the reference table. The input and 
lookup columns must have matching, supported data types, either DT_NTEXT or DT_WSTR. Select a mapping 
line and right-click to edit the mappings in the Create Relationships dialog box. 


Available Reference Columns 
View the available columns in the reference table. Choose the column that contains the list of terms to match. 


Pass-Through Column 
Select from the list of available input columns. Your selections are reflected in the check box selections in the 
Available Input Columns table. 


Output Column Alias 
Type an alias for each output column. The default is the name of the column; however, you can choose any 


unique, descriptive name. 


Configure Error Output 
Use the Configure Error Output dialog box to specify error handling options for rows that cause errors. 


Term Lookup Transformation Editor (Reference Table Tab) 


Use the Reference Table tab of the Term Lookup Transformation Editor dialog box to specify the 
connection to the reference (lookup) table. 


Options 
OLE DB connection manager 


Select an existing connection manager from the list, or create a new connection by clicking New. 


New 
Create a new connection by using the Configure OLE DB Connection Manager dialog box. 


Reference table name 
Select a lookup table or view from the database by selecting an item from the list. The table or view should 


contain a column with an existing list of terms that the text in the source column can be compared to. 


Configure Error Output 
Use the Configure Error Output dialog box to specify error handling options for rows that cause errors. 


Term Lookup Transformation Editor (Advanced Tab) 


Use the Advanced tab of the Term Lookup Transformation Editor dialog box to specify whether lookup 
should be case-sensitive. 


Options 
Use case-sensitive term lookup 
Indicate whether the lookup is case-sensitive. The default is False. 


Configure Error Output 
Use the Configure Error Output dialog box to specify error handling options for rows that cause errors. 


See Also 


Integration Services Error and Message Reference 
Term Extraction Transformation 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


The Union All transformation combines multiple inputs into one output. For example, the outputs from five 
different Flat File sources can be inputs to the Union All transformation and combined into one output. 


Inputs and Outputs 


The transformation inputs are added to the transformation output one after the other; no reordering of rows 
occurs. If the package requires a sorted output, you should use the Merge transformation instead of the Union 
All transformation. 


The first input that you connect to the Union All transformation is the input from which the transformation 
creates the transformation output. The columns in the inputs you subsequently connect to the transformation 
are mapped to the columns in the transformation output. 


To merge inputs, you map columns in the inputs to columns in the output. A column from at least one input 
must be mapped to each output column. The mapping between two columns requires that the metadata of the 
columns match. For example, the mapped columns must have the same data type. 


If the mapped columns contain string data and the output column is shorter in length than the input column, the 
output column is automatically increased in length to contain the input column. Input columns that are not 
mapped to output columns are set to null values in the output columns. 


This transformation has multiple inputs and one output. It does not support an error output. 


Configuration of the Union All Transformation 

You can set properties through SSIS Designer or programmatically. 

For more information about the properties that you can set programmatically, see Common Properties. 
For more information about how to set properties, click one of the following topics: 


e Set the Properties of a Data Flow Component 


Union All Transformation Editor 


Use the Union All Transformation Editor dialog box to merge several input rowsets into a single output 
rowset. By including the Union All transformation in a data flow, you can merge data from multiple data flows, 
create complex datasets by nesting Union All transformations, and re-merge rows after you correct errors in the 
data. 


Options 
Output Column Name 


Type an alias for each column. The default is the name of the input column from the first (reference) input; 
however, you can choose any unique, descriptive name. 


Union All Input 1 
Select from the list of available input columns in the first (reference) input. The metadata of mapped columns 
must match. 


Union All Input n 
Select from the list of available input columns in the second and additional inputs. The metadata of mapped 
columns must match. 


Related Tasks 


Merge Data by Using the Union All Transformation 


Merge Data by Using the Union All Transformation 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


To add and configure a Union All transformation, the package must already include at least one Data Flow task 
and two data sources. 


The Union All transformation combines multiple inputs. The first input that is connected to the transformation is 
the reference input, and the inputs connected subsequently are the secondary inputs. The output includes the 
columns in the reference input. 


To combine inputs in a data flow 


1. In SQL Server Data Tools (SSDT), double-click the package in Solution Explorer to open the package in 
SSIS Designer, and then click the Data Flow tab. 


2. From the Toolbox, drag the Union All transformation to the design surface of the Data Flow tab. 


3. Connect the Union All transformation to the data flow by dragging a connector from the data source or a 


previous transformation to the Union All transformation. 
4. Double-click the Union All transformation. 


5. Inthe Union All Transformation Editor, map a column from an input to a column in the Output 
Column Name list by clicking a row and then selecting a column in the input list. Select <ignore> in 


the input list to skip mapping the column. 





NOTE 


The mapping between two columns requires that the metadata of the columns match. 








NOTE 


Columns in a secondary input that are not mapped to reference columns are set to null values in the output. 








6. Optionally, modify the names of columns in the Output Column Name column. 
7. Repeat steps 5 and 6 for each column in each input. 
8. Click OK. 


9. To save the updated package, click Save Selected Items on the File menu. 


See Also 


Union All Transformation 

Integration Services Transformations 
Integration Services Paths 

Data Flow Task 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


The Unpivot transformation makes an unnormalized dataset into a more normalized version by expanding 
values from multiple columns in a single record into multiple records with the same values in a single column. 
For example, a dataset that lists customer names has one row for each customer, with the products and the 
quantity purchased shown in columns in the row. After the Unpivot transformation normalizes the data set, the 
data set contains a different row for each product that the customer purchased. 


The following diagram shows a data set before the data is unpivoted on the Product column. 





| Destination Column |Cust [Qty [Qty | Qty 
Pivot Key Value Ham | Soda | Milk 
Column Name Cust_| HAM | Soda | Milk 
Data Records 































|Pivot Key False True 
Col Name Cust Product 
Data Kate Ham 





Records 














Under some circumstances, the unpivot results may contain rows with unexpected values. For example, if the 
sample data to unpivot shown in the diagram had null values in all the Qty columns for Fred, then the output 
would include only one row for Fred, not five. The Qty column would contain either null or zero, depending on 
the column data type. 


Configuration of the Unpivot Transformation 


The Unpivot transformation includes the PivotKeyValue custom property. This property can be updated by a 
property expression when the package is loaded. For more information, see Integration Services (SSIS) 
Expressions, Use Property Expressions in Packages, and Transformation Custom Properties. 


This transformation has one input and one output. It has no error output. 
You can set properties through SSIS Designer or programmatically. 


For more information about the properties that you can set in the Advanced Editor dialog box or 
programmatically, click one of the following topics: 


@ Common Properties 
e Transformation Custom Properties 


For more information about how to set the properties, see Set the Properties of a Data Flow Component. 


Unpivot Transformation Editor 


Use the Unpivot Transformation Editor dialog box to select the columns to pivot into rows, and to specify the 
data column and the new pivot value output column. 





NOTE 


This topic relies on the Unpivot scenario described in Unpivot Transformation to illustrate the use of the options. 





Options 


Available Input Columns 
Using the check boxes, specify the columns to pivot into rows. 


Name 
View the name of the available input column. 


Pass Through 
Indicate whether to include the column in the unpivoted output. 


Input Column 
Select from the list of available input columns for each row. Your selections are reflected in the check box 
selections in the Available Input Columns table. 


In the Unpivot scenario described in Unpivot Transformation, the Input Columns are the Ham, Soda, Milk, Beer, 
and Chips columns. 


Destination Column 


Provide a name for the data column. 


In the Unpivot scenario described in Unpivot Transformation, the Destination Column is the quantity (Qty) 
column. 


Pivot Key Value 
Provide a name for the pivot value. The default is the name of the input column; however, you can choose any 
unique, descriptive name. 


The value of this property can be specified by using a property expression. 


In the Unpivot scenario described in Unpivot Transformation, the Pivot Values will appear in the new Product 
column designated by the Pivot Key Value Column Name option, as the text values Ham, Soda, Milk, Beer, 
and Chips. 


Pivot Key Value Column Name 
Provide a name for the pivot value column. The default is "Pivot Key Value"; however, you can choose any 


unique, descriptive name. 


In the Unpivot scenario described in Unpivot Transformation, the Pivot Key Value Column Name is Product and 
designates the new Product column into which the Ham, Soda, Milk, Beer, and Chips columns are unpivoted. 


See Also 


Integration Services Error and Message Reference 
Pivot Transformation 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 
Integration Services includes three types of data flow components: sources, transformations, and destinations. 


The following diagram shows a simple data flow that has a source, two transformations, and a destination. 








Source | 


| 


Transformation 
Transformation 


Destination | 


























Integration Services transformations provide the following functionality: 
e Splitting, copying, and merging rowsets and performing lookup operations. 


e Updating column values and creating new columns by applying transformations such as changing 
lowercase to uppercase. 


e Performing business intelligence operations such as cleaning data, mining text, or running data mining 
prediction queries. 


e Creating new rowsets that consist of aggregate or sorted values, sample data, or pivoted and unpivoted 
data. 


e Performing tasks such as exporting and importing data, providing audit information, and working with 
slowly changing dimensions. 


For more information, see Integration Services Transformations. 


You can also write custom transformations. For more information, see Developing a Custom Data Flow 
Component and Developing Specific Types of Data Flow Components. 


After you add the transformation to the data flow designer, but before you configure the transformation, you 
connect the transformation to the data flow by connecting the output of another transformation or source in the 
data flow to the input of this transformation. The connector between two data flow components is called a path. 
For more information about connecting components and working with paths, see Connect Components with 
Paths. 


To add a transformation to a data flow 


e Add or Delete a Component in a Data Flow 


To connect a transformation to a data flow 


@ Connect Components in a Data Flow 


To set the properties of a transformation 


e Set the Properties of a Data Flow Component 


See Also 


Data Flow Task 

Data Flow 

Connect Components with Paths 
Error Handling in Data 

Data Flow 


Transformation Custom Properties 
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Applies to: Q sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


In addition to the properties that are common to most data flow objects in the SQL Server Integration Services 
object model, many data flow objects have custom properties that are specific to the object. These custom 
properties are available only at run time, and are not documented in the Integration Services Managed 
Programming Reference Documentation. 


This topic lists and describes the custom properties of the various data flow transformations. For information 
about the properties common to most data flow objects, see Common Properties. 


Some properties of transformations can be set by using property expressions. For more information, see Data 
Flow Properties that Can Be Set by Using Expressions. 


Transformations with Custom Properties 


Aggregate 

Audit 

Cache Transform 
Character Map 
Conditional Split 
Copy Column 

Data Conversion 
Data Mining Query 
Derived Column 


Export Column 
Fuzzy Grouping 
Fuzzy Lookup 
Import Column 
Lookup 

Merge Join 

OLE DB Command 
Percentage Sampling 
Pivot 


Row Count 

Row Sampling 

Script Component 

Slowly Changing Dimension 
Sort 

Term Extraction 

Term Lookup 

Unpivot 


Transformations Without Custom Properties 


The following transformations have no custom properties at the component, input, or output levels: Merge 
Transformation, Multicast Transformation, and Union All Transformation. They use only the properties common 
to all data flow components. 


Aggregate Transformation Custom Properties 


The Aggregate transformation has both custom properties and the properties common to all data flow 
components. 


The following table describes the custom properties of the Aggregate transformation. All properties are 
read/write. 


PROPERTY DATA TYPE DESCRIPTION 


AutoExtendFactor Integer A value between 1 and 100 that 
specifies the percentage by which 
memory can be extended during the 
aggregation. The default value of this 
property is 25. 


CountDistinctKeys Integer A value that specifies the exact number 
of distinct counts that the aggregation 
can write. If a CountDistinctScale value 
is specified, the value in 
CountDistinctKeys takes precedence. 


CountDistinctScale Integer (enumeration) A value that describes the approximate 
number of distinct values in a column 
that the aggregation can count. This 
property can have one of the following 
values: 


Low (1)-indicates up to 500,000 key 
values 


Medium (2)-indicates up to 5 million 
key values 


High (3)-indicates more than 25 
million key values. 


Unspecified (0)-indicates no 
CountDistinctScale value is used. Using 
the Unspecified (0) option may affect 
performance in large data sets. 


Keys Integer A value that specifies the exact number 
of Group By keys that the aggregation 
writes. If a KeyScalevalue is specified, 
the value in Keys takes precedence. 


PROPERTY DATA TYPE DESCRIPTION 


KeyScale Integer (enumeration) A value that describes approximately 
how many Group By key values the 
aggregation can write. This property 
can have one of the following values: 


Low (1)-indicates up to 500,000 key 
values. 


Medium (2)-indicates up to 5 million 
key values. 


High (3)-indicates more than 25 
million key values. 


Unspecified (0)-indicates that no 
KeyScale value is used. 


The following table describes the custom properties of the output of the Aggregate transformation. All 


properties are read/write. 
PROPERTY DATA TYPE DESCRIPTION 


Keys Integer A value that specifies the exact number 
of Group By keys that the aggregation 
can write. If a KeyScale value is 
specified, the value in Keys takes 
precedence. 


KeyScale Integer (enumeration) A value that describes approximately 
how many Group By key values the 
aggregation can write. This property 
can have one of the following values: 


Low (1)-indicates up to 500,000 key 
values, 


Medium (2)-indicates up to 5 million 
key values, 


High (3)-indicates more than 25 
million key values. 


Unspecified (0)-indicates no KeyScale 
value is used. 


The following table describes the custom properties of the output columns of the Aggregate transformation. All 
properties are read/write. 


PROPERTY DATA TYPE DESCRIPTION 


AggregationColumnld Integer The LineagelD of a column that 
participates in GROUP BY or aggregate 
functions. 


PROPERTY 


AggregationComparisonFlags 


AggregationType 


CountDistinctKeys 


CountDistinctScale 


DATA TYPE 


Integer 


Integer (enumeration) 


Integer 


Integer (enumeration) 


DESCRIPTION 


A value that specifies how the 
Aggregate transformation compares 
string data in a column. For more 
information, see Comparing String 
Data. 


A value that specifies the aggregation 
operation to be performed on the 
column. This property can have one of 
the following values: 


Group by (0) 
Count (1) 

Count all (2) 
Countdistinct (3) 
Sum (4) 

Average (5) 
Maximum (7) 


Minimum (6) 


When the aggregation type is Count 
distinct, a value that specifies the 
exact number of keys that the 
aggregation can write. If a 
CountDistinctScale value is specified, 
the value in CountDistinctKeys takes 
precedence. 


When the aggregation type is Count 
distinct, a value that describes 
approximately how many key values 
the aggregation can write. This 
property can have one of the following 
values: 


Low (1)-indicates up to 500,000 key 
values, 


Medium (2)-indicates up to 5 million 
key values, 


High (3)-indicates more than 25 
million key values. 


Unspecified (0)-indicates no 
CountDistinctScale value is used. 


PROPERTY 


IsBig 


DATA TYPE 


Boolean 


DESCRIPTION 


A value that indicates whether the 
column contains a value larger than 4 
billion or a value with more precision 
than a double-precision floating-point 
value. The value can be 0 or 1. 0 
indicates that IsBig is False and the 
column does not contain a large value 
or precise value. The default value of 
this property is 1. 


The input and the input columns of the Aggregate transformation have no custom properties. 


For more information, see Aggregate Transformation. 


Audit Transformation Custom Properties 


The Audit transformation has only the properties common to all data flow components at the component level. 


The following table describes the custom properties of the output columns of the Audit transformation. All 


properties are read/write. 


PROPERTY NAME 


LineageltemSelected 


DATA TYPE 


Integer (enumeration) 


DESCRIPTION 


The audit item selected for output. This 
property can have one of the following 
values: 

Execution instance GUID (0) 
Execution start time (4) 

Machine name (5) 

Package ID (1) 

Package name (2) 

Task ID (8) 

Task name (7) 


User name (6) 


Version ID (3) 


The input, the input columns, and the output of the Audit transformation have no custom properties. 


For more information, see Audit Transformation. 


Cache Transform Transformation Custom Properties 


The Cache Transform transformation has both custom properties and the properties common to all data flow 


components. 


The following table describes the properties of the Cache Transform transformation. All properties are 


read/write. 


PROPERTY DATA TYPE 
Connectionmanager String 
ValidateExternalMetadata Boolean 
AvailablelnputColumns String 
InputColumns String 
CacheColumnName String 


DESCRIPTION 


Specifies the name of the connection 
manager. 


Indicates whether the Cache Transform 
is validated by using external data 
sources at design time. If the property 
is set to False, validation against 
external data sources occurs at run 
time. 


The default value it True. 


A list of the available input columns. 


A list of the selected input columns. 


Specifies the name of the column that 
is mapped to a selected input column. 


The name of the column in the 
CacheColumnName property must 
match the name of the corresponding 
column listed on the Columns page 
of the Cache Connection Manager 
Editor. 


For more information, see Cache 
Connection Manager Editor 


Character Map Transformation Custom Properties 


The Character Map transformation has only the properties common to all data flow components at the 


component level. 


The following table describes the custom properties of the output columns of the Character Map 


transformation. All properties are read/write. 


PROPERTY DATA TYPE 


InputColumnLineageld Integer 


DESCRIPTION 


A value that specifies the LineagelD 
of the input column that is the source 
of the output column. 


PROPERTY DATA TYPE DESCRIPTION 


MapFlags Integer (enumeration) A value that specifies the string 
operations that the Character Map 
transformation performs on the 
column. This property can have one of 
the following values: 

Byte reversal (2) 

Full width (6) 

Half width (5) 
Hiragana (3) 
Katakana (4) 
Linguistic casing (7) 
Lowercase (0) 
Simplified Chinese (8) 


Traditional Chinese(9) 


Uppercase (1) 


The input, the input columns, and the output of the Character Map transformation have no custom properties. 


For more information, see Character Map Transformation. 


Conditional Split Transformation Custom Properties 


The Conditional Split transformation has only the properties common to all data flow components at the 
component level. 


The following table describes the custom properties of the output of the Conditional Split transformation. All 
properties are read/write. 


PROPERTY DATA TYPE DESCRIPTION 


EvaluationOrder Integer A value that specifies the position of a 
condition, associated with an output, 
in the list of conditions that the 
Conditional Split transformation 
evaluates. The conditions are evaluated 
in order from the lowest to the highest 
value. 


Expression String An expression that represents the 
condition that the Conditional Split 
transformation evaluates. Columns are 
represented by lineage identifiers. 


PROPERTY DATA TYPE DESCRIPTION 


FriendlyExpression String An expression that represents the 
condition that the Conditional Split 
transformation evaluates. Columns are 
represented by their names. 


The value of this property can be 


specified by using a property 
expression. 


IsDefaultOut Boolean A value that indicates whether the 
output is the default output. 


The input, the input columns, and the output columns of the Conditional Split transformation have no custom 
properties. 


For more information, see Conditional Split Transformation. 


Copy Column Transformation Custom Properties 


The Copy Column transformation has only the properties common to all data flow components at the 


component level. 


The following table describes the custom properties of the output columns of the Copy Column transformation. 
All properties are read/write. 


PROPERTY NAME DATA TYPE DESCRIPTION 

copyColumnld Integer The LineagelD of the input column 
from which the output column is 
copied. 


The input, the input columns, and the output of the Copy Column transformation have no custom properties. 


For more information, see Copy Column Transformation. 


Data Conversion Transformation Custom Properties 


The Data Conversion transformation has only the properties common to all data flow components at the 


component level. 


The following table describes the custom properties of the output columns of the Data Conversion 
transformation. All properties are read/write. 


PROPERTY DATA TYPE DESCRIPTION 


PROPERTY 


FastParse 


SourcelnputColumnLineageld 


DATA TYPE 


Boolean 


Integer 


DESCRIPTION 


A value that indicates whether the 
column uses the quicker, but locale- 
insensitive, fast parsing routines that 
Integration Services provides, or the 
locale-sensitive standard parsing 
routines. The default value of this 
property is False. For more 
information, see Fast Parse and 
Standard Parse. . 


Note: This property is not available in 
the Data Conversion 
Transformation Editor, but can be 
set by using the Advanced Editor. 


The LineagelD of the input column 
that is the source of the output 
column. 


The input, the input columns, and the output of the Data Conversion transformation have no custom properties. 


For more information, see Data Conversion Transformation. 


Data Mining Query Transformation Custom Properties 


The Data Mining Query transformation has both custom properties and the properties common to all data flow 


components. 


The following table describes the custom properties of the Data Mining Query transformation. All properties are 


read/write. 


PROPERTY 


ASConnectionld 


ASConnectionString 


CatalogName 


ModelName 


ModelStructureName 


ObjectRef 


QueryText 


DATA TYPE 


String 


String 


String 


String 


String 


String 


String 


DESCRIPTION 


The unique identifier of the connection 
object. 


The connection string to an Analysis 
Services project or an Analysis Services 
database. 


The name of an Analysis Services 
database. 


The name of the data mining model. 


The name of the mining structure. 


An XML tag that identifies the data 
mining structure that the 
transformation uses. 


The prediction query statement that 
the transformation uses. 


The input, the input columns, the output, and the output columns of the Data Mining Query transformation have 


no custom properties. 


For more information, see Data Mining Query Transformation. 


Derived Column Transformation Custom Properties 


The Derived Column transformation has only the properties common to all data flow components at the 


component level. 


The following table describes the custom properties of the input columns and output columns of the Derived 
Column transformation. When you choose to add the derived column as a new column, these custom properties 
apply to the new output column; when you choose to replace the contents of an existing input column with the 
derived results, these custom properties apply to the existing input column. All properties are read/write. 


PROPERTY DATA TYPE DESCRIPTION 


Expression String An expression that represents the 
condition that the Conditional Split 
transformation evaluates. Columns are 
represented by the LineagelD 
property for the column. 


FriendlyExpression String An expression that represents the 
condition that the Conditional Split 
transformation evaluates. Columns are 
represented by their names. 


The value of this property can be 
specified by using a property 
expression. 


The input and output of the Derived Column transformation have no custom properties. 


For more information, see Derived Column Transformation. 


Export Column Transformation Custom Properties 


The Export Column transformation has only the properties common to all data flow components at the 


component level. 


The following table describes the custom properties of the input columns of the Export Column transformation. 
All properties are read/write. 


PROPERTY DATA TYPE DESCRIPTION 


AllowAppend Boolean A value that specifies whether the 
transformation appends data to an 
existing file. The default value of this 
property is False. 


ForceTruncate Boolean A value that specifies whether the 
transformation truncates an existing 
files before writing data. The default 
value of this property is False. 


PROPERTY DATA TYPE DESCRIPTION 


FileDataColumn!ID Integer A value that identifies the column that 
contains the data that the 
transformation inserts into a file. On 
the Extract Column, this property has 
a value of 0; on the File Path Column, 
this property contains the LineagelD 
of the Extract Column. 


WriteBOM Boolean A value that specifies whether a byte- 
order mark (BOM) is written to the file. 


The input, the output, and the output columns of the Export Column transformation have no custom properties. 


For more information, see Export Column Transformation. 


Import Column Transformation Custom Properties 


The Import Column transformation has only the properties common to all data flow components at the 


component level. 


The following table describes the custom properties of the input columns of the Import Column transformation. 
All properties are read/write. 


PROPERTY DATA TYPE DESCRIPTION 


ExpectBOM Boolean A value that specifies whether the 
Import Column transformation expects 
a byte-order mark (BOM). A BOM is 
only expected if the data has the 
DT_NTEXT data type. 


FileDataColumn!ID Integer A value that identifies the column that 
contains the data that the 
transformation inserts into the data 
flow. On the column of data to be 
inserted, this property has a value of 
0; on the column that contains the 
source file paths, this property 
contains the LineagelD of the column 
of data to be inserted. 


The input, the output, and the output columns of the Import Column transformation have no custom properties. 


For more information, see Import Column Transformation. 


Fuzzy Grouping Transformation Custom Properties 


The Fuzzy Grouping transformation has both custom properties and the properties common to all data flow 
components. 


The following table describes the custom properties of the Fuzzy Grouping transformation. All properties are 
read/write. 


PROPERTY DATA TYPE DESCRIPTION 


PROPERTY DATA TYPE DESCRIPTION 


Delimiters String The token delimiters that the 
transformation uses. The default 
delimiters include the following 
characters: space (), comma(,), period 
(), semicolon (;), colon (:), hyphen (-), 
double straight quotation mark ("), 
single straight quotation mark (’), 
ampersand (&), slash mark (/), 
backslash (\), at sign (@), exclamation 
point (!), question mark (?), opening 
parenthesis ((), closing parenthesis ()), 
less than (<), greater than (>), opening 
bracket (D, closing bracket (]), opening 
brace ({), closing brace (}), pipe (\), 
number sign (#), asterisk (*), caret (4), 
and percent (%). 


Exhaustive Boolean A value that specifies whether each 
input record is compared to every 
other input record. The value of True is 
intended mostly for debugging 
purposes. The default value of this 
property is False. 


Note: This property is not available in 
the Fuzzy Grouping 
Transformation Editor, but can be 
set by using the Advanced Editor. 


MaxMemoryUsage Integer The maximum amount of memory for 
use by the transformation. The default 
value of this property is 0, which 
enables dynamic memory usage. 


The value of this property can be 
specified by using a property 
expression. 


Note: This property is not available in 
the Fuzzy Grouping 
Transformation Editor, but can be 
set by using the Advanced Editor. 


MinSimilarity Double The similarity threshold that the 
transformation uses to identify 
duplicates, expressed as a value 
between 0 and 1. The default value of 
this property is 0.8. 


The following table describes the custom properties of the input columns of the Fuzzy Grouping transformation. 
All properties are read/write. 


PROPERTY DATA TYPE DESCRIPTION 


PROPERTY 


ExactFuzzy 


FuzzyComparisonFlags 


LeadingTrailingNumeralsSignificant 


MinSimilarity 


ToBeCleaned 


DATA TYPE 


Integer (enumeration) 


Integer (enumeration) 


Integer (enumeration) 


Double 


Boolean 


DESCRIPTION 


A value that specifies whether the 
transformation performs a fuzzy match 
or an exact match. The valid values are 
Exact and Fuzzy. The default value for 
this property is Fuzzy. 


A value that specifies how the 
transformation compares the string 
data in a column. This property can 
have one of the following values: 


FullySensitive 
IgnoreCase 
IgnoreKanaType 
IgnoreNonSpace 
IgnoreSymbols 


IgnoreWidth 


For more information, see Comparing 
String Data. 


A value that specifies the significance 
of numerals. This property can have 
one of the following values: 


NumeralsNotSpecial (0)-use if 
numerals are not significant. 


LeadingNumeralsSignificant (1)- 
use if leading numerals are significant. 


TrailingNumeralsSignificant (2)-use 
if trailing numerals are significant. 


LeadingAndtTrailingNumeralsSignif 
icant (3)-use if both leading and 
trailing numerals are significant. 


The similarity threshold used for the 
join on the column, specified as a value 
between 0 and 1. Only rows greater 
than the threshold qualify as matches. 


A value that specifies whether the 
column is used to identify duplicates; 
that is, whether this is a column on 
which you are grouping. The default 
value of this property is False. 


The following table describes the custom properties of the output columns of the Fuzzy Grouping 


transformation. All properties are read/write. 


PROPERTY NAME 


ColumntType 


InputID 


DATA TYPE 


Integer (enumeration) 


Integer 


DESCRIPTION 


A value that identifies the type of 
output column. This property can have 
one of the following values: 
Undefined (0) 

KeylIn (1) 

KeyOut (2) 

Similarity (3) 

ColumnSimilarity (4) 


PassThru (5) 


Canonical (6) 


The LineagelD of the corresponding 
input column. 


The input and output of the Fuzzy Grouping transformation have no custom properties. 


For more information, see Fuzzy Grouping Transformation. 


Fuzzy Lookup Transformation Custom Properties 


The Fuzzy Lookup transformation has both custom properties and the properties common to all data flow 


components. 


The following table describes the custom properties of the Fuzzy Lookup transformation. All properties except 


for ReferenceMetadataXML are read/write. 


PROPERTY 


CopyReferenceTable 


Delimiters 


DATA TYPE 


Boolean 


String 


DESCRIPTION 


Specifies whether a copy of the 
reference table should be made for 
fuzzy lookup index construction and 
subsequent lookups. The default value 
of this property is True. 


The delimiters that the transformation 
uses to tokenize column values. The 
default delimiters include the following 
characters: space (), comma (,), period 
(.) semicolon(;), colon (:) hyphen (-), 
double straight quotation mark ("), 
single straight quotation mark (’), 
ampersand (&), slash mark (/), 
backslash (\), at sign (@), exclamation 
point (!), question mark (?), opening 
parenthesis ((), closing parenthesis ()), 
less than (<), greater than (>), opening 
bracket (D, closing bracket (]), opening 
brace ({), closing brace (}), pipe (|). 
number sign (#), asterisk (*), caret (4), 
and percent (%). 


PROPERTY 


DropExistingMatchIndex 


Exhaustive 


MatchIndexName 


MatchIndexOptions 


MaxMemoryUsage 


DATA TYPE 


Boolean 


Boolean 


String 


Integer (enumeration) 


Integer 


DESCRIPTION 


A value that specifies whether the 
match index specified in 
MatchIndexName is deleted when 
MatchIndexOptions is not set to 
ReuseExistingIndex. The default value 
for this property is True. 


A value that specifies whether each 
input record is compared to every 
other input record. The value of True is 
intended mostly for debugging 
purposes. The default value of this 
property is False. 


Note: This property is not available in 
the Fuzzy Lookup Transformation 
Editor, but can be set by using the 
Advanced Editor. 


The name of the match index. The 
match index is the table in which the 
transformation creates and saves the 
index that it uses. If the match index is 
reused, MatchIndexName specifies the 
index to reuse. MatchIndexName must 
be a valid SQL Server identifier name. 
For example, if the name contains 
spaces, the name must be enclosed in 
brackets. 


A value that specifies how the 
transformation manages the match 
index. This property can have one of 
the following values: 


ReuseExistingIndex (0) 
GenerateNew!ndex (1) 
GenerateAndPersistNewIndex (2) 


GenerateAndMaintainNewIndex 


(3) 


The maximum cache size for the 
lookup table. The default value of this 
property is 0, which means the cache 
size has no limit. 


The value of this property can be 
specified by using a property 
expression. 


Note: This property is not available in 
the Fuzzy Lookup Transformation 
Editor, but can be set by using the 
Advanced Editor. 


PROPERTY DATA TYPE 


MaxOutputMatchesPerlnput Integer 
MinSimilarity Integer 
ReferenceMetadataXML String 
ReferenceTableName String 
WarmCaches Boolean 


DESCRIPTION 


The maximum number of matches the 
transformation can return for each 
input row. The default value of this 
property is 1. 


Note: Values greater than 100 can only 
be specified by using the Advanced 
Editor. 


The similarity threshold that the 
transformation uses at the component 
level, specified as a value between 0 
and 1. Only rows greater than the 
threshold qualify as matches. 


Identified for informational purposes 
only. Not supported. Future 
compatibility is not guaranteed. 


The name of the lookup table. The 
name must be a valid SQL Server 
identifier name. For example, if the 
name contains spaces, the name must 
be enclosed in brackets. 


When true, the lookup partially loads 
the index and reference table into 
memory before execution begins. This 
can enhance performance. 


The following table describes the custom properties of the input columns of the Fuzzy Lookup transformation. 


All properties are read/write. 


PROPERTY DATA TYPE 
FuzzyComparisonFlags Integer 
FuzzyComparisonFlagsEx Integer (enumeration) 
JoinToReferenceColumn String 


DESCRIPTION 


A value that specifies how the 
transformation compares the string 
data in a column. For more 
information, see Comparing String 
Data. 


A value that specifies which extended 
comparison flags the transformation 
uses. The values can include 
MapExpandLigatures, 
MapFoldCZone, MapFoldDigits, 
MapPrecomposed, and 
NoMapping. NoMapping cannot be 
used with other flags. 


A value that specifies the name of the 
column in the reference table to which 
the column is joined. 


PROPERTY DATA TYPE DESCRIPTION 


JoinType Integer A value that specifies whether the 
transformation performs a fuzzy or an 
exact match. The default value for this 
property is Fuzzy. The integer value 
for the exact join type is 1 and the 
value for the fuzzy join type is 2. 


MinSimilarity Double The similarity threshold that the 
transformation uses at the column 
level, specified as a value between 0 
and 1. Only rows greater than the 
threshold qualify as matches. 


The following table describes the custom properties of the output columns of the Fuzzy Lookup transformation. 
All properties are read/write. 


NOTE 


For output columns that contain passthrough values from the corresponding input columns, CopyFromReferenceColumn 
is empty and SourcelnputColumnLineagelD contains the LineagelD of the corresponding input column. For output 
columns that contain lookup results, CopyFromReferenceColumn contains the name of the lookup column, and 


SourcelnputColumnLineagelD is empty. 





PROPERTY DATA TYPE DESCRIPTION 


ColumnType Integer (enumeration) A value that identifies the type of 
output column for columns that the 
transformation adds to the output. 
This property can have one of the 
following values: 


Undefined (0) 
Similarity (1) 
Confidence (2) 


ColumnSimilarity (3) 


CopyFromReferenceColumn String A value that specifies the name of the 
column in the reference table that 
provides the value in an output 
column. 


SourcelnputColumnLineageld Integer A value that identifies the input 
column that provides values to this 
output column. 


The input and output of the Fuzzy Lookup transformation have no custom properties. 


For more information, see Fuzzy Lookup Transformation. 


Lookup Transformation Custom Properties 


The Lookup transformation has both custom properties and the properties common to all data flow 


components. 





The following table describes the custom properties of the Lookup transformation. All properties except for 


ReferenceMetadataXML are read/write. 


PROPERTY 


CacheType 


DefaultCodePage 


MaxMemoryUsage 


MaxMemoryUsage64 


NoMatchBehavior 


ParameterMap 


ReferenceMetaDataXML 


SqlCommand 


SqlCommandParam 


DATA TYPE 


Integer (enumeration) 


Integer 


Integer 


Integer 


Integer (enumeration) 


String 


String 


String 


String 


DESCRIPTION 


The cache type for the lookup table. 
The values are Full (0), Partial (1), and 
None (2). The default value of this 
property is Full. 


The default code page to use when 
code page information is not available 
from the data source. 


The maximum cache size for the 
lookup table. The default value of this 
property is 25, which means that the 
cache size has no limit. 


The maximum cache size for the 
lookup table on a 64-bit computer. 


A value that specifies whether rows 
without matching entries in the 
reference dataset are treated as errors. 


When the property is set to Treat 
rows with no matching entries as 
errors (0), the rows without matching 
entries are treated as errors. You can 
specify what should happen when this 
type of error occurs by using the Error 
Output page of the Lookup 
Transformation Editor dialog box. 
For more information, see Lookup 
Transformation Editor (Error Output 
Page). 


When the property is set to Send 
rows with no matching entries to 
the no match output (1), the rows 
are not treaded as errors. 


The default value is Treat rows with 
no matching entries as errors (0). 


A semicolon-delimited list of lineage 
IDs that map to the parameters used 
in the SqlCommand statement. 


Metadata for the columns in the 
lookup table that the transformation 
copies to its output. 


The SELECT statement that populates 
the lookup table. 


The parameterized SQL statement that 
populates the lookup table. 


The following table describes the custom properties of the input columns of the Lookup transformation. All 
properties are read/write. 


PROPERTY DATA TYPE DESCRIPTION 

CopyFromReferenceColumn String The name of the column in the 
reference table from which a column is 
copied. 

JoinToReferenceColumns String The name of the column in the 


reference table to which a source 
column joins. 


The following table describes the custom properties of the output columns of the Lookup transformation. All 
properties are read/write. 


PROPERTY NAME DATA TYPE DESCRIPTION 

CopyFromReferenceColumn String The name of the column in the 
reference table from which a column is 
copied. 


The input and output of the Lookup transformation have no custom properties. 


For more information, see Lookup Transformation. 


Merge Join Transformation Custom Properties 


The Merge Join transformation has both custom properties and the properties common to all data flow 
components. 


The following table describes the custom properties of the Merge Join transformation. 
PROPERTY DATA TYPE DESCRIPTION 


JoinType Integer (enumeration) Specifies whether the join is an inner 
(2), left outer (1), or full join (0). 


MaxBuffersPerInput Integer You no longer have to configure the 
value of the MaxBuffersPerInput 
property because Microsoft has made 
changes that reduce the risk that the 
Merge Join transformation will 
consume excessive memory. This 
problem sometimes occurred when the 
multiple inputs of the Merge Join 
produced data at uneven rates. 


NumKeyColumns Integer The number of columns that are used 
in the join. 
TreatNullsAsEqual Boolean A value that specifies whether the 


transformation handles null values as 
equal values. The default value of this 
property is True. If the property value 
is False, the transformation handles 
null values like SQL Server does. 


The following table describes the custom properties of the output columns of the Merge Join transformation. All 
properties are read/write. 


PROPERTY NAME DATA TYPE DESCRIPTION 


InputColumn|D Integer The LineagelD of the input column 
from which data is copied to this 
output column. 


The input, the input columns, and the output of the Merge Join transformation have no custom properties. 


For more information, see Merge Join Transformation. 


OLE DB Command Transformation Custom Properties 


The OLE DB Command transformation has both custom properties and the properties common to all data flow 
components. 


The following table describes the custom properties of the OLE DB Command transformation. 


PROPERTY NAME DATA TYPE DESCRIPTION 


CommandTimeout Integer The maximum number of seconds that 
the SQL command can run before 
timing out. A value of 0 indicates an 
infinite time. The default value of this 
property is 0. 


DefaultCodePage Integer The code page to use when code page 
information is unavailable from the 
data source. 


SQLCommand String The Transact-SQL statement that the 
transformation runs for each row in 
the data flow. 


The value of this property can be 
specified by using a property 
expression. 


The following table describes the custom properties of the external columns of the OLE DB Command 
transformation. All properties are read/write. 


PROPERTY NAME DATA TYPE DESCRIPTION 


DBParam|nfoFlag Integer (bitmask) A set of flags that describe parameter 
characteristics. For more information, 
see the DBPARAMFLAGSENUM in the 
OLE DB documentation in the MSDN 
Library. 


The input, the input columns, the output, and the output columns of the OLE DB Command transformation have 
no custom properties. 


For more information, see OLE DB Command Transformation. 


Percentage Sampling Transformation Custom Properties 


The Percentage Sampling transformation has both custom properties and the properties common to all data 
flow components. 


The following table describes the custom properties of the Percentage Sampling transformation. 


PROPERTY DATA TYPE DESCRIPTION 


SamplingSeed Integer The seed the random number 
generator uses. The default value of 
this property is 0, indicating that the 
transformation uses a tick count. 


SamplingValue Integer The size of the sample as a percentage 
of the source. 


The value of this property can be 
specified by using a property 
expression. 


The following table describes the custom properties of the outputs of the Percentage Sampling transformation. 
All properties are read/write. 


PROPERTY NAME DATA TYPE DESCRIPTION 


Selected Boolean Designates the output to which the 
sampled rows are directed. On the 
selected output, Selected is set to 
True, and on the unselected output, 
Selected is set to False. 


The input, the input columns, and the output columns of the Percentage Sampling transformation have no 
custom properties. 


For more information, see Percentage Sampling Transformation. 


Pivot Transformation Custom Properties 


The following table describes the custom component properties of the Pivot transformation. 


PROPERTY DATA TYPE DESCRIPTION 
PassThroughUnmatchedPivotKeyt Boolean Set to True to configure the Pivot 
s transformation to ignore rows 


containing unrecognized values in the 
Pivot Key column and to output all of 
the pivot key values to a log message, 
when the package is run. 


The following table describes the custom properties of the input columns of the Pivot transformation. All 
properties are read/write. 


PROPERTY DATA TYPE DESCRIPTION 


PROPERTY DATA TYPE 


PivotUsage Integer (enumeration) 


DESCRIPTION 


A value that specifies the role of a 
column when the data set is pivoted. 


0: 

The column is not pivoted, and the 
column values are passed through to 
the transformation output. 


As 

The column is part of the set key that 
identifies one or more rows as part of 
one set. All input rows with the same 
set key are combined into one output 
row. 


2: 

The column is a pivot column. At least 
one column is created from each 
column value. 


3: 

The values from this column are put in 
columns that are created as a result of 
the pivot. 


The following table describes the custom properties of the output columns of the Pivot transformation. All 


properties are read/write. 


PROPERTY DATA TYPE 
PivotKeyValue String 
SourceColumn Integer 


For more information, see Pivot Transformation. 


Row Count Transformation Custom Properties 


DESCRIPTION 


One of the possible values from the 
column that is marked as the pivot key 
by the value of its PivotUsage 


property. 


The value of this property can be 
specified by using a property 
expression. 


The LineagelD of an input column 
that contains a pivoted value, or -1. 
The value of -1 indicates that the 
column is not used in a pivot 
operation. 


The Row Count transformation has both custom properties and the properties common to all data flow 


components. 


The following table describes the custom properties of the Row Count transformation. All properties are 


read/write. 


PROPERTY NAME DATA TYPE DESCRIPTION 


VariableName String The name of the variable that holds 
the row count. 


The input, the input columns, the output, and the output columns of the Row Count transformation have no 
custom properties. 


For more information, see Row Count Transformation. 


Row Sampling Transformation Custom Properties 


The Row Sampling transformation has both custom properties and the properties common to all data flow 


components. 


The following table describes the custom properties of the Row Sampling transformation. All properties are 


read/write. 
PROPERTY DATA TYPE DESCRIPTION 
SamplingSeed Integer The seed that the random number 
generator uses. The default value of 
this property is 0, indicating that the 
transformation uses a tick count. 
SamplingValue Integer The row count of the sample. 


The value of this property can be 
specified by using a property 
expression. 


The following table describes the custom properties of the outputs of the Row Sampling transformation. All 
properties are read/write. 


PROPERTY NAME DATA TYPE DESCRIPTION 


Selected Boolean Designates the output to which the 
sampled rows are directed. On the 
selected output, Selected is set to 
True, and on the unselected output, 
Selected is set to False. 


The following table describes the custom properties of the output columns of the Row Sampling transformation. 
All properties are read/write. 


PROPERTY DATA TYPE DESCRIPTION 


InputColumnLineageld Integer A value that specifies the LineagelD 
of the input column that is the source 
of the output column. 


The input and input columns of the Row Sampling transformation have no custom properties. 


For more information, see Row Sampling Transformation. 


Script Component Custom Properties 


The Script Component has both custom properties and the properties common to all data flow components. 
The same custom properties are available whether the Script Component functions as a source, transformation, 
or destination. 


The following table describes the custom properties of the Script Component. All properties are read/write. 


PROPERTY NAME DATA TYPE DESCRIPTION 


ReadOnlyVariables String A comma-separated list of variables 
available to the Script Component for 
read-only access. 


ReadWriteVariables String A comma-separated list of variables 
available to the Script Component for 
read/write access. 


The input, the input columns, the output, and the output columns of the Script Component have no custom 
properties, unless the script developer creates custom properties for them. 


For more information, see Script Component. 


Slowly Changing Dimension Transformation Custom Properties 


The Slowly Changing Dimension transformation has both custom properties and the properties common to all 
data flow components. 


The following table describes the custom properties of the Slowly Changing Dimension transformation. All 
properties are read/write. 


PROPERTY DATA TYPE DESCRIPTION 


CurrentRowWhere String The WHERE clause in the SELECT 
statement that selects the current row 
among rows with the same business 
key. 


EnablelnferredMember Boolean A value that specifies whether inferred 
member updates are detected. The 
default value of this property is True. 


FailOnFixedAttributeChange Boolean A value that specifies whether the 
transformation fails when row columns 
with fixed attributes contain changes 
or the lookup in the dimension table 
fails. If you expect incoming rows to 
contain new records, set this value to 
True to make the transformation 
continue after the lookup fails, because 
the transformation uses the failure to 
identify new records. The default value 
of this property is False. 


FailOnLookupFailure Boolean A value that specifies whether the 
transformation fails when a lookup of 
an existing record fails. The default 
value of this property is False. 


PROPERTY DATA TYPE 
IncomingRowChangeType Integer 
InferredMemberIndicator String 
SQLCommand String 
UpdateChangingAttributeHistory Boolean 


DESCRIPTION 


A value that specifies whether all 
incoming rows are new rows, or 
whether the transformation should 
detect the type of change. 


The column name for the inferred 
member. 


The SQL statement used to create a 
schema rowset. 


A value that indicates whether 
historical attribute updates are 
directed to the transformation output 
for changing attribute updates. 


The following table describes the custom properties of the input columns of the Slowly Changing Dimension 


transformation. All properties are read/write. 


PROPERTY DATA TYPE 


ColumnType Integer (enumeration) 


DESCRIPTION 


The update type of the column. The 
values are: Changing Attribute (2), 
Fixed Attribute (4), Historical 
Attribute (3), Key (1), and Other (0). 


The input, the outputs, and the output columns of the Slowly Changing Dimension transformation have no 


custom properties. 


For more information, see Slowly Changing Dimension Transformation. 


Sort Transformation Custom Properties 


The Sort transformation has both custom properties and the properties common to all data flow components. 


The following table describes the custom properties of the Sort transformation. All properties are read/write. 


PROPERTY DATA TYPE 
EliminateDuplicates Boolean 
MaximumThreads Integer 


DESCRIPTION 


Specifies whether the transformation 
removes duplicate rows from the 
transformation output. The default 
value of this property is False. 


Contains the maximum number of 
threads the transformation can use for 
sorting. A value of 0 indicates an 
infinite number of threads. The default 
value of this property is 0. 


The value of this property can be 
specified by using a property 
expression. 


The following table describes the custom properties of the input columns of the Sort transformation. All 


properties are read/write. 


PROPERTY DATA TYPE DESCRIPTION 


NewComparisonFlags Integer (bitmask) A value that specifies how the 
transformation compares the string 
data in a column. For more 
information, see Comparing String 
Data. 


NewSortKeyPosition Integer A value that specifies the sort order of 
the column. A value of 0 indicates that 
the data is not sorted on this column. 


The following table describes the custom properties of the output columns of the Sort transformation. All 
properties are read/write. 


PROPERTY DATA TYPE DESCRIPTION 
SortColumnID Integer The LineagelD of a sort column. 


The input and output of the Sort transformation have no custom properties. 


For more information, see Sort Transformation. 


Term Extraction Transformation Custom Properties 


The Term Extraction transformation has both custom properties and the properties common to all data flow 
components. 


The following table describes the custom properties of the Term Extraction transformation. All properties are 
read/write. 


PROPERTY DATA YPE DESCRIPTION 


FrequencyThreshold Integer A numeric value that indicates the 
number of times a term must occur 
before it is extracted. The default value 
of this property is 2. 


IsCaseSensitive Boolean A value that specifies whether case 
sensitivity is used when extracting 
nouns and noun phrases. The default 
value of this property is False. 


MaxLengthOflferm Integer A numeric value that indicates the 
maximum length of a term. This 
property applies only to phrases. The 
default value of this property is 12. 


NeedRefenceData Boolean A value that specifies whether the 
transformation uses a list of exclusion 
terms stored in a reference table. The 
default value of this property is False. 


OutTermColumn String The name of the column that contains 
the exclusion terms. 


PROPERTY 


OutTermTable 


ScoreType 


WordOrPhrase 


DATA YPE 


String 


Integer 


Integer 


DESCRIPTION 


The name of the table that contains 
the column with exclusion terms. 


A value that specifies the type of score 
to associate with the term. Valid values 
are 0 indicating frequency, and 1 
indicating a TFIDF score. The TFIDF 
score is the product of Term Frequency 
and Inverse Document Frequency, 
defined as: TFIDF of a Term T = 
(frequency of T) * log( (#rows in Input) 
/ (#rows having T) ). The default value 
of this property is 0. 


A value that specifies term type. The 
valid values are 0 indicating words 
only, 1 indicating noun phrases only, 
and 2 indicating both words and noun 
phrases. The default value of this 
property is 0. 


The input, the input columns, the output, and the output columns of the Term Extraction transformation have no 


custom properties. 


For more information, see Term Extraction Transformation. 


Term Lookup Transformation Custom Properties 


The Term Lookup transformation has both custom properties and the properties common to all data flow 


components. 


The following table describes the custom properties of the Term Lookup transformation. All properties are 


read/write. 


PROPERTY 


IsCaseSensitive 


ReffermColumn 


ReffermTable 


DATA TYPE 


Boolean 


String 


String 


DESCRIPTION 


A value that specifies whether a case 
sensitive comparison applies to the 
match of the input column text and 
the lookup term. The default value of 
this property is False. 


The name of the column that contains 
the lookup terms. 


The name of the table that contains 
the column with lookup terms. 


The following table describes the custom properties of the input columns of the Term Lookup transformation. 


All properties are read/write. 


PROPERTY 


DATA TYPE 


DESCRIPTION 


PROPERTY DATA TYPE DESCRIPTION 


InputColumnType Integer A value that specifies the use of the 
column. Valid values are 0 for a 
passthrough column, 1 for a lookup 
column, and 2 for a column that is 
both a passthrough and a lookup 
column. 


The following table describes the custom properties of the output columns of the Term Lookup transformation. 
All properties are read/write. 


PROPERTY NAME DATA TYPE DESCRIPTION 


CustomLineagelD Integer The LineagelD of the corresponding 
input column if the 
InputColumntype of that column is 
0 or 2. 


The input and output of the Term Lookup transformation have no custom properties. 


For more information, see Term Lookup Transformation. 


Unpivot Transformation Custom Properties 


The Unpivot transformation has only the properties common to all data flow components at the component 
level. 


NOTE 


This section relies on the Unpivot scenario described in Unpivot Transformation to illustrate the use of the options 


described here. 





The following table describes the custom properties of the input columns of the Unpivot transformation. All 
properties are read/write. 


PROPERTY DATA TYPE DESCRIPTION 


DestinationColumn Integer The LineagelD of the output column 
to which the input column maps. A 
value of -1 indicates that the input 
column is not mapped to an output 
column. 


PROPERTY 


PivotKeyValue 


DATA TYPE 


String 


DESCRIPTION 


A value that is copied to a 
transformation output column. 


The value of this property can be 
specified by using a property 
expression. 


In the Unpivot scenario described in 
Unpivot Transformation, the Pivot 
Values are the text values Ham, Coke, 
Milk, Beer, and Chips. These will appear 
as text values in the new Product 
column designated by the Pivot Key 
Value Column Name option. 


The following table describes the custom properties of the output columns of the Unpivot transformation. All 


properties are read/write. 


PROPERTY NAME 


PivotKey 


DATA TYPE 


Boolean 


DESCRIPTION 


Indicates whether the values in the 
PivotKeyValue property of input 
columns are written to this output 
column. 


In the Unpivot scenario described in 
Unpivot Transformation, the Pivot 
Value column name is Product and 
designates the new Product column 
into which the Ham, Coke, Milk, Beer, 
and Chips columns are unpivoted. 


The input and output of the Unpivot transformation have no custom properties. 


For more information, see Unpivot Transformation. 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 
The XML source reads an XML data file and populates the columns in the source output with the data. 


The data in XML files frequently includes hierarchical relationships. For example, an XML data file can represent 
catalogs and items in catalogs. Before the data can enter the data flow, the relationship of the elements in XML 
data file must be determined, and an output must be generated for each element in the file. 


Schemas 


The XML source uses a schema to interpret the XML data. The XML source supports use of a XML Schema 
Definition (XSD) file or inline schemas to translate the XML data into a tabular format. If you configure the XML 
source by using the XML Source Editor dialog box, the user interface can generate an XSD from the specified 
XML data file. 


NOTE 
DTDs are not supported. 





The schemas can support a single namespace only; they do not support schema collections. 


NOTE 
The XML source does not validate the data in the XML file against the XSD. 











XML Source Editor 


The data in the XML files frequently includes hierarchical relationships. The XML Source Editor dialog box uses 
the specified schema to generate the XML source outputs. You can specify an XSD file, use an inline schema, or 
generate an XSD from the specified XML data file. The schema must be available at design time. 


The XML source generates tabular structures from the XML data by creating an output for every element that 
contains other elements in the XML files. For example, if the XML data represents catalogs and items in catalogs, 
the XML source creates an output for catalogs and an output for each type of item that the catalogs contain. The 
output of each item will contain output columns for the attributes of that item. 


To provide information about the hierarchical relationship of the data in the outputs, the XML source adds a 
column in the outputs that identifies the parent element for each child element. Using the example of catalogs 
with different types of items, each item would have a column value that identifies the catalog to which it 
belongs. 


The XML source creates an output for every element, but it is not required that you use all the outputs. You can 
delete any output that you do not want to use, or just not connect it to a downstream component. 


The XML source also generates the output names, to ensure that the names are unambiguous. These names 
may be long and may not identify the outputs in a way that is useful to you. You can rename the outputs, as long 
as their names remain unique. You can also modify the data type and the length of output columns. 


For every output, the XML source adds an error output. By default the columns in error outputs have Unicode 
string data type (DT_WSTR) with a length of 255, but you can configure the columns in the error outputs by 
modifying their data type and length. 


If the XML data file contains elements that are not in the XSD, these elements are ignored and no output is 
generated for them. On the other hand, if the XML data file is missing elements that are represented in the XSD, 


the output will contain columns with null values. 


When the data is extracted from the XML data file, it is converted to an Integration Services data type. However, 
the XML source cannot convert the XML data to the DT_TIME2 or DT_DBTIMESTAMP2 data types because the 
source does not support these data types. For more information, see Integration Services Data Types. 


The XSD or inline schema may specify the data type for elements, but if it does not, the XML Source Editor 
dialog box assigns the Unicode string data type (DT_WSTR) to the column in the output that contains the 
element, and sets the column length to 255 characters. 


If the schema specifies the maximum length of an element, the length of output column is set to this value. If the 
maximum length is greater than the length supported by the Integration Services data type to which the 
element is converted, then the data is truncated to the maximum length of the data type. For example, if a string 
has a length of 5000, it is truncated to 4000 characters because the maximum length of the DT_WSTR data type 
is 4000 characters; likewise, byte data is truncated to 8000 characters, the maximum length of the DT_BYTES 
data type. If the schema specifies no maximum length, the default length of columns with either data type is set 
to 255. Data truncation in the XML source is handled the same way as truncation in other data flow components. 


For more information, see Error Handling in Data. 


You can modify the data type and the column length. For more information, see Integration Services Data Types. 


Configuration of the XML Source 


The XML source supports three different data access modes. You can specify the file location of the XML data file, 
the variable that contains the file location, or the variable that contains the XML data. 


The XML source includes the XMLData and XMLSchemaDefinition custom properties that can be updated by 
property expressions when the package is loaded. For more information, see Integration Services (SSIS) 
Expressions, Use Property Expressions in Packages, and XML Source Custom Properties. 


The XML source supports multiple regular outputs and multiple error outputs. 


SQL Server Integration Services includes the XML Source Editor dialog box for configuring the XML source. 
This dialog box is available in SSIS Designer. 


You can set properties through SSIS Designer or programmatically. 


The Advanced Editor dialog box reflects the properties that can be set programmatically. For more 
information about the properties that you can set in the Advanced Editor dialog box or programmatically, click 
one of the following topics: 


e Common Properties 
e XML Source Custom Properties 
For more information about how to set the properties, click one of the following topics: 


e Set the Properties of a Data Flow Component 


XML Source Editor (Connection Manager Page) 


Use the Connection Manager page of the XML Source Editor to specify an XML file and the XSD that 


transforms the XML data. 


Static Options 


Data access mode 
Specify the method for selecting data from the source. 


VALUE DESCRIPTION 
XML file location Retrieve data from an XML file. 
XML file from variable Specify the XML file name in a variable. 


Related information: Use Variables in Packages 
XML data from variable Retrieve XML data from a variable. 


Use inline schema 
Specify whether the XML source data itself contains the XSD schema that defines and validates its structure and 
data. 


XSD location 
Type the path and file name of the XSD schema file, or locate the file by clicking Browse. 


Browse 
Use the Open dialog box to locate the XSD schema file. 


Generate XSD 
Use the Save As dialog box to select a location for the auto-generated XSD schema file. The editor infers the 
schema from the structure of the XML data. 


Data Access Mode Dynamic Options 

Data access mode = XML file location 

XML location 

Type the path and file name of the XML data file, or locate the file by clicking Browse. 


Browse 

Use the Open dialog box to locate the XML data file. 

Data access mode = XML file from variable 

Variable name 

Select the variable that contains the path and file name of the XML file. 
Data access mode = XML data from variable 


Variable name 
Select the variable that contains the XML data. 


XML Source Editor (Columns Page) 


Use the Columns node of the XML Source Editor dialog box to map an output column to an external (source) 
column. 


Options 
Available External Columns 
View the list of available external columns in the data source. You cannot use this table to add or delete columns. 


External Column 
View external (source) columns in the order in which the task will read them. You can change this order by first 


clearing the selected columns in the table displayed in the editor, and then selecting external columns from the 
list in a different order. 


Output Column 

Provide a unique name for each output column. The default is the name of the selected external (source) 
column; however, you can choose any unique, descriptive name. The name provided will be displayed within 
SSIS Designer. 


XML Source Editor (Error Output Page) 


Use the Error Output page of the XML Source Editor dialog box to select error handling options and to set 
properties on error output columns. 

Options 

Input/Output 


View the name of the data source. 


Column 
View the external (source) columns that you selected on the Connection Manager page of the XML Source 
Editordialog box. 


Error 
Specify what should happen when an error occurs: ignore the failure, redirect the row, or fail the component. 


Related Topics: Error Handling in Data 


Truncation 
Specify what should happen when a truncation occurs: ignore the failure, redirect the row, or fail the component. 


Description 
View the description of the error. 


Set this value to selected cells 
Specify what should happen to all the selected cells when an error or truncation occurs: ignore the failure, 
redirect the row, or fail the component. 


Apply 
Apply the error handling option to the selected cells. 


Related Tasks 


Extract Data by Using the XML Source 


Extract Data by Using the XML Source 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 
To add and configure an XML source, the package must already include at least one Data Flow task. 


To extract data using an XML source 


1. In SQL Server Data Tools (SSDT), open the Integration Services project that contains the package you 
want. 


2. In Solution Explorer, double-click the package to open it. 

3. Click the Data Flow tab, and then, from the Toolbox, drag the XML source to the design surface. 
4. Double-click the XML source. 

5. In the XML Source Editor, on the Connection Manager page, select a data access mode: 


e For the XML file location access mode, click Browse and locate the folder that contains the XML 
file. 


e For the XML file from variable access mode, select the user-defined variable that contains the 
path of the XML file. 


e For the XML data from variable access mode, select the user-defined variable that contains the 
XML data. 





NOTE 


The variables must be defined in the scope of the Data Flow task that contains the XML source, or in the scope of 
the package; additionally, the variable must have a string data type. 








6. Optionally, select Use inline schema to indicate that the XML document includes schema information. 


7. To specify an external XML Schema definition language (XSD) schema for the XML file, do one of the 
following: 


e Click Browse to locate an existing XSD file. 
e Click Generate XSD to create an XSD from the XML file. 
8. To update the names of output columns, click Columns and edit the values in the Output Column list. 
9. To configure the error output, click Error Output. For more information, see Debugging Data Flow. 
10. Click OK. 


11. To save the updated package, click Save Selected Items on the File menu. 


See Also 


XML Source 
Integration Services Transformations 
Integration Services Paths 


Data Flow Task 


XML Source Custom Properties 
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Applies to: Q@ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 
The XML source has both custom properties and the properties common to all data flow components. 


The following table describes the custom properties of the XML source. All properties are read/write. 


PROPERTY NAME DATA TYPE DESCRIPTION 

AccessMode Integer The mode used to access the XML 
data. 

UselnlineSchema Boolean A value that indicates whether to use 


an inline schema definition within the 
XML source. The default value of this 
property is False. 


XMLData String The file or variables from which to 
retrieve the XML data. 


The value of this property can be 
specified by using a property 
expression. 


XMLSchemaDefinition String The path and file name of the schema 
definition file (xsd). 


The value of this property can be 


specified by using a property 
expression. 


The following table describes the custom properties of the output of the XML source. All properties are 


read/write. 
PROPERTY NAME DATA TYPE DESCRIPTION 
Rowset|D String A value that identifies the rowset 


associated with the output. 


The output columns of the XML source have no custom properties. 


For more information, see XML Source. 


See Also 


Common Properties 


Integration Services (SSIS) Variables 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Variables store values that a SQL Server Integration Services package and its containers, tasks, and event 
handlers can use at run time. The scripts in the Script task and the Script component can also use variables. The 
precedence constraints that sequence tasks and containers into a workflow can use variables when their 
constraint definitions include expressions. 


You can use variables in Integration Services packages for the following purposes: 


e Updating properties of package elements at run time. For example, you can dynamically set the number 
of concurrent executables that a Foreach Loop container allows. 


e Including an in-memory lookup table. For example, a package can run an Execute SQL task that loads a 
variable with data values. 


e Loading variables with data values and then using them to specify a search condition in a WHERE clause. 
For example, the script in a Script task can update the value of a variable that is used by a Transact-SQL 
statement in an Execute SQL task. 


e Loading a variable with an integer and then using the value to control looping within a package control 
flow. For example, you can use a variable in the evaluation expression of a For Loop container to control 
iteration. 


e Populating parameter values for Transact-SQL statements at run time. For example, a package can run an 
Execute SQL task and then use variables to dynamically set the parameters in a Transact-SQL statement. 


e Building expressions that include variable values. For example, the Derived Column transformation can 
populate a column with the result obtained by multiplying a variable value by a column value. 


System and user-defined variables 


Integration Services supports two types of variables: user-defined variables and system variables. User-defined 
variables are defined by package developers, and system variables are defined by Integration Services. You can 
create as many user-defined variables as a package requires, but you cannot create additional system variables. 


All variables-system and user-defined-can be used in the parameter bindings that the Execute SQL task uses to 
map variables to parameters in SQL statements. For more information, see Execute SQL Task and Parameters 
and Return Codes in the Execute SQL Task. 





NOTE 


The names of user-defined and system variables are case sensitive. 











You can create user-defined variables for all Integration Services container types: packages, Foreach Loop 
containers, For Loop containers, Sequence containers, tasks, and event handlers. User-defined variables are 
members of the Variables collection of the container. 


If you create the package using SSIS Designer, you can see the members of the Variables collections in the 
Variables folders on the Package Explorer tab of SSIS Designer. The folders list user-defined variables and 
system variables. 


You can configure user-defined variables in the following ways: 

e Provide a name and description for the variable. 

e Specify a namespace for the variable. 

e Indicate whether the variable raises an event when its value changes. 

e Indicate whether the variable is read-only or read/write. 

e Use the evaluation result of an expression to set the variable value. 

e Create the variable in the scope of the package or a package object such as a task. 
e Specify the value and data type of the variable. 


The only configurable option on system variables is specifying whether they raise an event when they change 


value. 


A different set of system variables is available for different container types. For more information about the 
system variables used by packages and their elements, see System Variables. 


For more information about real-life use scenarios for variables, see Use Variables in Packages. 


Properties of variables 


You can configure user-defined variables by setting the following properties in either the Variables window or 
the Properties window. Certain properties are available only in the Properties window. 





NOTE 


The only configurable option on system variables is specifying whether they raise an event when they change value. 





Description 


Specifies the description of the variable. 


EvaluateAsExpression 
When the property is set to True, the expression provided is used to set the variable value. 


Expression 


Specifies the expression that is assigned to the variable. 


Name 
Specifies the variable name. 


Namespace 

Integration Services provides two namespaces, User and System. By default, custom variables are in the User 
namespace, and system variables are in the System namespace. You can create additional namespaces for user- 
defined variables and change the name of the User namespace, but you cannot change the name of the 
System namespace, add variables to the System namespace, or assign system variables to a different 
namespace. 


RaiseChangedEvent 
When the property is set to True, the OnVariableValueChanged event is raised when the variable changes 


value. 


ReadOnly 
When the property is set to False, the variable is read\write. 


Scope 





NOTE 


You can change this property setting only by clicking Move Variable in the Variables window. 





A variable is created within the scope of a package or within the scope of a container, task, or event handler in 
the package. Because the package container is at the top of the container hierarchy, variables with package 
scope function like global variables and can be used by all containers in the package. Similarly, variables defined 
within the scope of a container such as a For Loop container can be used by all tasks or containers within the For 


Loop container. 


If a package runs other packages by using the Execute Package task, the variables defined in the scope of the 
calling package or the Execute Package task can be made available to the called package by using the Parent 
Package Variable configuration type. For more information, see Package Configurations. 


IncludelnDebugDump 
Indicate whether the variable value is included in the debug dump files. 


For user-defined variables and system variables, the default value for the IncluelnDebugDump option is true. 


However, for user-defined variables, the system resets the IncludelnDebugDump option to false when the 
following conditions are met: 


e If the EvaluateAsExpression variable property is set to true, the system resets the 
IncludelnDebugDump option to false. 


To include the text of the expression as the variable value in the debug dump files, set the 
IncludelnDebugDump option to true. 


e If the variable data type is changed to a string, the system resets the IncludelnDebugDump option to 
false. 


When the system resets the IncludelnDebugDump option to false, this might override the value selected by 
the user. 


Value 
The value of a user-defined variable can be a literal or an expression. The value of a variable can't be null. 
Variables have the following default values: 


DATA TYPE DEFAULT VALUE 
Boolean False 

Numeric and binary data types 0 (zero) 

Char and string data types (empty string) 
Object System.Object 


A variable has options for setting the variable value and the data type of the value. The two properties must be 
compatible: for example, the use of a string value together with an integer data type is not valid. 


If the variable is configured to evaluate as an expression, you must provide an expression. At run time, the 


expression is evaluated, and the variable is set to the evaluation result. For example, if a variable uses the 


expression DATEPART("month", GETDATE()) the value of the variable is the number equivalent of the month for 
the current date. The expression must be a valid expression that uses the SSIS expression grammar syntax. 
When an expression is used with variables, the expression can use literals and the operators and functions that 
the expression grammar provides, but the expression cannot reference the columns from a data flow in the 
package. The maximum length of an expression is 4000 characters. For more information, see Integration 


Services (SSIS) Expressions. 


ValueType 





NOTE 


The property value appears in the Data type column in the Variables window. 





Specifies the data type of the variable value. 


Scenarios for using variables 


Variables are used in many different ways in Integration Services packages. You will probably find that package 
development does not progress far before you have to add a user-defined variable to your package to 
implement the flexibility and manageability your solution requires. Depending on the scenario, system variables 


are also commonly used. 


Property Expressions Use variables to provide values in the property expressions that set the properties of 
packages and package objects. For example, the expression, SELECT * FROM @varTableName includes the variable 
varTableName that updates the SQL statement that an Execute SQL task runs. The expression, 

DATEPART("d", GETDATE()) == 1? @[User: :varPackageFirst]:@[User: :varPackageOther] ", updates the package that 
the Execute Package task runs, by running the package specified in the varPackageFirst variable on the first day 
of the month and running the package specified in the varPackageOther variable on other days. For more 
information, see Use Property Expressions in Packages. 


Data Flow Expressions Use variables to provide values in the expressions that the Derived Column and 
Conditional Split transformations use to populate columns, or to direct data rows to different transformation 
outputs. For example, the expression, @varSalutation + LastName , concatenates the value in the varSalutation 
variable and the LastName column. The expression, Income < @HighIncome , directs data rows in which the value 
of the Income column is less than the value in the HighIncome variable to an output. For more information, see 


Derived Column Transformation, Conditional Split Transformation, and Integration Services (SSIS) Expressions. 


Precedence Constraint Expressions Provide values to use in precedence constraints to determine whether a 
constrained executable runs. The expressions can be used either together with an execution outcome (success, 
failure, completion), or instead of an execution outcome. For example, if the expression, @varMax > @varMin , 


evaluates to true, the executable runs. For more information, see Add Expressions to Precedence Constraints. 


Parameters and Return Codes Provide values to input parameters, or store the values of output parameters 
and return codes. You do this by mapping the variables to parameters and return values. For example, if you set 
the variable varProductId to 23 and run the SQL statement, 

SELECT * from Production.Product WHERE ProductID = ? , the query retrieves the product with a Productip of 23. 


For more information, see Execute SQL Task and Parameters and Return Codes in the Execute SQL Task. 


For Loop Expressions Provide values to use in the initialization, evaluation, and assignment expressions of the 
For Loop. For example, if the variable varcount is 2 and varmaxcount is 10, the initialization expression is 
@varCount , the evaluation expression is @varcount < @varMaxCount , and the assignment expression is 


@varCount =@varCount +1 , then the loop repeats 8 times. For more information, see For Loop Container. 


Parent Package Variable Configurations Pass values from parent packages to child packages. Child 
packages can access variables in the parent package by using parent package variable configurations. For 


example, if the child package must use the same date as the parent package, the child package can define a 
parent package variable configuration that specifies a variable set by the GETDATE function in the parent 
package. For more information, see Execute Package Task and Package Configurations. 


Script Task and Script Component Provide a list of read-only and read/write variable to the Script task or 
Script component, update the read/write variables within the script, and then use the updated values in or 
outside the script. For example, in the code, numberofcars = CType(Dts.Variables("NumberOfCars").Value, Integer) 
_ the script variable numberofcars is updated by the value in the variable, Numberofcars . For more information, 


see Using Variables in the Script Task. 


Add a variable 


1. In SQL Server Data Tools (SSDT), open the Integration Services package you want to work with. 
2. In Solution Explorer, double-click the package to open it. 
3. In SSIS Designer, to define the scope of the variable, do one of the following: 
e To set the scope to the package, click anywhere on the design surface of the Control Flow tab. 


@ To set the scope to an event handler, select an executable and an event handler on the design 
surface of the Event Handler tab. 


e To set the scope to a task or container, on the design surface of the Control Flow tab or the Event 
Handler tab, click a task or container. 


4. On the SSIS menu, click Variables. You can optionally display the Variables window by mapping the 
View.Variables command to a key combination of your choosing on the Keyboard page of the Options 
dialog box. 


5. Inthe Variables window, click the Add Variable icon. The new variable is added to the list. 


6. Optionally, click the Grid Options icon, select additional columns to show in the Variables Grid 
Options dialog box, and then click OK. 


7. Optionally, set the variable properties. For more information, see Set the Properties of a User-Defined 
Variable. 


8. To save the updated package, click Save Selected Items on the File menu. 
Add Variable dialog box 
Use the Add Variable dialog box to specify the properties of a new variable. 


Options 

Container 

Select a container in the list. The container defines the scope of the variable. The container can be either the 
package or an executable in the package. 


Name 
Type the variable name. 


Namespace 
Specify the namespace of the variable. By default, user-defined variables are in the User namespace. 


Value type 
Select a data type. 


Value 
Type a value. The value must be compatible with the data type specified in the Value type option. 


Read-only 
Select to make the variable read-only. 


Delete a variable 


1. In SQL Server Data Tools (SSDT), open the Integration Services project that contains the package you 


want. 
2. In Solution Explorer, right-click the package to open it. 


3. On the SSIS menu, click Variables. You can optionally display the Variables window by mapping the 
View.Variables command to a key combination of your choosing on the Keyboard page of the Options 
dialog box. 


4. Select the variable to delete, and then click Delete Variable. 


If you don't see the variable in the Variables window, click Grid Options and then select Show 
variables of all scopes. 


5. If the Confirm Deletion of Variables dialog box opens, click Yes to confirm. 


6. To save the updated package, click Save Selected Items on the File menu. 


Change the scope of a variable 


1. In SQL Server Data Tools (SSDT), open the Integration Services project that contains the package you 


want. 
2. In Solution Explorer, right-click the package to open it. 


3. On the SSIS menu, click Variables. You can optionally display the Variables window by mapping the 
View.Variables command to a key combination of your choosing on the Keyboard page of the Options 
dialog box. 


4. Select the variable and then click Move Variable. 


If you don't see the variable in the Variables window, click Grid Options and then select Show 
variables of all scopes. 


5. In the Select New Scope dialog box, select the package or a container, task, or event handler in the 
package, to change the variable scope. 


6. To save the updated package, click Save Selected Items on the File menu. 


Set the properties of a user-defined variable 
To set the properties of a user-defined variable in Integration Services, you can use one of the following features: 
e Variables window. 


e Properties window. The Properties window lists properties for configuring variables that are not 
available in the Variables window: Description, EvaluateAsExpression, Expression, ReadOnly, ValueType, 
and IncludelnDebugDump. 





NOTE 


Integration Services also provides a set of system variables whose properties cannot be updated, with the exception of 
the RaiseChangedEvent property. 











Set expressions on variables 


When you use the Properties window to set expressions on a user-defined variable: 


e The value of a variable can be set by the Value or the Expression property. By default, the 
EvaluateAsExpression property is set to False and the value of the variable is set by the Value property. To 
use an expression to set the value, you must first set EvaluateAsExpression to True, and then provide an 
expression in the Expression property. The Value property is automatically set to the evaluation result of 
the expression. 


e The ValueType property contains the data type of the value in the Value property. When Value is set by an 
expression, ValueType is automatically updated to a data type that is compatible with the evaluation result 
of the expression. For example, if Value contains 0 and ValueType property contains Int32 and you then 
set Expression to GETDATE(), Value contains the current date and time and ValueType is set to DateTime. 


e The Properties window for the variable provides access to the Expression Builder dialog box. You can 
use this tool to build, validate, and evaluate expressions. For more information, see Expression Builder 
and Integration Services (SSIS) Expressions. 


When you use the Variables window to set expressions on a user-defined variable: 


e To use an expression to set the variable value, first confirm that the variable data type is compatible with 
the evaluation result of the expression and then provide an expression in the Expression column of the 
Variables window. The EvaluateAsExpression property in the Properties window is automatically set to 
True. 


e When you assign an expression to a variable, a special icon marker displays next to the variable. This 
special icon marker also displays next to connection managers and tasks that have expressions set on 
them. 


e The Variables window for the variable provides access to the Expression Builder dialog box. You can 
use this tool to build, validate, and evaluate expressions. For more information, see Expression Builder 


and Integration Services (SSIS) Expressions. 


In both the Variables and Properties window, if you assign an expression to the variable, and 
EvaluateAsExpression is set to True, you cannot change the variable data type. 


Set the Namespace and Name properties 


The values of the Name and Namespace properties must begin with an alphabetic character letter as defined 
by the Unicode Standard 2.0, or an underscore (_). Subsequent characters can be letters or numbers as defined 
in the Unicode Standard 2.0, or the underscore (_). 


Set Variable Properties in the Variables Window 


1. In SQL Server Data Tools (SSDT), open the Integration Services project that contains the package you 
want. 


2. In Solution Explorer, right-click the package to open it. 
3. On the SSIS menu, click Variables. 


You can optionally display the Variables window by mapping the View.Variables command to a key 
combination of your choosing on the Keyboard page of the Options dialog box. 


4. Optionally, in the Variables window click Grid Options, and then select the columns to appear in the 
Variables window and select the filters to apply to the list of variables. 


5. Select the variable in the list, and then update values in the Name, Data Type, Value, Namespace, 
Raise Change Event, Description, and Expression columns. 


6. Select the variable in the list, and then click Move Variable to change the scope. 
7. To save the updated package, on the File menu, click Save Selected Items. 


Set Variable Properties in the Properties Window 


1. In SQL Server Data Tools (SSDT), open the Integration Services project that contains the package you 
want. 


2. In Solution Explorer, right-click the package to open it. 
3. On the View menu, click Properties Window. 
4. In SSIS Designer, click the Package Explorer tab and expand the Package node. 


5. To modify variables with package scope, expand the Variables node; otherwise, expand the Event 
Handlers or Executables nodes until you locate the Variables node that contains the variable that you 
want to modify. 


6. Click the variable whose properties you want to modify. 


7. In the Properties window, update the read/write variable properties. Some properties are read/read 
only for user-defined variables. 


For more information about the properties, see Integration Services (SSIS) Variables. 


8. To save the updated package, on the File menu, click Save Selected Items. 


Update a variable dynamically with configurations 


To dynamically update variables, you can create configurations for the variables, deploy the configurations with 
the package, and then update the variable values in the configuration file when you deploy the packages. At run 
time, the package uses the updated variable values. For more information, see Create Package Configurations. 


Related Tasks 


Use the Values of Variables and Parameters in a Child Package 


Map Query Parameters to Variables in a Data Flow Component 


Variables Window 
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Applies to: Q sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 
Use the Variables window to create and modify user-defined variables and view system variables. 


By default, the Variables window is located below the Connection Managers area in the SSIS Designer, in 
SQL Server Data Tools (SSDT). If you don't see the Variables window, click Variables on the SSIS menu to 
display the window. 


You can optionally display the Variables window by mapping the View.Variables command to a key 
combination of your choosing on the Keyboard page of the Options dialog box. 


NOTE 


The values of the Name and Namespace properties must begin with an alphabetic character letter as defined by the 
Unicode Standard 2.0, or an underscore (_). Subsequent characters can be letters or numbers as defined in the Unicode 
Standard 2.0, or the underscore (_). 











Options 


Add Variable 
Add a user-defined variable. 


Move Variable 

Click a variable in the list, and then click Move Variable to change the variable scope. In the Select New 
Scope dialog box, select the package or a container, task, or event handler in the package, to change the variable 
scope. 


For more information about variable scope, see Integration Services (SSIS) Variables. 


Delete Variable 
Select a variable from the list, and then click Delete Variable. 


Grid Options 
Click to open the Variable Grid Options dialog box where you can change the column selection and apply 
filters to the Variables window. For more information, see Variable Grid Options. 


Name 
View the variable name. You can update the name for user-defined variables. 


Scope 

View the scope of the variable. A variable has either the scope of the entire package, or the scope of a container 
or task. The scope of the variable must be sufficient so that the variable is visible to any other tasks or 
components that need to read or set its value. 


You can change the scope by clicking the variable and then clicking Move Variable in the Variables window. 


Data Type 
View the data type of the variable. You can select a data type from the list for user-defined variables. 





NOTE 


If you assign an expression to the variable, you cannot change the data type. 





Value 


View the variable value. You can update the value for user-defined variables. This value can be a literal or an 
expression, and the value can be a multi-line string. To assign an expression to the variable, click the ellipse 
button that is next to the Expression column in the Variables window. 


Namespace 
View the namespace name. User-defined variables are initially created in the User namespace, but you can 
change the namespace name in the Namespace field. To display this column, click Grid Options. 


Raise Change Event 

Indicate whether to raise the OnVariableValueChanged event when a value changes. You can update the 
value for user-defined and system variables. By default, the Variables window does not list this column. To 
display this column, click Grid Options. 


Description 
View the variable description. You can change the description for user-defined variables. By default, the 
Variables window does not list this column. To display this column, click Grid Options. 


Expression 


View the expression assigned to the variable. To assign an expression, click the ellipse button. 


If you assign an expression to a variable, a special icon marker displays next to the variable. This special icon 
marker also displays next to connection managers and tasks that have expressions set on them. 


Variable Grid Options dialog box 


Use the Variable Grid Options dialog box to select the columns that will display in the Variables window and 
to select the filters to apply to the list of variables. For more information about the corresponding variable 
properties, see Integration Services (SSIS) Variables. 


Options for Filter 


Show system variables 
Select to list system variables in the Variables window. System variables are predefined. You cannot add or 
delete system variables. You can modify the RaiseChangedEvent property setting. 


This list is color coded. System variables are gray, and user-defined variables are black. 


Show variables of all scopes 

Select to show variables within the scope the package, and within the scope of containers, tasks, and event 
handlers in the package. Clear this option to show only variables within the scope of the package and within the 
scope of a selected container, task, or event handler. 


For more information about variable scope, see Integration Services (SSIS) Variables. 


Options for Columns 


Select the columns that you want to appear in the Variables window. 
e Scope 
e Data type 


e Value 


e Namespace 
e Raise event when variable value changes 
e Description 


e Expression 


See Also 


Integration Services (SSIS) Variables 

Use Variables in Packages 

Integration Services (SSIS) Expressions 
Generating Dump Files for Package Execution 


System Variables 
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SQL Server Integration Services provides a set of system variables that store information about the running 
package and its objects. These variables can be used in expressions and property expressions to customize 
packages, containers, tasks, and event handlers. 


All variables-system and user-defined- can be used in the parameter bindings that the Execute SQL task uses to 


map variables to parameters. 


System Variables for Packages 


The following table describes the system variables that Integration Services provides for packages. 


SYSTEM VARIABLE DATA TYPE DESCRIPTION 


CancelEvent Int32 The handle to a Windows Event object 
that the task can signal to indicate that 
the task should stop running. 


ContainerStartTime DateTime The start time of the container. 
CreationDate DateTime The date that the package was created. 
CreatorComputerName String The computer on which the package 


was created. 


CreatorName String The name of the person who built the 
package. 
ExecutionInstanceGUID String The unique identifier of the executing 


instance of a package. 


FailedConfigurations String The names of package configurations 
that have failed. 


IgnoreConfigurationsOnLoad Boolean Indicates whether package 
configurations are ignored when 
loading the package. 


InteractiveMode Boolean Indicates whether the package is run in 
interactive mode. If a package is 
running in SSIS Designer, this property 
is set to True. If a package is running 
using the DTExec command prompt 
utility, the property is set to False. 


Localeld Int32 The locale that the package uses. 


SYSTEM VARIABLE 


MachineName 


OfflineMode 


PackagelD 


PackageName 


StartTime 


ServerExecutionID 


UserName 


VersionBuild 


VersionComment 


VersionGUID 


VersionMajor 


VersionMinor 


System Variables for Containers 


DATA TYPE 


String 


Boolean 


String 


String 


DateTime 


Int6o4 


String 


Int32 


String 


String 


Int32 


Int32 


DESCRIPTION 


The name of the computer on which 
the package is running. 


Indicates whether the package is in 
offline mode. Offline mode does not 
acquire connections to data sources. 


The unique identifier of the package. 


The name of the package. 


The time that the package started to 
run. 


Execution ID for the package that is 
executed on the Integration Services 
server. 


The default value is zero. The value is 
changed only if the package is 
executed by ISServerExec on the 
Integration Services Server. When 
there is a child package, the value is 
passed from the parent package to 
child package. 


The account of the user who started 
the package. The user name is qualified 
by the domain name. 


The package version. 


Comments about the package version. 


The unique identifier of the version. 


The major version of the package. 


The minor version of the package. 


The following table describes the system variables that Integration Services provides for the For Loop, Foreach 


Loop, and Sequence containers. 


SYSTEM VARIABLE 


Localeld Int32 


DATA TYPE 


DESCRIPTION 


The locale that the 
container uses. 


CONTAINER 


For Loop container 
Foreach Loop container 


Sequence container 


System Variables for Tasks 


The following table describes the system variables that Integration Services provides for tasks. 


SYSTEM VARIABLE DATA TYPE DESCRIPTION 

CreationName String The name of the task. 

Localeld Int32 The locale that the task uses. 

TaskID String The unique identifier of a task instance. 
TaskName String The name of the task instance. 
TaskTransactionOption Int32 The transaction option that the task 


uses. 


System Variables for Event Handlers 


The following table describes the system variables that Integration Services provides for event handlers. Not all 
variables are available to all event handlers. 


SYSTEM VARIABLE DATA TYPE DESCRIPTION EVENT HANDLER 
Cancel Boolean Indicates whether the event OnError event handler 
handler stops running when 
an error, warning, or query OnWarning event handler 
cancellation occurs. 
OnQueryCancel event 
handler 
ErrorCode Int32 The error identifier. OnError event handler 
OnInformation event 
handler 
OnWarning event handler 
ErrorDescription String The description of the error. OnError event handler 
OnInformation event 
handler 
OnWarning event handler 
ExecutionStatus Boolean The current execution OnExecStatusChanged 
status. event handler 
ExecutionValue DBNull The execution value. OnTaskFailed event handler 
Localeld Int32 The locale that the event All event handlers 
handler uses. 
PercentComplete Int32 The percentage of OnProgress event handler 


completed work. 


SYSTEM VARIABLE 


ProgressCountHigh 


ProgressCountLow 


ProgressDescription 


Propagate 


SourceDescription 


SourcelD 


SourceName 


VariableDescription 


VariablelD 


DATA TYPE 


Int32 


Int32 


String 


Boolean 


String 


String 


String 


String 


String 


DESCRIPTION 


The high part of a 64-bit 
value that indicates the 
total number of operations 
processed by the 
OnProgress event. 


The low part of a 64-bit 
value that indicates the 
total number of operations 
processed by the 
OnProgress event. 


Description of the progress. 


Indicates whether the event 
is propagated to a higher 
level event handler. 


Note: The value of the 
Propagate variable is 
disregarded during the 
validation of the package. If 
you set Propagate to 
False in a child package, 
this does not prevent an 
event from propagating up 
to the parent package. 


The description of the 
executable in the event 
handler that raised the 
event. 


The unique identifier of the 
executable in the event 
handler that raised the 
event. 


The name of the executable 
in the event handler that 
raised the event. 


The variable description. 


The unique identifier of the 
variable. 


System Variables in Parameter Bindings 


EVENT HANDLER 


OnProgress event handler 


OnProgress event handler 


OnProgress event handler 


All event handlers 


All event handlers 


All event handlers 


All event handlers 


OnVariableValueChanged 
event handler 


OnVariableValueChanged 
event handler 


It is frequently useful to save the values of system variables in tables when the package is run. For example, a 


package that dynamically creates a table and writes the GUID of the package execution instance that created the 


table in a table column. 


If you use system variables to map to parameters in the SQL statement that an Execute SQL task uses, it is 


important that you set the data type of each parameter binding to the data type of the system variable. 


Otherwise, the values of system variables may be translated incorrectly. For example, if the 
ExecutionInstanceGUID system variable, which has the string data type and contains a string that represents 
the GUID of the executing instance of a package, is used in a parameter binding with the GUID data type, the 
GUID of the package instance will be translated incorrectly. 


This rule applies to user-defined variables as well. But, whereas the data types of system variables cannot be 
changed and you have to tailor your use of these variables to fit the data types, user-defined are more flexible. 
The user-defined variables that are used in parameter bindings are usually defined with data types that are 
compatible with the data types of parameters to which they are mapped. 


Related Tasks 


Map Query Parameters to Variables in an Execute SQL Task 


Integration Services (SSIS) Expressions 
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An expression is a combination of symbols-identifiers, literals, functions, and operators-that yields a single data 
value. Simple expressions can be a single constant, variable, or function. More frequently, expressions are 
complex, using multiple operators and functions and referencing multiple columns and variables. In Integration 
Services, expressions can be used to define conditions for CASE statements, create and update values in data 
columns, assign values to variables, update or populate properties at run time, define constraints in precedence 
constraints, and provide the expressions used by the For Loop container. 


Expressions are based on an expression language, and the expression evaluator. The expression evaluator parses 
the expression and determines whether the expression follows the rules of the expression language. For more 
information about the expression syntax and supported literals and identifiers, see the following topics. 


e Syntax (SSIS) 
e Literals (SSIS) 


e Identifiers (SSIS) 


Components that Use Expressions 


The following elements in Integration Services can use expressions: 


e The Conditional Split transformation implements a decision structure based on expressions to direct data 
rows to different destinations. Expressions used in a Conditional Split transformation must evaluate to 
true or false. For example, rows that meet the condition in the expression "Column1 > Column2" can be 
routed to a separate output. 


e The Derived Column transformation uses values created by using expressions either to populate new 
columns in a data flow, or to update existing columns. For example, the expression Column1 + " ABC" can 
be used to update a value or to create a new value with the concatenated string. 


e Variables use an expression to set their value. For example, GETDATE() sets the value of the variable to the 
current date. 


e Precedence constraints can use expressions to specify the conditions that determine whether the 
constrained task or container in a package runs. Expressions used in a precedence constraint must 
evaluate to true or false. For example, the expression @A > @B compares two user-defined variables to 
determine whether the constrained task runs. 


e The For Loop container can use expressions to build the initialization, evaluation, and the incrementing 
statements that the looping structure uses. For example, the expression @Counter = 1 initializes the loop 
counter. 


Expressions can also be used to update the values of properties of packages, containers such as the For Loop 
and Foreach Loop, tasks, package and project level connection managers, log providers, and Foreach 
enumerators. For example, using a property expression, the string "LocalhostAdventureWorks" can be assigned 
to the ConnectionName property of the Execute SQL task. For more information, see Use Property Expressions 
in Packages. 


Icon Markers for Expressions 


In SQL Server Data Tools (SSDT), a special icon marker displays next to connection managers, variables, and 
tasks that have expressions set on them. The HasExpressions property is available on all SSIS objects that 
support expresions, with the exception of variables. The property enables you to easily identy which objects 
have expressions. 


Expression Builder 


The expression builder is a graphical tool for building expressions. It is available in the Conditional Split 
Transformation Editor, Derived Column Transformation Editor dialog boxes, and in the Expression 
Builder dialog box, is a graphical tool for building expressions. 


The expression builder provides folders that contain package-specific elements, and folders that contain the 
functions, type casts, and operators that the expression language provides. The package-specific elements 
include system variables and user-defined variables. In the Conditional Split Transformation Editor and 
Derived Column Transformation Editor dialog boxes, you can also view data columns. To build expressions 
for the transformations, you can drag items from the folders to the Condition or Expression column or you 
can type the expression directly in the column. The expression builder automatically adds needed syntax 


elements such as the @ prefix on variable names. 





NOTE 


The names of user-defined and system variables are case-sensitive. 





Variables have scope, and the Variables folder in the expression builder lists only variables that are in scope 
and available to use. For more information, see Integration Services (SSIS) Variables. 


Related Tasks 


Use an Expression in a Data Flow Component 


Related Content 


Technical article, SSIS Expression Examples, on social.technet.microsoft.com 


See Also 


SQL Server Integration Services 


Examples of Advanced Integration Services 


Expressions 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


This section provides examples of advanced expressions that combine multiple operators and functions. If an 
expression is used in a precedence constraint or the Conditional Split transformation, it must evaluate to a 
Boolean. That restriction, however, does not apply to expressions used in property expressions, variables, the 
Derived Column transformation, or the For Loop container. 


The following examples use the AdventureWorks and the AdventureWorksDW2012 Microsoft SQL Server 
databases. Each example identifies the tables it uses. 


Boolean Expressions 
e@ This example uses the Product table. The expression evaluates the month entry in the SellStartDate 


column and returns TRUE if the month is June or later. 


DATEPART("mm",SellStartDate) > 6 


@ This example uses the Product table. The expression evaluates the rounded result of dividing the 
ListPrice column by the StandardCost column, and returns TRUE if the result is greater than 1.5. 


ROUND(ListPrice / StandardCost,2) > 1.50 


e@ This example uses the Product table. The expression returns TRUE if all three operations evaluate to 
TRUE. If the Size column and the BikeSize variable have incompatible data types, the expression 
requires an explicit cast as shown the second example. The cast to DT_WSTR includes the length of the 
string. 


MakeFlag = 
MakeFlag = 


TRUE && FinishedGoodsFlag == TRUE && Size != @BikeSize 
TRUE && FinishedGoodsFlag == TRUE && Size != (DT_WSTR,10)@BikeSize 


e This example uses the CurrencyRate table. The expression compares values in tables and variables. It 
returns TRUE if entries in the FromCurrencyCode or ToCurrencyCode columns are equal to variable 
values and if the value in AverageRate is greater that the value in EndOfDayRate. 


(FromCurrencyCode == @FromCur || ToCurrencyCode == @ToCur) && AverageRate > EndOfDayRate 


e This example uses the Currency table. The expression returns TRUE if the first character in the Name 
column is nota or A. 


SUBSTRING(UPPER(Name),1,1) != "A" 


The following expression provides the same results, but it is more efficient because only one character is 
converted to uppercase. 


UPPER(SUBSTRING(Name,1,1)) != "A" 


Non-Boolean Expressions 


Non-Boolean expressions are used in the Derived Column transformation, property expressions, and the For 


Loop container. 


@ This example uses the Contact table. The expression removes leading and trailing spaces from the 
FirstName, MiddleName, and LastName columns. It extracts the first letter of the MiddleName 
column if it is not null, concatenates the middle initial and the values in FirstName and LastName, and 
inserts appropriate spaces between values. 


TRIM(FirstName) + " " + (!ISNULL(MiddleName) ? SUBSTRING(MiddleName,1,1) + " " : "") + TRIM(LastName) 
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e This example uses the Contact table. The expression validates entries in the Salutation column. It 
returns a Salutation entry or an empty string. 


(Salutation == "Sr." || Salutation == "Ms." || Salutation == "Sra." || Salutation == "Mr.") ? 


Salutation : "" 


e This example uses the Product table. The expression converts the first character in the Color column to 
uppercase and converts remaining characters to lowercase. 


UPPER(SUBSTRING(Color,1,1)) + LOWER(SUBSTRING(Color, 2,15)) 


e This example uses the Product table. The expression calculates the number of months a product has 
been sold and returns the string "Unknown" if either the SellStartDate or the SellEndDate column 
contains NULL. 


!(ISNULL(Sel1StartDate)) && !(ISNULL(SellEndDate)) ? 
(DT_WSTR, 2)DATEDIFF("mm",SellStartDate,SellEndDate) : "Unknown" 


e This example uses the Product table. The expression calculates the markup on the StandardCost 
column and rounds the result to a precision of two. The result is presented as a percentage. 


ROUND(ListPrice / StandardCost,2) * 100 


Related Tasks 


Use an Expression in a Data Flow Component 


Related Content 


Technical article, SSIS Expression Cheat Sheet, on pragmaticworks.com 


Use Property Expressions in Packages 
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A property expression is an expression that is assigned to a property to enable dynamic update of the property 
at run time. For example, a property expression can update the To line that a Send Mail task uses by inserting an 
e-mail address that is stored in a variable. 


An expression can be added to a package, task, Foreach Loop, For Loop, Sequence, Foreach enumerator, event 
handler, a package or project level connection manager, or log provider. Any property of these objects that is 
read/write can implement a property expression. Integration Services also supports the use of property 
expressions in some custom properties of data flow components. Variables and precedence constraints do not 
support property expressions, but they include special properties in which you can use expressions. 


Property expressions can be updated in different ways: 


e User-defined variables can be included in package configurations and then updated when the package is 
deployed. At run time, the property expression is evaluated using the updated variable value. 


e System variables that are included in expressions are updated at run time, which changes the results of 
the property evaluation. 


e Date and time functions are evaluated at run time and provide the updated values to property 
expressions. 


e Variables in expressions can be updated by the scripts that the Script task and the Script component run. 


The expressions are built using the Microsoft Integration Services expression language. The expressions can use 
system or user-defined variables, together with the operators, functions, and type casts that the expression 
language provides. 





NOTE 


The names of user-defined and system variables are case-sensitive. 





For more information, see Integration Services (SSIS) Expressions. 


An important use of property expressions is to customize configurations for each deployed instance of a 
package. This makes it possible to dynamically update package properties for different environments. For 
example, you can create a property expression that assigns a variable to the connection string of a connection 
manager, and then update the variable when the package is deployed, ensuring that the connection string is 
correct at run time. Package configurations are loaded before the property expressions are evaluated. 


A property can use only one property expression and a property expression can apply only to one property. 
However, you can build multiple identical property expressions and assign them to different properties. 


Some properties are set by using values from enumerators. When you reference the enumerator member in a 
property expression, you must use the numeric value that is equivalent to the friendly name of the enumerator 
member. For example, if a property expression sets the LoggingMode property, which uses a value from the 
DTSLoggingMode enumeration, the property expression must use 0, 1, or 2 instead of the friendly names 
Enabled, Disabled, or UseParentSetting. For more information, see Enumerated Constants in Property 
Expressions. 


Property Expression User Interface 
Integration Services provides a set of tools for building and managing property expressions. 


e The Expressions page, found in the custom editors for tasks, the For Loop container, and the Foreach 
containers. The Expressions page lets you edit expressions and view a list of the property expressions 
that a task, Foreach Loop, or For Loop uses. 


e The Properties window, for editing expressions and viewing a list of the property expressions that a 
package or package objects use. 


e The Property Expressions Editor dialog box, for creating, updating, and deleting property expressions. 


e The Expression Builder dialog box, for building an expression using graphical tools. The Expression 
Builder dialog box can evaluate expressions for your review without assigning the evaluation result to 
the property. 


The following diagram shows the user interfaces that you use to add, change, and remove property expressions. 
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In the Properties window and the Expressions page, click the browse button (...) at the Expressions 
collection level to open the Property Expressions Editor dialog box. The Property Expressions Editor allows 
you to map a property to an expression and to type a property expression. If you want to use the graphical 
expression tools to create and then validate the expression, click the browse button (...) at the expression level to 
open the Expression Builder dialog box, and then create or modify and optionally validate the expression. 


You can also open the Expression Builder dialog box from the Property Expressions Editor dialog box. 


To work with property expressions 


e Add or Change a Property Expression 


Setting Property Expressions of Data Flow Components 


If you construct a package in SQL Server Data Tools (SSDT), the properties of data flow components that 
support property expressions are exposed on the Data Flow task to which they belong. To add, change, and 
remove the property expressions of data flow components, you right-click the Data Flow task for the data flow 
to which the data flow components belong and click Properties. The Properties window lists the properties of 
data flow components with which you can use property expressions. For example, to create or modify a 
property expression for the SamplingValue property of a Row Sampling transformation in a data flow named 
SampleCustomer, right-click the Data Flow task for the data flow to which the Row Sampling transformation 


belongs and click Properties. The SamplingValue property is listed in the Properties window, and has the 


format [SampleCustomer].[SamplingValue]. 


In the Properties window, you add, change, and remove property expressions for data flow components in the 


same way as property expressions for other Integration Services object types. The Properties window also 


provides access to the various dialog boxes and builders that you use to add, change, or remove property 


expressions for data flow components. For more information about the properties of data flow components that 


can be updated by property expressions, see Transformation Custom Properties. 


Loading Property Expressions 


You cannot specify or control when property expressions are loaded. The property expressions are evaluated 


and loaded when the package and the package objects are validated. Validation occurs when you save the 


package, open the package in SSIS Designer, and run the package. 


You will therefore not see the updated values of the properties of the package objects that use property 


expressions in SSIS Designer until you save the package, run the package, or reopen the package after adding 


the property expressions. 


The property expressions associated with different types of objects-connection managers, log providers, and 


enumerators-are also loaded when methods specific to that object type are called. For example, the properties 


of connection managers are loaded before Integration Services creates an instance of the connection. 


Property expressions are loaded after package configurations have loaded. For example, variables are updated 


first by their configurations, and then the property expressions that use the variables are evaluated and loaded. 


This means that the property expressions always use the values of variables that are set by configurations. 





NOTE 


You cannot use the Set option of the dtexec utility to populate a property expression. 





The following table summarizes when property expressions of Integration Services are evaluated and loaded. 


OBJECT TYPE 


Package, Foreach loop, For Loop, Sequence, tasks, and data 
flow components 


Connection managers 


Log providers 


LOAD AND EVALUATE 


After loading configurations 
Before validation 


Before execution 


After loading configurations 
Before validation 
Before execution 


Before creating a connection instance 


After loading configurations 
Before validation 
Before execution 


Before opening logs 


OBJECT TYPE LOAD AND EVALUATE 


Foreach enumerators After loading configurations 
Before validation 
Before execution 


Before each enumeration of the loop 


Using Property Expressions in the Foreach Loop 


It is frequently useful to implement a property expression to set the value of the ConnectionString property of 
connection managers that are used inside the Foreach Loop container. After the enumerator maps its current 
value to a variable on each iteration of the loop, the property expression can use the value of this variable to 


update the value of the ConnectionString property dynamically . 


If you want to use property expressions with the ConnectionString property of File, Multiple Files, Flat Files, 
and Multiple Flat Files connection managers that a Foreach Loop uses, there are some things that you should 
consider. A package can be configured to run multiple executables concurrently by setting the 
MaxConcurrentExecutables property either to a value greater than 1 or to the value -1. A value of -1 allows 
the maximum number of concurrently running executables to equal the number of processors plus two. To 
avoid negative consequences from the parallel execution of executables, the value 
MaxConcurrentExecutables should be set to 1. If MaxConcurrentExecutables is not set to 1, then the value 
of the ConnectionString property cannot be guaranteed and results are unpredictable. 


For example, consider a Foreach Loop that enumerates files in a folder, retrieves the file names, and then uses an 
Execute SQL task to insert each file name into a table. lf MaxConcurrentExecutables is not set to 1, then write 


conflicts could occur if two instances of the Execute SQL task attempted to write to the table at the same time. 


Sample Property Expressions 


The following sample expressions show how to use system variables, operators, functions, and string literals in 


property expressions. 


Property Expression for the LoggingMode Property of a Package 

The following property expression can be used to set the LoggingMode property of a package. The expression 
uses the DAY and GETDATE functions to get an integer that represents the day datepart of a date. If the day is the 
1st or 15th, logging is enabled; otherwise, logging is disabled. The value 1 is the integer equivalent of the 
LoggingMode enumerator member Enabled, and the value 2 is the integer equivalent of the member 
Disabled. You must use the numeric value instead of the enumerator member name in the expression. 


DAY ( (DT_DBTIMESTAMP ) GETDATE() )==1| |DAY( (DT_DBTIMESTAMP)GETDATE() )==15?1:2 


Property Expression for the Subject of an E-mail Message 

The following property expression can be used to set the Subject property of a Send Mail task and provide a 
useful e-mail subject. The expression uses a combination of string literals, system variables, the concatenation 
(+) and cast operators, and the DATEDIFF and GETDATE functions. The system variables are the PackageName and 
StartTime variables. 


"PExpression-->Package: (" + @[System::PackageName] + ") Started:"+ (DT_WSTR, 30) @[System::StartTime] + " 
Duration:" + (DT_WSTR,1@) (DATEDIFF( "ss", @[System::StartTime] , GETDATE() )) + " seconds" 


If the package name is EmailRowCountPP was run on 3/4/2005, and the duration of the run was 9 seconds, the 


expression evaluates to the following string. 


PExpression--> Package: (EmailRowCountPP) Started:3/4/2005 11:06:18 AM Duration:9 seconds. 


Property Expression for the Message of an E-mail Message 


The following property expression can be used to set the MessageSource property of a Send Mail task. The 
expression uses a combination of string literals, user-defined variables, and the concatenation (+) operator. The 
user-defined variables are named nasdaqrawrows , nyserawrows , aNd amexrawrows . The string "\n" indicates a 


carriage return. 


"Rows Processed: " + "\n" +" NASDAQ: " + (dt_wstr,9)@[nasdaqrawrows] + "\n" + " NYSE: " + 
(dt_wstr,9)@[nyserawrows] + "\n" + " Amex: " + (dt_wstr,9)@[amexrawrows ] 


If nasdaqrawrows is 7058, nyserawrows is 3528,and amexrawrows is 1102, the expression evaluates to the 


following string. 
Rows Processed: 
NASDAQ: 7058 
NYSE: 3528 
AMEX: 1102 


Property Expression for the Executable Property of an Execute Process Task 


The following property expression can be used to set the Executable property of an Execute Process task. The 
expression uses a combination of string literals, operators, and functions. The expression uses the DATEPART and 
GETDATE functions and the conditional operator. 


DATEPART("weekday", GETDATE()) ==2?"notepad.exe":"mspaint.exe" 


If it is the second day in the week, the Execute Process task runs notepad.exe, otherwise the task runs 
mspaint.exe. 


Property Expression for the ConnectionString Property of a Flat File Connection Manager 


The following property expression can be used to set the ConnectionString property of a Flat File connection 
manager. The expression uses a single user-defined variable, myfilenamefull , which contains the path to a text 
file. 


@[User: :myfilenamefull] 





NOTE 
Property expressions for connection managers can be accessed only by using the Properties window. To view the 
properties for a connection manager, you must select the connection manager in the Connection Managers area of 


SSIS Designer when the Properties window is open, or right-click the connection manager and select Properties. 





Property Expression for the ConfigString Property of a Text File Log Provider 


The following property expression can be used to set the ConfigString property of a Text File log provider. The 
expression uses a single user-defined variable, varconfigstring , which contains the name of the File connection 


manager to use. The File connection manager specifies the path of the text file to which log entries are written. 


@[User: :varConfigString ] 








NOTE 
Property expressions for log providers can be accessed only by using the Properties window. To view the properties of a 
log provider, you must select the log provider on the Package Explorer tab of SSIS Designer when the Properties 


window is open, or right-click the log provider in Package Explorer and click Properties. 








External Resources 


e Technical article, SSIS Expression Examples, on social.technet.microsoft.com 


See Also 


Use Variables in Packages 


Enumerated Constants in Property Expressions 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


If property expressions include values from an enumerator member list, the expression must use the numeric 
value of the enumerator member instead of the friendly name of the member. For example, if an expression sets 
the LoggingMode property then you must use the numeric value 2 instead of the friendly name Disabled. 


This topic lists only the numeric values equivalent to friendly names of enumerators whose members are 
commonly used in property expressions. The Integration Services object model includes many additional 
enumerators that you use when you program the object model to build packages programmatically or code 
custom package elements such as tasks and data flow components. 


In addition to the custom properties for packages and package objects, the Properties window in SQL Server 
Data Tools (SSDT) includes a set of properties that are available to packages, tasks, and the Foreach Loop, For 
Loop, and Sequence containers. The common properties that are set by values from 
enumerators-ForceExecutionResult, LoggingMode, IsolationLevel, and Transaction Option-are listed in 
Common Properties section. 


The following sections provide information about enumerated constants: 
Package 

Foreach Loop Enumerators 

Tasks 

Maintenance Plan Tasks 


Common Properties 


Package 


The following tables lists the friendly names and the numeric value equivalents for properties of packages that 


you set by using values from an enumerator. 


PackageType property-Set by using values from the DTS PackageType enumeration. 


FRIENDLY NAME IN DTSPACKAGETYPE NUMERIC VALUE 
Default 0 
DTSWizard 1 
DTSDesigner 2 
SQLReplication 3 
DTSDesigner100 5 


SQLDBMaint 6 


CheckpointUsage property-Set by using values from the DTSCheckpointUsage enumeration. 


FRIENDLY NAME IN DTSCHECKPOINTUSAGE NUMERIC VALUE 
Never 0 
IfExists 1 
Always 2 


PackagePriorityClass property-Set by using values from the DTSPriorityClass enumeration. 


FRIENDLY NAME IN DTSPRIORITYCLASS NUMERIC VALUE 
Default 0 
AboveNormal 1 
Normal 2 
BelowNormal 3 
Idle 4 


ProtectionLevel property-Set by using values from the DTSProtectionLevel enumeration. 


FRIENDLY NAME IN DTSPROTECTIONLEVEL NUMERIC VALUE 
DontSaveSensitive 0 
EncryptSensitiveWithUserKey 1 
EncryptSensitiveWithPassword 2 
EncryptAllWithPassword 3 
EncryptAllWithUserKey 4 
ServerStorage 5 


Precedence Constraints 


EvalOp property-Set by using values from the DTSPrecedenceEvalOp enumeration. 


FRIENDLY NAME IN DTSPRECEDENCEEVALOP NUMERIC VALUE 
Expression 1 
Constraint 2 
ExpressionAndConstraint 3 


ExpressionOrConstraint 4 


FRIENDLY NAME IN DTSPRECEDENCEEVALOP NUMERIC VALUE 


Value property-Set by using values from the DTSExecResult enumeration. 


FRIENDLY NAME NUMERIC VALUE 
Success 0 
Failure 1 
Completion 2 
Canceled 3 


Foreach Loop Enumerators 


The Foreach Loop includes a set of enumerators with properties that can be set by property expressions. 


Foreach ADO Enumerator 


Type property-Set by using values from the ADOEnumerationType enumeration. 


FRIENDLY NAME IN ADOENUMERATIONTYPE NUMERIC VALUE 
EnumerateTables 0 
EnumerateAllRows 1 
EnumerateRows!nFirstTable 2 


Foreach Nodelist Enumerator 
SourceDocumenttType, InnerXPathStringSourceType, and OuterXPathStringSourceType properties-Set 


by using values from the SourceType enumeration. 


FRIENDLY NAME IN SOURCETYPE NUMERIC VALUE 
FileConnection 0 
Variable 1 
DirectInput 2 


EnumerationType property-Set by using values from the EnumerationType enumeration. 


FRIENDLY NAME IN ENUMERATIONTYPE NUMERIC VALUE 
Navigator 0 
Node 1 


NodeText 2 


FRIENDLY NAME IN ENUMERATIONTYPE NUMERIC VALUE 


ElementCollection 3 


InnerElementType property-Set by using values from the InnerElementType enumeration. 


FRIENDLY NAME IN INNERELEMENTTYPE NUMERIC VALUE 
Navigator 0 
Node 1 
NodeText 2 


Tasks 


Integration Services includes numerous tasks with properties that can be set by property expressions. 


Analysis Services Execute DDL Task 


SourceType property-Set by using values from the DDLSourceType enumeration. 


FRIENDLY NAME IN DDLSOURCETYPE NUMERIC VALUE 
DirectInput 0 
FileConnection 1 
Variable 2 


Bulk Insert Task 
DataFileType property-Set by using values from the DTSBulkInsert_DataFileType enumeration. 


FRIENDLY NAME IN DTSBULKINSERT_DATAFILETYPE NUMERIC VALUE 
DTSBulklnsert_DataFileType_Char 0 
DTSBulklnsert_DataFileType_Native 1 
DTSBulklnsert_DataFileType_WideChar 2 
DTSBulkInsert_DataFileType_WideNative 3 


Execute SQL Task 


ResultSetType property-Set by using values from the ResultSetType enumeration. 


FRIENDLY NAME IN RESULTSETTYPE NUMERIC VALUE 
ResultSetType_None 1 
ResultSetType_SingleRow 2 


ResultSetType_Rowset 3 


FRIENDLY NAME IN RESULTSETTYPE NUMERIC VALUE 


ResultSetType_XML 4 


SqlStatementSourceType property-Set by using values from the SqIStatementSourceType enumeration. 


FRIENDLY NAME IN SQLSTATEMENTSOURCETYPE NUMERIC VALUE 
DirectInput 1 
FileConnection 2 
Variable 3 


File System Task 


Operation property-Set by using values from the DTSFileSystemOperation enumeration. 


FRIENDLY NAME IN DTSFILESYSTEMOPERATION NUMERIC VALUE 
CopyFile 0 
MoveFile 1 
DeleteFile 2 
RenameFile 3 
SetAttributes 4 
CreateDirectory 5 
CopyDirectory 6 
MoveDirectory if 
DeleteDirectory 8 
DeleteDirectoryContent 9 


Attributes property-Set by using values from the DTSFileSystemAttributes enumeration. 


FRIENDLY NAME IN DTSFILESYSTEMATTRIBUTES NUMERIC VALUE 
Normal 0 
Archive 1 
Hidden 2 
ReadOnly 4 


System 8 


FTP Task 
Operation property-Set by using values from the DISFTPOp enumeration. 


FRIENDLY NAME IN DTSFTPOP NUMERIC VALUE 
Send 0 
Receive 1 
DeleteLocal 2 
DeleteRemote 3 
MakeDirLocal 4 
MakeDirRemote 5 
RemoveDirLocal 6 
RemoveDirRemote 7 


Message Queue Task 


MessageType property-Set by using values from the MQMessageType enumeration. 


FRIENDLY NAME IN MQMESSAGETYPE NUMERIC VALUE 
DTSMQMéessageType_String 0 
DTSMQMessageType_DataFile 1 
DTSMQMessageType_Variables 2 
DTSMQMessagType_StringMessageToVariable 3 


StringCompareType property-Set by using values from the MQStringMessageCompare enumeration. 


FRIENDLY NAME IN MQSTRINGMESSAGEC OM PARE NUMERIC VALUE 
DTSMQStringMessageCompare_None 0 
DTSMQStringMessageCompare_Exact 1 
DTSMQStringMessageCompare_IgnoreCase 2 
DTSMQStringMessageCompare_Contains 3 


TaskType property-Set by using values from the MQType enumeration. 
FRIENDLY NAME IN MQTYPE NUMERIC VALUE 


DTSMQType_Sender 0 


FRIENDLY NAME IN MQTYPE NUMERIC VALUE 


DTSMQType_Receiver 1 


Send Mail Task 


MessageSourceType property-Set by using values from the SendMailMessageSourceType enumeration. 


FRIENDLY NAME IN SENDMAILMESSAGESOURCETYPE NUMERIC VALUE 
DirectInput 0 
FileConnection 1 
Variable 2 


Priority property-Set by using values from the MailPriority enumeration. 


FRIENDLY NAME IN MAILPRIORITY NUMERIC VALUE 
High 1 
Normal 3 
Low 5 


Transfer Database Task 


Action property-Set by using values from the TransferAction enumeration. 


FRIENDLY NAME IN TRANSFERACTION NUMERIC VALUE 
Copy 0 
Move 1 


Method property-Set by using values from the TransferMethod enumeration. 


FRIENDLY NAME IN TRANSFERMETHOD NUMERIC VALUE 
DatabaseOffline 0 
DatabaseOnline 1 


Transfer Error Messages Task 


IfObjectExists property-Set by using values from the IfObjectExists enumeration. 


FRIENDLY NAME IN IFOBJECTEXISTS NUMERIC VALUE 
FailTask 0 
Overwrite 1 


Skip 2 


Transfer Jobs Task 


IfObjectExists property-Set by using values from the IfObjectExists enumeration. 


FRIENDLY NAME IN IFOBJECTEXISTS NUMERIC VALUE 
FailTask 0 
Overwrite 1 
Skip 2 


Transfer Logins Task 


IfObjectExists property-Set by using values from the IfObjectExists enumeration. 


FRIENDLY NAME IN IFOBJECTEXISTS NUMERIC VALUE 
FailTask 0 
Overwrite 1 
Skip 2 


LoginsToTransfer property-Set by using values from the LoginsToTransfer enumeration. 


FRIENDLY NAME IN LOGINSTOTRANSFER NUMERIC VALUE 
AllLogins 0 
SelectedLogins 1 
AllLoginsFromSelectedDatabases 2 


Transfer Master Stored Procedures Task 


IfObjectExists property-Set by using values from the lfObjectExists enumeration. 


FRIENDLY NAME IN IFOBJECTEXISTS NUMERIC VALUE 
FailTask 0 
Overwrite 1 
Skip 2 


Transfer SQL Server Objects Task 


ExistingData property-Set by using values from the ExistingData enumeration. 
FRIENDLY NAME IN EXISTINGDATA NUMERIC VALUE 


Replace 0 


Append 1 


Web Service Task 
OutputType property-Set by using values from the DTSOutputType enumeration. 


FRIENDLY NAME IN DTSOUTPUTTYPE NUMERIC VALUE 
File 0 
Variable 1 


WMI Data Reader Task 


OverwriteDestination property-Set by using values from the OverwriteDestination enumeration. 


FRIENDLY NAME IN OVERWRITEDESTINATION NUMERIC VALUE 
OverwriteDestination 0 
AppendtToDestination 1 
KeepOriginal 2 


OutputType property-Set by using values from the OutputType enumeration. 


FRIENDLY NAME IN OUTPUTTYPE NUMERIC VALUE 
DataTable 0 
PropertyValue 1 
PropertyNameAndValue 2 


DestinationType property-Set by using values from the DestinationType enumeration. 


FRIENDLY NAME IN DESTINATIONTYPE NUMERIC VALUE 
FileConnection 0 
Variable 1 


WqlQuerySourceType property-Set by using values from the QuerySourceType enumeration. 


FRIENDLY NAME IN QUERYSOURCETYPE NUMERIC VALUE 
FileConnection 0 
DirectInput 1 
Variable 2 


WMI Event Watcher ActionAtEvent property-Set by using values from the ActionAtEvent enumeration. 


FRIENDLY NAME IN ACTIONATEVENT NUMERIC VALUE 


LogTheEventAndFireDTSEvent 0 


FRIENDLY NAME IN ACTIONATEVENT NUMERIC VALUE 


LogTheEvent 1 


ActionAtTimeout property-Set by using values from the ActionAtTimeout enumeration. 


FRIENDLY NAME IN ACTIONATTIMEOUT NUMERIC VALUE 
LogTimeoutAndFireDTSEvent 0 
LogTimeout 1 


AfterEvent property-Set by using values from the AfterEvent enumeration. 


FRIENDLY NAME IN AFTEREVENT NUMERIC VALUE 
ReturnWithSuccess 0 
ReturnWithFailure 1 
WatchfortheEventAgain 2 


AfterTimeout property-Set by using values from the AfterTimeout enumeration. 


FRIENDLY NAME IN AFTERTIMEOUT NUMERIC VALUE 
ReturnWithSuccess 0 
ReturnWithFailure 1 
WatchfortheEventAgain 2 


WaqlQuerySourceType property-Set by using values from the QuerySourceType enumeration. 


FRIENDLY NAME IN QUERYSOURCETYPE NUMERIC VALUE 
FileConnection 0 
DirectInput 1 
Variable 2 
XML Task 


OperationType property-Set by using values from the DTSXMLOperation enumeration. 


FRIENDLY NAME IN DTSXMLOPERATION NUMERIC VALUE 
Validate 0 
XSLT 1 


XPATH 2 


FRIENDLY NAME IN DTSXMLOPERATION NUMERIC VALUE 


Merge 3 
Diff 4 
Patch 5 


SourceType, SecondOperandType, and XPathSourceType properties-Set by using values from the 
DTSXMLSourceType enumeration. 


FRIENDLY NAME IN DTSXMLSOURCETYPE NUMERIC VALUE 
FileConnection 0 
Variable 1 
DirectInput 2 


DestinationType and DiffGramDestinationType properties-Set by using values from the 
DTSXMLSaveResultTo enumeration. 


FRIENDLY NAME IN DTSXMLSAVERESULTTO NUMERIC VALUE 
FileConnection 0 
Variable 1 


ValidationType property-Set by using values from the DTSXMLValidationType enumeration. 


FRIENDLY NAME IN DTSXMLVALIDATIONTYPE NUMERIC VALUE 
DTD 0 
XSD 1 


XPathOperation property-Set by using values from the DTSXMLXPathOperation enumeration. 


FRIENDLY NAME IN DTSXMLXPATHOPERATION NUMERIC VALUE 
Evaluation 0 
Values 1 
NodeList 2 


DiffOptions property-Set by using values from the DTISXMLDiffOptions enumeration. The options in this 
enumerator are not mutually exclusive. To use multiple options, provide a comma-separated list of the options 
to apply. 


FRIENDLY NAME IN DTSXMLDIFFOPTIONS NUMERIC VALUE 


None 0 


FRIENDLY NAME IN DTSXMLDIFFOPTIONS NUMERIC VALUE 


IgnoreChildOrder 1 
IgnoreComments 2 
IgnorePl 4 
IgnoreWhitespace 8 
IgnoreNamespaces 16 
IgnorePrefixes 32 
IgnoreXmlDecl 64 
IgnoreDtd 128 


DiffAlgorithm property-Set by using values from the DTSXMLDiffAlgorithm enumeration. 


FRIENDLY NAME IN DTSXMLDIFFALGORITHM NUMERIC VALUE 
Auto 0 
Fast 1 
Precise 2 


Maintenance Plan Tasks 


Integration Services includes a set of tasks that perform SQL Server tasks for use in maintenance plans and 


Integration Services packages. 


SQL Server does not support working with these tasks programmatically and programming reference 


documentation does not include API documentation of these tasks and their enumerators. 


All Maintenance Tasks 


All maintenance tasks use the following enumerations to set the specified properties. 


DatabaseSelectionType property-Set by using values from the DatabaseSelection enumeration. 


FRIENDLY NAME IN DATABASESELECTION NUMERIC VALUE 
None 0 
All 1 
System 2 
User 3 
Specific 4 


TableSelectionType property-Set by using values from the TableSelection enumeration. 


FRIENDLY NAME IN TABLESELECTION NUMERIC VALUE 


None 0 
All 1 
Specific 2 


ObjectTypeSelection property-Set by using values from the ObjectType enumeration. 


FRIENDLY NAME IN OBJECTTYPE NUMERIC VALUE 
Table 0 
View 1 
TableView 2 


Back Up Database Task 


DestinationCreationType property-Set by using values from the DestinationType enumeration. 


FRIENDLY NAME IN DESTINATIONTYPE NUMERIC VALUE 
Auto 0 
Manual 1 


ExistingBackupsAction property-Set by using values from the ActionForExistingBackups enumeration. 


FRIENDLY NAME IN ACTIONFOREXISTINGBACKUPS NUMERIC VALUE 
Append 0 
Overwrite 1 


BackupAction property-Set by using values from the BackupTaskType enumeration. This property works 
with the BackuplsIncremental property to define the type of backup that the task performs. 


FRIENDLY NAME IN BACKUPTASKTYPE NUMERIC VALUE 
Database 0 
Files 1 
Log 2 


BackupDevice property-Set by using values from the SQL Server Management Objects (SMO) DeviceType 
enumeration. 


FRIENDLY NAME IN DEVICETYPE NUMERIC VALUE 


LogicalDevice 0 


FRIENDLY NAME IN DEVICETYPE NUMERIC VALUE 


Tape 1 
File 2 
Pipe 3 
VirtualDevice 4 


Maintenance Cleanup Task 


FileTypeSelected property-Set by using values from the FileType enumeration. 


FRIENDLY NAME IN FILETYPE NUMERIC VALUE 
FileBackup 0 
FileReport 1 


OlderThanTimeUnitType property-Set by using values from the TimeUnitType enumeration. 


FRIENDLY NAME IN TIMEUNITTYPE NUMERIC VALUE 
Day 0 
Week 1 
Month 2 
Year 3 


Update Statistics Task 
UpdateType property-Set by using values from the SQL Server Management Objects (SMO) StatisticsTarget 


enumeration. 


FRIENDLY NAME IN STATISTICSTARGET NUMERIC VALUE 
Column 1 
Index 2 
All 3 


Common Properties 


Packages, tasks, and the Foreach Loop, For Loop, and Sequence containers can use the following enumerations 
to set the specified properties. 


ForceExecutionResult property-Set by using values from the DTSForcedExecResult enumeration. 


FRIENDLY NAME IN DTSFORCEDEXECRESULT NUMERIC VALUE 


None =] 
Success 0 
Failure 1 
Completion 2 


IsolationLevel property-Set by the .NET Framework IsolationLevel enumeration. For more information, see 
the .NET Framework Class Library in the MSDN Library. 


LoggingMode property-Set by using values from the DTSLoggingMode enumeration. 


FRIENDLY NAME IN DTSLOGGINGMODE NUMERIC VALUE 
UseParentSetting 0 
Enabled 1 
Disabled 2 


TransactionOption property-Set by using values from the DTSTransactionOption enumeration. 


FRIENDLY NAME IN DTSTRANSACTIONOPTION NUMERIC VALUE 
NotSupported 0 
Supported 1 
Required 2 


Related Tasks 


Add or Change a Property Expression 


See Also 


Use Property Expressions in Packages 
Integration Services (SSIS) Packages 
Integration Services Containers 
Integration Services Tasks 
Precedence Constraints 


Add or Change a Property Expression 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


You can create property expressions for packages, tasks, Foreach Loop containers, For Loop containers, 
Sequence containers, event handlers, package and project level connection managers, and log providers. 


To create or change property expressions, you can use either the Property Expressions Editor or Expression 
Builder. The Property Expressions Editor can be accessed from either the custom editors that are available 
for tasks and containers, or from the Properties window. Expression Builder can be accessed from inside the 
Property Expressions Editor. While you can write expressions in either the Property Expressions Editor or 
Expression Builder, Expression Builder provides a graphical set of tools that makes it simple to build 
complex expressions. 


To learn more about the syntax, operators, and functions that Integration Services provides, see Operators (SSIS 
Expression) and Functions (SSIS Expression). The topic for each operator or function includes examples of using 
that operator or function in an expression. For examples of more complex expressions, see Use Property 
Expressions in Packages. 


To create or change a property expression 


1. In SQL Server Data Tools (SSDT), open the project that contains the Integration Services package you 
want. 


2. In Solution Explorer, double-click the package to open it, and then do one of the following: 
e Ifthe item is a task or a container, double-click the item, and then click Expressions in the editor. 
e@ Right-click the item and then click Properties. 

3. Click in the Expressions box and then click the ellipsis (...). 


4. Inthe Property Expressions Editor, select a property in the Property list, and then do one of the 
following: 


e Type or change the property expression directly in the Expression column, and then click OK. 
-or- 
e Click the ellipsis (...) in the expression row of the property to open the Expression Builder. 
5. (Optional) In the Expression Builder, do any of the following tasks: 
@ To access system and user-defined variables, expand Variables. 


e To access the functions, the casts, and the operators that the SSIS expression language provides, 
expand Mathematical Functions, String Functions, Date/Time Functions, NULL Functions, 
Type Casts, and Operators. 


@ To build or change an expression in the Expression Builder, drag variables, columns, functions, 
operators, and casts to the Expression box, or type the expression in the box. 


e To view the evaluation result of the expression, click Evaluate Expression in the Expression 
Builder. 


If the expression is not valid, an alert appears that describes the syntax errors in the expression. 





NOTE 


Evaluating an expression does not assign the evaluation result to the property. 





6. Click OK. 


See Also 


Integration Services (SSIS) Expressions 
Use Property Expressions in Packages 
Integration Services (SSIS) Packages 
Integration Services Containers 
Integration Services Tasks 

Integration Services (SSIS) Event Handlers 
Integration Services (SSIS) Connections 


Integration Services (SSIS) Logging 


Expressions Page 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Use the Expressions page to edit property expressions and to access the Property Expressions Editor and 
Property Expression Builder dialog boxes. 


Property expressions update the values of properties when the package is run. Property expressions can be 
used with the properties of packages, tasks, containers, connection managers, as well as some data flow 
components. The expressions are evaluated and their results are used instead of the values to which you set the 
properties when you configured the package and package objects. The expressions can include variables and the 
functions and operators that the expression language provides. For example, you can generate the subject line 
for the Send Mail task by concatenating the value of a variable that contains the string "Weather forecast for " 
and the return results of the GETDATE() function to make the string "Weather forecast for 4/5/2006". 


To learn more about writing expressions and using property expressions, see Integration Services (SSIS) 
Expressions and Use Property Expressions in Packages. 


Options 


Expressions (...) 
Click the ellipsis to open the Property Expressions Editor dialog box. For more information, see Property 
Expressions Editor. 


<property name> 
Click the ellipsis to open the Expression Builder dialog box. For more information, see Expression Builder. 


See Also 


Integration Services (SSIS) Variables 
System Variables 
Integration Services (SSIS) Expressions 


Property Expressions Editor 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Use the Property Expressions Editor dialog box to create, edit, or delete the property expressions that update 
property values. 


Options 


Property 
Select an object property from the list. 


Expression 


Type a literal or an expression to update the value of the property. 





NOTE 


The names of user-defined and system variables are case-sensitive. 





Expression (...) 
Click the ellipsis to open the Expression Builder dialog box. For more information, see Expression Builder. 


Delete 
Select a property, and then click Delete. 


See Also 


Expressions Page 

Integration Services (SSIS) Variables 
System Variables 

Integration Services (SSIS) Expressions 


Use Property Expressions in Packages 


Expression Builder 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Use the Expression Builder dialog box to create and edit a property expression or write the expression that 
sets the value of a variable using a graphical user interface that lists variables and provides a built-in reference 
to the functions, type casts, and operators that the Integration Services expression language includes. 


A property expression is an expression that is assigned to a property. When the expression is evaluated, the 
property is dynamically updated to use the evaluation result of the expression. Likewise, an expression that is 
used in a variable enables the variable value to be updated with the evaluation result of the expression. 


There are many ways to use expressions: 


e Tasks Update the To line that a Send Mail task uses by inserting an e-mail address that is stored ina 
variable; or update the Subject line by concatenating a string such as "Sales for: " and the current date 
returned by the GETDATE function. 


e Variables Set the value of a variable to the current month by using an expression like 
DATEPART("mm",GETDATE()) ; or set the value of a string by concatenating the string literal and the current 
date by using the expression "Today's date is " + (DT_WSTR,3)(GETDATE()) . 


e Connection Managers Set the code page of a Flat File connection manager by using a variable that 
contains a different code page identifier; or specify the number of rows in the data file to skip by entering 
a positive integer like 3 in the expression. 


To learn more about property expressions and writing expressions, see Use Property Expressions in Packages 
and Integration Services (SSIS) Expressions. 


Options 
TERM DEFINITION 


Variables Expand the Variables folder and drag variables to the 
Expression box. 


Mathematical Functions Expand the folders and drag functions, type casts, and 
operators to the Expression box. 

String Functions 

Date/Time Functions 

NULL Functions 


Type Casts 


Operators 
Expression Edit or type an expression. 


Evaluated value Lists the evaluation result of the expression. 


TERM DEFINITION 


Evaluate Expression Click Evaluate Expression to view the evaluation result of 
the expression. 


See Also 


Expressions Page 

Property Expressions Editor 
Integration Services (SSIS) Variables 
System Variables 


Integration Services Data Types in Expressions 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


The expression evaluator uses Integration Services data types. When data first enters a data flow in an 
Integration Services package, the data flow engine converts all column data to an Integration Services data type, 
and the column data that an expression uses already has an Integration Services data type. Expressions used in 
the Conditional Split and the Derived Column transformations can reference columns because they are part of a 
data flow that includes column data. 


Variables 


Expressions can also use variables. Variables have a Variant data type and the expression evaluator converts the 
data type of a variable from a Variant subtype to an Integration Services data type before it evaluates the 
expression. Variables can use only a subset of the Integration Services data types. For example, a variable cannot 
use a Binary Large Object Block (BLOB) data type. 


For more information about Integration Services data types and the mapping of Variant data types to 
Integration Services data types, see Integration Services Data Types. 


Literals 


In addition, expressions can include string, Boolean, and numeric literals. For more information about converting 
numeric literals to numeric Integration Services data types, see Literals (SSIS). 


Strings 


You can use either DT_STR or DT_WSTR as the return type of an expression. Inside an expression, however, only 
DT_WSTR is supported, and DT_STR values are converted to DT_WSTR values. This behavior has several 
implications when you're writing an expression. 


e Inside an expression, use NULL(DT_WSTR., ...) instead of NULL(DT_STR, ...). For more info about this 
function, see NULL (SSIS Expression). 


e Inside an expression, you can only use the CAST function to cast a value to the DT_STR type at the root of 
the expression - that is, when you are returning the final result of the expression. Otherwise, use the 
DT_WSTR type within in expression. 


Consider the expressions in the following screen shot. 
Expression 
NULL(DT_STR, 32,1252) 
([b]=="1")?NULL(DT_WSTR, 1252):"str" 
([b]=="1")?NULL(DT_STR, 32, 1252):"str" 
([b]=="1")?(DT_STR,32,1252)NULL(DT_STR, 32, 1252):"str" 





1. The first expression runs without error because the NULL(DT_STR, ...) function is at the root level of the 
expression. 


2. The second expression runs without error because it uses NULL(DT_WSTR  ...). 


3. The third expression raises an error because it uses NULL(DT_STR, ...) inside the expression. 


4. The fourth expression runs without error because it casts the result of NULL(DT_STR, ...) inside the 


expression. 


The expression evaluator handles this cast intelligently and casts to DI_WSTR, not to DT_STR, because it 
recognizes that the operation is not at the root level of the expression. 


The following examples demonstrate the effects of casting. 





Expression Data Type 
([b] == "1")?(DT_STR, 32, 1252)NULL(DT_STR, 32, 1252):(DT_STR, 32, 1252)"str" Unicode string [DT_WSTR] 
(DT_STR,32, 1252)(([b] == "1")?(DT_STR,32,1252)NULL(DT_STR, 32, 1252):"str") string [DT_STR] 





1. In the first expression, the cast is not at the root level of the expression. The expression evaluator handles 
this cast intelligently and casts to DT_WSTR, not to DT_STR. The expression returns DT_WSTR. 


2. In the second expression, the cast is at the root level of the expression. The expression returns DT_STR. 


Implicit Data Conversion 


An implicit conversion of a data type occurs when the expression evaluator automatically converts the data from 
one data type to another. For example, if a smallint is compared to an int, the smallint is implicitly converted 
to int before the comparison is performed. 


The expression evaluator cannot perform implicit data conversion when the arguments and operands have 
incompatible data types. In addition, the expression evaluator cannot implicitly convert any value to a Boolean. 
Instead, the arguments and operands must be explicitly converted by using the cast operator. For more 
information, see Cast (SSIS Expression). 


The following diagram shows the result type of implicit conversions of BINARY operations. The intersection of 


column and row in this table is the result type of a binary operation with operands of the left (From) and right 
(To) types. 





The intersection of a signed and an unsigned integer is a signed integer that is potentially larger than either 
argument. 


Operators compare strings, dates, Booleans, and other data types. Before an operator compares two values, the 
expression evaluator performs certain implicit conversions. The expression evaluator always converts string 
literals to the DT_WSTR data type and converts Boolean literals to the DT_BOOL data type. The expression 
evaluator interprets all values enclosed in quotation marks as strings. Numeric literals are converted to one of 
the numeric Integration Services data types. 





NOTE 
Boolean values are logical values, not numbers. Although Boolean values may be displayed as numbers in some 
environments, they are not stored as numbers, and various programming languages represent Boolean values as numeric 


values differently, as do the .NET Framework methods. 


For example, the conversion functions available in Visual Basic convert True to -1; however, the 
System.Convert.ToInt32 method in the .NET Framework converts True to +1. The Integration Services Expression 


Language converts True to -1. 


To avoid errors or unexpected results, you should not write code that relies on particular numeric values for True and 


False. Wherever possible, you should restrict usage of Boolean variables to the logical values for which they are designed. 











For more information, see the following topics: 

e == (Equal) (SSIS Expression) 

e != (Unequal) (SSIS Expression) 

e > (Greater Than) (SSIS Expression) 

e@ < (Less Than) (SSIS Expression) 

@ >= (Greater Than or Equal To) (SSIS Expression) 
@ <= (Less Than or Equal To) (SSIS Expression) 


A function that uses a single argument returns a result with the same data type as the argument, with the 
following exceptions: 


e@ DAY, MONTH, and YEAR accept a date and return an integer (DT_I4) result. 
e ISNULL accepts an expression of any SSIS data type and returns a Boolean (DT_BOOL) result. 
@ SQUARE and SQRT accept a numeric expression and return a non-integral numeric (DT_R8) result. 


If the arguments have the same data type, the result is of that type. The only exception is the result of a binary 
operation on two values with the DT_DECIMAL data type, which returns a result with the DT_NUMERIC data type. 


Requirements for Data Used in Expressions 


The expression evaluator supports all Integration Services data types. However, depending on the operation or 
the function, the operands and arguments require certain data types. The expression evaluator imposes the 
following data type requirements on data used in expressions: 


e Operands used in logical operations must evaluate to a Boolean. For example, ColumnA > 
1&&ColumnB < 2. 


e Operands used in mathematical operations must evaluate to a numeric value. For example, 23.75 * 4. 


e@ Operands used in comparison operations, such as logical and equality operations, must evaluate to 
compatible data types. 


For example, one of the expressions in the following example uses the DT_DBTIMESTAMPOFFSET data 
type: 


(DT_DBTIMESTAMPOFFSET,3) "1999-10-11 20:34:52.123 -3:30" != (DT_DBDATE)"1999-10-12" 


The system converts the expression, (DT_DBDATE)"1999-1@-12" , to DI_DBTIMESTAMPOFFSET. The example 
evaluates to TRUE because the converted expression becomes "1999-10-12 00:00:00.000 +00:00", which 


is not equal to the value of the other expression, 
(DT_DBTIMESTAMPOFFSET,3) "1999-10-11 20:34:52.123 -3:30". 


e Arguments passed to mathematical functions must evaluate to a numeric data type. Depending on the 
function or operation, a specific numeric data type may be required. For example, the HEX function 
requires a signed or unsigned integer. 


e Arguments passed to string functions must evaluate to a character data type: DI_STR or DT_WSTR. For 
example, UPPER("flower"). Some string functions, such as SUBSTRING, require additional integer 
arguments for the start position and the length of the string. 


e Arguments passed to date and time functions must evaluate to a valid date. For example, 
DAY(GETDATE()). Some functions, such as DATEADD, require an additional integer argument for the 
number of days the function adds to a date. 


Operations that combine an unsigned eight-byte integer and a signed integer require an explicit cast to clarify 
the result format. For more information, see Cast (SSIS Expression). 


Results of many operations and functions have predetermined data types. This can be the data type of the 
argument or the data type to which the expression evaluator casts the result. For example, the result of a logical 
OR operator (||) is always a Boolean, the result of the ABS function is the numeric data type of the argument, and 
the result of multiplication is the smallest numeric data type that can hold the result without loss. For more 
information about the data types of results, see Operators (SSIS Expression) and Functions (SSIS Expression). 


Related Tasks 


Use an Expression in a Data Flow Component 


Related Content 


e Technical article, SSIS Expression Cheat Sheet, on pragmaticworks.com 


e Technical article, SSIS Expression Examples, on social.technet.microsoft.com 


Data Truncation (SSIS) 


11/23/2021 * 2 minutes to read « Edit Online 





Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 
Converting values from one data type to another may cause values to be truncated. 
Truncation can occur when: 


e Translating string data from a D7 WS7R to a D7_STR with the same length if the original string contains 
double-byte characters. 


e Casting an integer from a D7_/4to a DT_/2 significant digits can be lost. 

e Casting an unsigned integer to a signed integer significant digits can be lost. 
@ Casting areal number from a D7_R8 to a DT_R4 insignificant digits can be lost 
e Casting an integer from a D7_/4to a DT_R4 insignificant digits can be lost. 


The expression evaluator identifies explicit casts that may cause truncation and issues a warning when the 
expression is parsed. For example, the expression evaluator warns you if a 30-character string is cast into a 20- 
character string. 


However, truncation is not checked at run time. At runtime data is truncated without warning. Most data 
adapters and transformations support error outputs that can handle the disposition of error rows. 


For more information about handling truncation of data, see Error Handling in Data 


Sea lare mm ele (elalem SSIS) 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


The expression evaluator does not check if a string contains leading and trailing spaces, and it does not pad 
strings to make them the same length before it compares them. If expressions requires string padding, you can 
use the + operator to concatenate column values and blank strings. For more information, see + (Concatenate) 
(SSIS Expression). 


On the other hand, if you want to remove spaces, the expression evaluator provides the LTRIM, RTRIM, and TRIM 
functions, which remove leading or trailing spaces, or both. For more information, see LTRIM (SSIS Expression), 
RTRIM (SSIS Expression), and TRIM (SSIS Expression). 





NOTE 


The LEN function includes leading and trailing blanks in its count. 





Related Content 


Technical article, SSIS Expression Cheat Sheet, on pragmaticworks.com 


Syntax (SSIS) 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


The Integration Services expression syntax is similar to the syntax that the C and C# languages use. Expressions 
include elements such as identifiers (columns and variables), literals, operators, and functions. This topic 
summarizes the unique requirements of the expression evaluator syntax as they apply to different expression 
elements. 





NOTE 


In previous releases of Integration Services, there was a 4000-character limit on the evaluation result of an expression 
when the result had the Integration Services data type DT_WSTR or DT_STR. This limit has been removed. 








For sample expressions that use specific operators and functions, see the topic about each operator and function 
in the topics: Operators (SSIS Expression) and Functions (SSIS Expression). 


For sample expressions that use multiple operators and functions as well as identifiers and literals, see Examples 
of Advanced Integration Services Expressions. 


For sample expressions to use in property expressions, see Use Property Expressions in Packages. 


Identifiers 


Expressions can include column and variable identifiers. The columns can originate in the data source or can be 
created by transformations in the data flow. Expressions can use lineage identifiers to refer to columns. Lineage 
identifiers are numbers that uniquely identify package elements. Lineage identifiers, referenced in an expression, 
must include the pound (#) prefix. For example, the lineage identifier 138 is referenced using #138. 


Expressions can include the system variables that SSIS provides and custom variables. Variables, when 
referenced in an expression, must include the @ prefix. For example, the counter variable is referenced using 
@Counter. The @ character is not part of the variable name; it only indicates to the expression evaluator that the 
identifier is a variable. For more information, see Identifiers (SSIS). 


Literals 


Expressions can include numeric, string, and Boolean literals. String literals used in expressions must be 
enclosed in quotation marks. Numeric and Boolean literals do not take quotation marks. The expression 
language includes escape sequences for characters that are frequently escaped. For more information, see 
Literals (SSIS). 


Operators 


The expression evaluator provides a set of operators that provides functionality similar to the set of operators in 
languages such as Transact-SQL, C++, and C#. However, the expression language includes additional operators 
and uses different symbols than those you may be familiar with. For more information, see Operators (SSIS 
Expression). 


Namespace Resolution Operator 


Expressions use the namespace resolution operator (::) to disambiguate variables that have the same name. By 


using the namespace resolution operator, you can qualify the variable with its namespace, which makes it 
possible to use multiple variables with the same name in a package. 


Cast Operator 

The cast operator converts expression results, column values, variable values, and constants from one data type 
to another. The cast operator provided by the expression language is similar to the one provided by the C and 
C# languages. In Transact-SQL, the CAST and CONVERT functions provide this functionality. The syntax of the 
cast operator is different from ones used by CAST and CONVERT in the following ways: 


e It can use an expression as an argument. 
e Its syntax does not include the CAST keyword. 


e Its syntax does not include the AS keyword. 


Conditional Operator 

The conditional operator returns one of two expressions, based on the evaluation of a Boolean expression. The 
conditional operator provided by the expression language is similar to the one provided by the C and C# 
languages. In multidimensional expressions (MDX), the IIF function provides similar functionality. 

The expression language supports the ! character for the logical NOT operator. In Transact-SQL, the ! operator is 
built into the set of relational operators. For example, Transact-SQL provides the > and the !> operators. The 
SSIS expression language does not support the combination of the ! operator and other operators. For example, 
it is not valid to combine ! and > into !>. However, the expression language does support a built-in != 
combination of characters for the not-equal-to comparison. 

The expression evaluator grammar provides the == equality operator. This operator is the equivalent of the = 
operator in Transact-SQL and the == operator in C#. 


Functions 


The expression language includes date and time functions, mathematical functions, and string functions that are 
similar to Transact-SQL functions and C# methods. 


A few functions have the same names as Transact-SQL functions, but have subtly different functionality in the 
expression evaluator. 


e In Transact-SQL, the ISNULL function replaces null values with a specified value, whereas the expression 
evaluator ISNULL function returns a Boolean based on whether an expression is null. 


e In Transact-SQL, the ROUND function includes an option to truncate the result set, whereas the 
expression evaluator ROUND function does not. 


For more information, see Functions (SSIS Expression). 


Related Tasks 


Use an Expression in a Data Flow Component 


Related Content 


e Technical article, SSIS Expression Cheat Sheet, on pragmaticworks.com 


e Technical article, SSIS Expression Examples, on social.technet.microsoft.com 


Identifiers (SSIS) 
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In expressions, identifiers are columns and variables that are available to the operation. Expressions can use 
regular and qualified identifiers. 


Regular Identifiers 


A regular identifier is an identifier that needs no additional qualifiers. For example, MiddleName, a column in 
the Contacts table of the AdventureWorks database, is a regular identifier. 


The naming of regular identifiers must follow these rules: 


e The first character of the name must be a letter as defined by the Unicode Standard 2.0, or an underscore 


Q). 


e Subsequent characters can be letters or numbers as defined in the Unicode Standard 2.0, the underscore 
(_), @, $, and # characters. 





IMPORTANT 


Embedded spaces and special characters, other than the ones listed, are not valid in regular identifiers. In order to use 
spaces and special characters, you must use a qualified identifier instead of a regular identifier. 











Qualified Identifiers 


A qualified identifier is an identifier that is delimited by brackets. An identifier may require a delimiter because 
the name of the identifier includes spaces, or because the identifier name does not begin with either a letter or 
the underscore character. For example, the column name Middle Name must be qualified by brackets and 
written as [Middle Name] in an expression. 


If the name of the identifier includes spaces, or if the name is not a valid regular identifier name, the identifier 
must be qualified. The expression evaluator uses the opening and closing ([]) brackets to qualify identifiers. The 
brackets are put in the first and the last position of the string. For example, the identifier 5$> becomes [5$>]. 


Brackets can be used with column names, variable names, and function names. 


If you build expressions using the SSIS Designer dialog boxes, regular identifiers are automatically enclosed in 
brackets. However, brackets are required only if the name include invalid characters. For example, the column 
named MiddleName is valid without brackets. 


You cannot reference column names that include brackets in expressions. For example, the column name 
Column[1] cannot be used in an expression. To use the column in an expression it must be renamed to a name 
without brackets. 


Lineage Identifiers 


Expressions can use lineage identifiers to refer to columns. The lineage identifiers are assigned automatically 
when you first create the package. You can view the lineage identifier for a column on the Column Properties 
tab of the Advanced Editor dialog box in the SSIS Designer. 


If you refer to a column using its lineage identifier, the identifier must include the pound (#) character prefix. For 
example, a column with the lineage identifier 147 must be referenced as #147. 


If an expression parses successfully, the expression evaluator replaces the lineage identifiers with column names 
in the dialog box. 


Unique Column Names 


Multiple components used in a package can expose columns with the same name. If these columns are used in 
expressions, they must be disambiguated before the expressions can be parsed successfully. The expression 
evaluator supports the dotted notation for identifying the source of the column. For example, two columns 
named Age become FlatFileSource.Age and OLEDBSource.Age, which indicates that their sources are 
FlatFileSource or OLEDBSource. The parser treats the fully qualified name as a single column name. 


Source component names and column names are qualified separately. The following examples show valid use of 
brackets in a dotted notation: 


e The source component name includes spaces. 
[MySo urce].Age 
e The first character in the column name is not valid. 
MySource. [#Age] 
e The source component and the column names contain invalid characters. 


[MySource? ]. [#Age] 





IMPORTANT 


If both elements in dotted notation are enclosed in one pair of brackets, the expression evaluator interprets the pair as a 
single identifier, not a source-column combination. 











Variables in Expressions 


Variables, when referenced in expressions, must include the @ prefix. For example, the Counter variable is 
referenced by using @Counter. The @ character is not part of the variable name; it only identifies the variable to 
the expression evaluator. If you build expressions by using the dialog boxes that SSIS Designer provides, the @ 
character is automatically added to the variable name. It is not valid to include spaces between the @ character 
and the variable name. 


Variable names follow the same rules as those for other regular identifiers: 


e The first character of the name must be a letter as defined by the Unicode Standard 2.0, or an underscore 


(). 


e Subsequent characters can be letters or numbers as defined in the Unicode Standard 2.0, the underscore 
(_), @, $, and # characters. 


If a variable name contains characters other than those listed, the variable must be enclosed in brackets. For 
example, variable names with spaces must be enclosed in brackets. The opening bracket follows the @ character. 
For example, the My Name variable is referenced as @[My Name]. It is not valid to include spaces between the 


variable name and the brackets. 





NOTE 


The names of user-defined and system variables are case-sensitive. 





Unique Variable Names 


Integration Services supports custom variables and provides a set of system variables. By default, custom 
variables belong to the User namespace, and system variables belong to the System namespace. You can 
create additional namespaces for custom variables and update the namespace names to suit the needs of your 


application. The expression builder lists in-scope variables in all namespaces. 


All variables have scope and belong to a namespace. A variable has package scope or the scope of a container or 
task in the package. The expression builder in SSIS Designer lists only the in-scope variables. For more 
information, see Integration Services (SSIS) Variables and Use Variables in Packages. 


Variables used in expressions must have unique names for the expression evaluator to evaluate the expression 
correctly. If a package uses multiple variables with the same name, their namespaces must be different. 
Integration Services provides a namespace resolution operator, consisting of two colons (:), for qualifying a 
variable with its namespace. For example, the following expression uses two variables named Count; one 
belongs to the User namespace and one to the MyNamespace namespace. 


@[User::Count] > @[MyNamespace: :Count ] 


IMPORTANT 


You must enclose the combination of namespace and qualified variable name in brackets for the expression evaluator to 


recognize the variable. 





If the value of Count in the User namespace is 10 and the value of Count in MyNamespace is 2, the 


expression evaluates to true because the expression evaluator recognizes two different variables. 


If variable names are not unique, no error occurs. Instead, the expression evaluator uses only one instance of the 
variable to evaluate the expression and returns an incorrect result. For example, the following expression was 
intended to compare the values (10 and 2) for two separate Count variables but the expression evaluates to 
false because the expression evaluator uses the same instance of the Count variable two times. 


@Count > @Count 


Related Content 


Technical article, SSIS Expression Cheat Sheet, on pragmaticworks.com 


Numeric, string, and Boolean literals 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Expressions can include numeric, string, and Boolean literals. The expression evaluator supports a variety of 
numeric literals such as integers, decimals, and floating-point constants. The expression evaluator also supports 
the long and float suffixes, which specify how the expression evaluator handles values, and scientific notation in 
numeric literals. 


Numeric Literals 


The expression evaluator supports integral and nonintegral numeric data types. It also supports lineage 
identifiers (the unique numeric identifiers for package elements). Lineage identifiers are numbers, but they 
cannot be used in mathematical operations. 


The expression evaluator supports suffixes, which you can use to indicate how the expression evaluator treats 
the numeric literal. For example, you can indicate the integer 37 be treated as a long integer data type by writing 
37L or 371. 


The following table lists suffixes for numeric literals. 


SUFFIX DESCRIPTION 

Lor | A long numeric literal. 

Uoru An unsigned numeric literal. 
Eore The exponent in scientific notation 


The following table lists numeric expression elements and their regular expressions. 


EXPRESSION ELEMENT REGULAR EXPRESSION DESCRIPTION 

Digits expressed as D. [0-9] Any digit. 

Scientific notation expressed as E. [Ee][+-]?{D}+ Upper or lowercase e, optionally + or - 
, and one or more digits as defined in 
D. 

Integer suffix expressed as IS. (((ILJ2(UUJ?)|((uU]?[IL]?)) Optionally, upper or lowercase u and | 


or a combination of u and |. U or u 
indicates an unsigned value. L or | 
indicates a long value. 


Float suffix expressed as FS. ((fIFAILL1) Upper or lowercase f or I. F or f 
indicates a float value (DT_R4 data 
type). L or | indicates a long value 
(DT_R8 data type). 


Hexadecimal digit expressed as H. [a-fA-FO-9] Any hexadecimal digit. 


The following table describes valid numeric literals using the regular expression language. 


REGULAR EXPRESSION 


{D}+{IS} 


{D}+{E}{FS} 


{D}*"."{D} + {E}2(FS} 


{D}+".{D}*{E}(FS} 


{D}*.{D}+ 


{D}+.{D}* 


#HD}+ 


O[xx]{H}+ {uU} 


DESCRIPTION 


An integral numeric literal with at least one digit (D) and, 
optionally, the long and/or the unsigned suffix (IS). Examples: 
457, 785u, 986L, and 7945ul. 


A nonintegral numeric literal with at least one digit (D), 
scientific notation, and the long or the float suffix. Examples: 
AE8I, 13e-2f and SE+L. 


A nonintegral numeric literal with a decimal place, a decimal 
fraction with at least one digit (D), an optional exponent (E), 
and one float or one long identifier (FS). This numeric literal 
has the DT_R4 or DT_R8 data type. Examples: 6.45E3f, .89E- 
2l, and 1.05E+7F. 


A nonintegral numeric literal with at least one significant 
digit (D), a decimal place, an exponent (E), and one float or 
one long identifier (FS). This numeric literal has the DT_R4 or 
DT_R8 data type. Examples: 1.£-4f 4.6E6L, and 8.365E+2f. 


A nonintegral numeric literal with precision and scale. It has 
a decimal place and a decimal fraction with at least one digit 
(D). This numeric literal has the DT.NUMERIC data type. 
Examples: .9, 5.8, and 0.346. 


A nonintegral numeric literal with precision and scale. It has 
at least one significant digit (D) and a decimal place. This 
numeric literal has the DT_NUMERIC data type. Examples: 6., 
0.2, and 8.0. 


A lineage identifier. It consists of the pound (#) character and 
at least one digit (D). Examples: #123. 


A numeric literal in hexadecimal format. It includes a zero, an 
upper or lowercase x, at least one uppercase H, and, 
optionally, the unsigned suffix. Examples: OxFFOA and 
0X000010000U. 


For more information about the data types the expression evaluator uses, see Integration Services Data Types. 


Expressions can include numeric literals with different data types. When the expression evaluator evaluates 


these expressions, it converts the data to compatible types. For more information, see Integration Services Data 


Types in Expressions. 


However, conversion between some data types requires an explicit cast. The expression evaluator provides the 


cast operator for performing explicit data type conversion. For more information, see Cast (SSIS Expression). 


Mapping Numeric Literals to Integration Services Data Types 


The expression evaluator performs the following conversions when evaluating numeric literals: 


e An integral numeric literal is mapped to an integer data type as follows. 


SUFFIX 


None 


RESULT TYPE 


DT_l4 


SUFFIX RESULT TYPE 


U DT_UI4 
L DT_I8 
UL DT_UI8 


IMPORTANT!! If the long (L or |) suffix is absent, the expression evaluator maps signed values to the 
DT_I4 data type and unsigned values to the DT_UI4 data type even though the value overflows the 
data type. 


e Anumeric literal that includes an exponent is converted to either the DT_R4 or the DT_R8 data type. If the 
expression includes the long suffix, it is converted to DT_R8; if it includes the float suffix, it is converted to 
the DT_R4 data type. 


e If anonintegral numeric literal includes F or f, it maps to the DT_R4 data type. If it includes L or | and the 
number is an integer, it maps to the DT_I8 data type. If it is a real number, it maps to the DT_R8 data type. 
If it includes the long suffix, it is converted to the DT_R8 data type. 


e Anonintegral numeric literal with precision and scale maps to the DT_NUMERIC data type. 


String Literals 


String literals must be enclosed in quotation marks. The expression language provides a set of escape sequences 


for commonly escaped characters such as nonprinting characters and quotation marks. 


A string literal consists of zero or more characters surrounded by quotation marks. If a string contains quotation 
marks, these must be escaped in order for the expression to parse. Any two-byte character except \x0000 is 
permitted in a string, because the \x0000 character is the null terminator of a string. 


Strings can include other characters that require an escape sequence. The following table lists escape sequences 
for string literals. 


ESCAPE SEQUENCE DESCRIPTION 
\a Alert 

\b Backspace 

\f Form feed 

\n New line 

\r Carriage return 
\t Horizontal tab 
\v Vertical tab 

¥ Quotation mark 


\|Backslash 


ESCAPE SEQUENCE DESCRIPTION 


\xhhhh Unicode character in hexadecimal notation 


Boolean Literals 


The expression evaluator supports the usual Boolean literals: True and False. The expression evaluator is not 
case-sensitive and any combination of uppercase and lowercase letters are permitted. For example, TRUE works 


just as well as True. 


NOTE: In an expression, a Boolean literal must be delimited by spaces. 


Operators (SSIS Expression) 
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This section describes the operators the expression language provides and the operator precedence and 
associativity that the expression evaluator uses. 


The following table lists topics about operators in this section. 


OPERATOR DESCRIPTION 

Cast (SSIS Expression) Converts an expression from one data type to a different 
data type. 

() (Parentheses) (SSIS Expression) Identifies the evaluation order of expressions. 

+ (Add) (SSIS) Adds two numeric expressions. 

+ (Concatenate) (SSIS Expression) Concatenates two expressions. 

- (Subtract) (SSIS Expression) Subtracts the second numeric expression from the first one. 

- (Negate) (SSIS Expression) Negates a numeric expression. 

* (Multiply) (SSIS Expression) Multiplies two numeric expressions. 

/ (Divide) (SSIS Expression) Divides the first numeric expression by the second one. 

% (Modulo) (SSIS Expression) Provides the integer remainder after dividing the first 


numeric expression by the second one. 


|| (Logical OR) (SSIS Expression) Performs a logical OR operation. 

&8& (Logical AND) (SSIS Expression) Performs a logical AND operation. 

! (Logical NOT) (SSIS Expression) Negates a Boolean operand. 

| (Bitwise Inclusive OR) (SSIS Expression) Performs a bitwise OR operation of two integer values. 

‘ (Bitwise Exclusive OR) (SSIS Expression) Performs a bitwise exclusive OR operation of two integer 
values. 

& (Bitwise AND) (SSIS Expression) Performs a bitwise AND operation of two integer values. 

~ (Bitwise NOT) (SSIS Expression) Performs a bitwise negation of an integer. 

== (Equal) (SSIS Expression) Performs a comparison to determine if two expressions are 


equal. 


OPERATOR 


!= (Unequal) (SSIS Expression) 


> (Greater Than) (SSIS Expression) 


< (Less Than) (SSIS Expression) 


>= (Greater Than or Equal To) (SSIS Expression) 


<= (Less Than or Equal To) (SSIS Expression) 


? : (Conditional) (SSIS Expression) 


DESCRIPTION 


Performs a comparison to determine if two expressions are 
not equal. 


Performs a comparison to determine if the first expression is 
greater than the second one. 


Performs a comparison to determine if the first expression is 
less than the second one. 


Performs a comparison to determine if the first expression is 
greater than or equal to the second one. 


Performs a comparison to determine if the first expression is 
less than or equal to the second one. 


Returns one of two expressions based on the evaluation of a 
Boolean expression. 


For information about the placement of each operator in the precedence hierarchy, see Operator Precedence 


and Associativity. 


See Also 


Functions (SSIS Expression) 
Examples of Advanced Integration Services Expressions 
Integration Services (SSIS) Expressions 


Operator Precedence and Associativity 
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Each operator in the set of operators that the expression evaluator supports has a designated precedence in the 
precedence hierarchy and includes a direction in which it is evaluated. The direction of evaluation for an 
operator is operator associativity. Operators with higher precedence are evaluated before operators with lower 
precedence. If a complex expression has multiple operators, operator precedence determines the order in which 
the operations are performed. The order of execution can significantly affect the resulting value. Some operators 
have equal precedence. If an expression contains multiple operators of equal precedence, the operators are 
evaluated directionally, from left to right or right to left. 


The following table lists the precedence of operators in order of high to low. Operators at the same level have 
equal precedence. 


OPERATOR SYMBOL TYPE OF OPERATION ASSOCIATIVITY 
() Expression Left to right 
Slee Unary Right to left 
casts Unary Right to left 
* 1% Multiplicative Left to right 
+,- Additive Left to right 
2S 25, $5 Relational Left to right 
==,l5 Equality Left to right 
& Bitwise AND Left to right 
* Bitwise exclusive OR Left to right 
| Bitwise inclusive OR Left to right 
RR Logical AND Left to right 
| Logical OR Left to right 
ae Conditional expression Right to left 
See Also 


Operators (SSIS Expression) 


Cast (SSIS Expression) 
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Explicitly converts an expression from one data type to a different data type. The cast operator can also function 
as a truncation operator. 


Syntax 


(type_spec) expression 


Arguments 


type_spec 
Is a valid SSIS data type. 


expression 
Is a valid expression. 


Result Types 


The data type of type_spec. For more information, see Integration Services Data Types. 


Remarks 


The following diagram shows legal cast operations. 
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DT_Ule eeeeeeeeeese Been seeseeen ene eeee 
DT_UI4 eeeaeaeaeaeaeaeeoese 2@enaeeeaecenenaeneee 
DT_IB eeeeeeneseaceese 2aHeeeeneeaeeaeaeee 
DT_UIS eeeeeeneaeaeee ee Sseaeeneeaeaeanaeene 
DT_GUID eeeeaeecuaeeuaeeeeoeee e28ee8eeeee08e000 
DT_BYTES eeseeeeaeaeneeneaeneeaene eenneneneneenee8e 
DT_STR eeeeeeeaeeeaeoeooooeooeoe seaeeeee ee ee 
DT_WSTR eeeeeeeeeeeoseeeaee ee eeeaeee eeee 
DT_DBDATE Seeeseeeceneaeneaeneuaenaeeed eeeeeenue8 
DT_DBTIME Seeeseeeeseneeeneeneaeaeaede eeeaeaeneee 
DT_DBTIME2 eseeeeaeeeeneeneeneaeneneaeee eeeeen8 
DT_DBTIMESTAMP eseseaeeeseneeneeeaeneaeaeaeaeane eseaeneee 
DT_DBTIMESTAMP2 eeseeeseeceeeeceeeeeeeeaeaeaeese 28806086 
DT_OBTIMESTAMPOFFSET @@OSSSSSSSSGeSSGeGeeGe8ee Cee 00 o88086 
DT_FILETIME Seeeseeeeeneeneeeaeneeeaeee eee 8880 
DT_IMAGE eeeeeeceaeaeoeooeooe eceaeeaeaeeeaeeeees 080 
DT_TEXT eeeeeee eCceeeeeeeseeeeaeaeae ee eee @ 
DT_NTEXT eeeeeaceeaoeoeooe ecaeaeeaeeaeeoeec eo eee @ 


@ Legal cast 
@ Illegal cast 


Casting to some data types requires parameters. The following table lists these data types and their parameters. 


DATA TYPE PARAMETER EXAMPLE 
DT_STR charcount (DT_STR,30,1252) casts 30 bytes, or 30 
single characters, to the DT_STR data 
codepage type using the 1252 code page. 
DT_WSTR Charcount (DT_WSTR,20) casts 20 byte pairs, or 


20 Unicode characters, to the 
DT_WSTR data type. 


DT_BYTES Bytecount (DT_BYTES,50) casts 50 bytes to the 
DT_BYTES data type. 


DT_DECIMAL Scale (DT_DECIMAL,2) casts a numeric value 
to the DT_DECIMAL data type using a 
scale of 2. 

DT_NUMERIC Precision (DT_NUMERIC,10,3) casts a numeric 


value to the DT_.NUMERIC data type 
Scale using a precision of 10 and a scale of 
3: 


DATA TYPE PARAMETER EXAMPLE 


DT_TEXT Codepage (DT_TEXT,1252) casts a value to the 
DT_TEXT data type using the 1252 
code page. 


When a string is cast to a DT_DATE, or vice versa, the locale of the transformation is used. However, the date is in 


the ISO format of YYYY-MM-DD, regardless of whether the locale preference uses the ISO format. 





NOTE 
To convert a string to a date data type other than DT_DATE, see Integration Services Data Types. 





If the code page is a multibyte character code page, the number of bytes and characters may differ. Casting from 
a DT_WSTR to a DT_STR with the same charcount value may cause truncation of the final characters in the 
converted string. If sufficient storage is available in the column of the destination table, set the value of the 
charcount parameter to reflect the number of bytes that the multibyte code page requires. For example, if you 
cast character data to a DI_STR data type using the 936 code page, you should set charcountto a value up to 
two times greater than the number of characters that you expect the data to contain; if you cast character data 
using the UTF-8 code page, you should set charcountto a value up to four times greater. 


For more information about the structure of date data types, see Integration Services Data Types. 


SSIS Expression Examples 


This example casts a numeric value to an integer. 
(DT_I4) 3.57 

This example casts an integer to a character string using the 1252 code page. 
(DT_STR,1,1252)5 

This example casts a three-character string to double-byte characters. 
(DT_WSTR, 3) "Cat" 

This example casts an integer to a decimal with a scale of two. 
(DT_DECIMA1, 2) 500 

This example casts an integer to a numeric with a precision of seven and scale of three. 
(DT_NUMERIC,7,3)4000 


This example casts values in the FirstName column, defined with an nvarchar data type and a length of 50, to 
a character string using the 1252 code page. 


(DT_STR,50,1252)FirstName 


This example casts values in the DateFirstPurchase column of type DT_DBDATE, to a Unicode character string 
with a length of 20. 


(DT_WSTR, 20)DateFirstPurchase 

This example casts the string literal "True" to a Boolean. 
(DT_BOOL) "True" 

This example casts a string literal to DT_DBDATE. 


(DT_DBDATE) "1999-10-11" 


This example casts a string literal to the DI_DBTIME2 data type that uses 5 digits for fractional seconds. (The 
DT_DBTIME2 data type can have between 0 and 7 digits specified for fractional seconds.) 


(DT_DBTIME2, 5) "16:34:52.12345" 


This example casts a string literal to the DT_DBTIMESTAMP2 data type that uses 4 digits for fractional seconds. 
(The DT_DBTIMESTAMP2 data type can have between 0 and 7 digits specified for fractional seconds.) 


(DT_DBTIMESTAMP2, 4) "1999-10-11 16:34:52.1234" 


This example casts a string literal to the DT_DBTIMESTAMPOFFSET data type that uses 7 digits for fractional 
seconds. (The DT_DBTIMESTAMPOFFSET data typecan have between 0 and 7 digits specified for fractional 
seconds.) 


(DT_DBTIMESTAMPOFFSET, 7) "1999-10-11 16:34:52.1234567 + 5:35" 


See Also 


Operator Precedence and Associativity 
Operators (SSIS Expression) 

Integration Services (SSIS) Expressions 
Integration Services Data Types in Expressions 


() (Parentheses) (SSIS Expression) 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Identifies the evaluation order of expressions. Expressions enclosed in parentheses have the highest evaluation 
precedence. Nested expressions enclosed in parentheses are evaluated in inner-to-outer order. 


Parentheses are also used to make complex expressions easier to understand. 


Syntax 


(expression) 


Arguments 


expression 


Is any valid expression. 


Result Types 


The data type of expression. For more information, see Integration Services Data Types. 


Expression Examples 
This example shows how the use of parenthesis modifies the precedence of operators. The first expression 


evaluates to 100, whereas the second one evaluates to 31. 


(5 4 5) * (4 + 6) 
54+5 7446 


See Also 


Operator Precedence and Associativity 
Operators (SSIS Expression) 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Adds two numeric expressions. 


Syntax 


numeric_expression1 + numeric_expression2 


Arguments 


numeric_expression1, numeric. expression2 


Is any valid expression of a numeric data type. 


Result Types 


Determined by data types of the two arguments. For more information, see Integration Services Data Types. 


Remarks 


If either operand is null, the result is null. 


Expression Examples 


This example adds numeric literals. 
5 + 6.09 + 7.0 

This example adds values in the VacationHours and SickLeaveHours columns. 
VacationHours + SickLeaveHours 


This example adds a calculated value to the StandardCost column. The variable Profit% must be enclosed in 
brackets because the name includes the % character. For more information, see Identifiers (SSIS). 


StandardCost + (StandardCost * @[Profit%]) 


See Also 


Operator Precedence and Associativity 
Operators (SSIS Expression) 


+ (Concatenate) (SSIS Expression) 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Concatenates two expressions into one expression. 


Syntax 


character_expression1 + character_expression2 


Arguments 


expression, expression2 
Is any valid DT_STR, DT_WSTR, DT_TEXT, DT_NTEXT, or DT_IMAGE data type expression. 


Result Types 


DT_WSTR 


Remarks 
The expression can use either or both of the DT_STR and DT_WSTR data types. 


The concatenation of the DT_STR and DT_WSTR data types returns a result of the DT_WSTR type. The length of 
the string is the sum of the lengths of the original strings expressed in characters. 


Only data with the string data types DI_STR and DT_WSTR or the Binary Large Object Block (BLOB) data types 
DT_TEXT, DT_NTEXT, and DT_IMAGE can be concatenated. Other data types must be explicitly converted to one of 
these data types before concatenation occurs. For more information about legal casts between data types, see 
Cast (SSIS Expression). 


Both expressions must be of the same data type, or one expression must be implicitly convertible to the data 
type of the other expression. For example, if the string "Order date is " and the column OrderDate are 
concatenated, the values in OrderDate are implicitly converted to a string data type. To concatenate two 
numeric values, both numeric values must be explicitly cast to a string data type. 


A concatenation can use only one BLOB data type: DT_TEXT, DT_NTEXT, or DT_IMAGE. 
If either element is null, the result is null. 


String literals must be enclosed in quotation marks. 


Expression Examples 


This example concatenates the values in the FirstName and LastName columns and inserts a space between 
them. 


FirstName + ' ' + LastName 


This example concatenates the variables ZIPCode and ZIPCode+4. Both variables have a string data type. 
ZIPCode+4 must be enclosed in brackets because the variable name includes the + character. 


@ZIPCcode + "-" + @[ZipCode+4] 


See Also 


Operator Precedence and Associativity 
Operators (SSIS Expression) 


- (Subtract) (SSIS Expression) 
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Applies to: Q sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Subtracts the second numeric expression from the first one. 


Syntax 


numeric_expression1 - numeric_expression2 


Arguments 


numeric_expression1, numeric_expression2 


Is any valid expression of a numeric data type. For more information, see Integration Services Data Types. 


Result Types 


Determined by the data types of the two arguments. For more information, see Integration Services Data Types 
in Expressions. 


Remarks 


e Enclose the minus unary expression in parenthesis to ensure that the expression is evaluated in the 
correct order 


e If either operand is null, the result is null. 


Expression Examples 


This example subtracts numeric literals. 
5 - 6.09 

This example subtracts the value in the StandardCost column from the value in the ListPrice column. 
ListPrice - StandardCost 


This example subtracts a calculated value from the ListPrice column. The variable Discount% must be 
enclosed in brackets because the name includes the % character. For more information, see Identifiers (SSIS). 


ListPrice - (ListPrice * @[Discount%]) 


See Also 


Operator Precedence and Associativity 


Operators (SSIS Expression) 


- (Negate) (SSIS Expression) 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Negates a numeric expression. 


Syntax 


-numeric_expression 


Arguments 


numeric_expression 


Is any valid expression of any numeric data type. Only signed numeric data types are supported. For more 
information, see Integration Services Data Types. 


Result Types 


Returns the data type of numeric_expression. 


Expression Examples 


This example negates the value of the Counter variable and adds the numeric literal 50. 


-@Counter + 50 


See Also 


Operator Precedence and Associativity 


Operators (SSIS Expression) 


* (Multiply) (SSIS Expression) 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Multiplies two numeric expressions. 


Syntax 


numeric_expression1 * numeric_expression2 


Arguments 


numeric_expression1, numeric_expression2 


Is any valid expression of a numeric data type. For more information, see Integration Services Data Types. 


Result Types 


Determined by data types of the two arguments. For more information, see Integration Services Data Types in 
Expressions. 


Remarks 


If either operand is null, the result is null. 


Expression Examples 


This example multiplies numeric literals. 
5 * 6.09 
This example multiplies values in the ListPrice column by 10 percent. 


ListPrice * .10 


This example subtracts the result of an expression from the ListPrice column. The variable Discount% must be 
enclosed in brackets because the name includes the % character. For more information, see Identifiers (SSIS). 


ListPrice - (ListPrice * @[Discount%]) 


See Also 


Operator Precedence and Associativity 
Operators (SSIS Expression) 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Divides the first numeric expression by the second one. 


Syntax 


dividend / divisor 


Arguments 


dividend 
Is the numeric expression to divide. dividend can be any valid numeric expression. For more information, see 
Integration Services Data Types. 


divisor 


Is the numeric expression to divide the dividend by. d/visor can be any valid numeric expression except zero. 


Result Types 


Determined by data types of the two arguments. For more information, see Integration Services Data Types in 
Expressions. 


Remarks 


If either operand is null, the result is null. 


Dividing by zero is not legal. Depending on how the divisor subexpression is evaluated, one of following errors 
occurs: 


e If the divisor subexpression that evaluates to zero is a constant, the error appears at design time, causing 
the expression to fail validation. 


e If the divisor subexpression that evaluates to zero contains variables, but no input columns, the 
component to which the expression belongs fails the pre-execution validation that occurs before the 
package runs. 


e If the divisor subexpression that evaluates to zero contains input columns, the error appears at run time 
and is handled according to the error flow rules of the data flow component. 


Expression Examples 


This example divides two numeric literals. 
25/5 


This example divides values in the ListPrice column by values in the StandardCost column. 


ListPrice / StandardCost 


See Also 


Operator Precedence and Associativity 
Operators (SSIS Expression) 


(Modulo) (SSIS Expression) 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Provides the integer remainder after dividing the first numeric expression by the second one. 


Syntax 


dividend % divisor 


Arguments 


dividend 
Is the numeric expression to divide. dividend can be any valid numeric expression. For more information, see 
Integration Services Data Types 


divisor 


Is the numeric expression to divide the dividend by. d/visor can be any valid numeric expression except zero. 


Result Types 


Determined by data types of the two arguments. For more information, see Integration Services Data Types in 
Expressions. 


Remarks 
Both expressions must evaluate to signed or unsigned integer data types. 
If either operand is null, the result is null. 


Modulo zero is not legal. 


Expression Examples 


This example computes the modulus from two numeric literals. The result is 3. 
42 % 13 

This example computes the modulus from the SalesQuota column and a numeric literal. 
SalesQuota % 12 


This example computes the modulus from two numeric variables Sales$ and Month. The variable Sales$ must 
be enclosed in brackets because the name includes the $ character. For more information, see Identifiers (SSIS). 


@[Sales$] % @Month 


This example uses the modulo operator to determine if the value of the Value variable is even or odd, and uses 
the conditional operator to return a string that describes the result. For more information, see ? : (Conditional) 
(SSIS Expression). 


@Value % 2 == @? "even":"odd" 


See Also 


Operator Precedence and Associativity 
Operators (SSIS Expression) 


|| (Logical OR) (SSIS Expression) 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Performs a logical OR operation. The expression evaluates to TRUE if one or both conditions are TRUE. 


Syntax 


boolean_expression1 || boolean_expression2 


Arguments 


boolean_expression?, boolean_expression2 
Is any valid expression that evaluates to TRUE, FALSE, or NULL. 


Result Types 


DT_BOOL 


Remarks 


The following table shows the result of the || operator. 


RESULT EXPRESSION EXPRESSION 
TRUE TRUE TRUE 
TRUE TRUE FALSE 
FALSE FALSE FALSE 
NULL NULL NULL 
TRUE NULL TRUE 
NULL NULL FALSE 


SSIS Expression Examples 


This example uses the StandardCost and ListPrice columns. The example evaluates to TRUE if the value of the 
StandardCost column is less than 300 or the ListPrice column is greater than 500. 


StandardCost < 30@ || ListPrice > 500 


This example uses the variables SPrice and LPrice instead of numeric literals. 


StandardCost < @SPrice || ListPrice > @LPrice 


See Also 


| (Bitwise Inclusive OR) (SSIS Expression) 
‘ (Bitwise Exclusive OR) (SSIS Expression) 
Operator Precedence and Associativity 
Operators (SSIS Expression) 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Performs a logical AND operation. The expression evaluates to TRUE if all conditions are TRUE. 


Syntax 


boolean_expression1 && boolean_expression2 


Arguments 


boolean _expression1, boolean_expression2 
Is any valid expression that evaluates to TRUE, FALSE, or NULL. 


Result Types 


DT_BOOL 


Remarks 


The following table shows the result of the && operator. 


RESULT EXPRESSION EXPRESSION 
TRUE TRUE TRUE 

FALSE TRUE FALSE 
FALSE FALSE FALSE 

NULL NULL NULL 

NULL NULL TRUE 

FALSE NULL FALSE 


Expression Examples 


This example uses the StandardCost and the ListPrice columns. The example evaluates to TRUE if the value of 
the StandardCost column is less than 300 and the ListPrice column is greater than 500. 


StandardCost < 300 && ListPrice > 500 


This example uses the variables SPrice and LPrice instead of literals. 


StandardCost < @SPrice && ListPrice > @LPrice 


See Also 


& (Bitwise AND) (SSIS Expression) 
Operator Precedence and Associativity 
Operators (SSIS Expression) 


| (Logical Not) (SSIS Expression) 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Negates a Boolean operand. 


NOTE 


The ! operator cannot be used in conjunction with other operators. For example, you cannot combine the ! and the > 
operators into the !>. operator. 











Syntax 


!boolean_expression 


Arguments 


boolean_expression 


Is any valid expression that evaluates to a Boolean. For more information, see Integration Services Data Types. 


Result Types 


DT_BOOL 


Remarks 


The following table shows the result of the ! operation. 


ORIGINAL BOOLEAN EXPRESSION AFTER APPLYING THE ! OPERATOR 
TRUE FALSE 
NULL NULL 
FALSE TRUE 


Expression Examples 


This example evaluates to FALSE if the Color column value is "red". 
!(Color == "red") 


This example evaluates to TRUE if the value of the MonthNumber variable is the same as the integer that 
represents the current month. For more information, see MONTH (SSIS Expression) and GETDATE (SSIS 
Expression). 


!(@MonthNumber != MONTH(GETDATE() ) 


See Also 


Operator Precedence and Associativity 
Operators (SSIS Expression) 


| (Bitwise Inclusive OR) (SSIS Expression) 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Performs a bitwise OR operation of two integer values. It compares each bit of its first operand to the 
corresponding bit of its second operand. If either bit is 1, the corresponding result bit is set to 1. Otherwise, the 
corresponding result bit is set to zero (0). 


Both conditions must be a signed integer data type or both conditions must be an unsigned integer data type. 


Syntax 


integer_expression1 | integer_expression2 


Arguments 


integer_expression7 ,integer_ expression2 
Is any valid expression of a signed or unsigned integer data type. For more information, see Integration Services 
Data Types. 


Result Types 


Determined by data types of the two arguments. For more information, see Integration Services Data Types in 
Expressions. 


Remarks 


If either condition is null, the expression result is null. 


Expression Examples 


This example performs a bitwise inclusive OR operation between the variables NumberA and NumberB. 
NumberA contains 3 (00000011) and NumberB contains 9 (00001001). 


@NumberA | @NumberB 


The expression evaluates to 11 (00001011). 
00000011 
00001001 
00001011 


This example performs a bitwise inclusive OR operation between the ReorderPoint and SafetyStockLevel 
columns. 


ReorderPoint | SafetyStockLevel 


If ReorderPoint is 10 and SafetyStockLevel is 8, the expression evaluates to 10 (00001010). 
00001010 
00001000 
00001010 


This example performs a bitwise inclusive OR operation between two integers. 
3 [5 


The expression evaluates to 7 (00000111). 
00000011 


00000101 


00000111 


See Also 


|| (Logical OR) (SSIS Expression) 

‘ (Bitwise Exclusive OR) (SSIS Expression) 
Operator Precedence and Associativity 
Operators (SSIS Expression) 


“ (Bitwise Exclusive OR) (SSIS Expression) 


11/23/2021 * 2 minutes to read « Edit Online 





Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Performs a bitwise exclusive OR operation of two integer values. It compares each bit of its first operand to the 
corresponding bit of its second operand. If one bit is 0 and the other bit is 1, the corresponding result bit is set to 
1. If both bits are 0 or both bits are 1, the corresponding result bit is set to 0. 


Both conditions must be a signed integer data type or both conditions must be an unsigned integer data type. 


Syntax 


integer_expression1 * integer_expression2 


Arguments 


integer_expression1, integer_expression2 
Is any valid expression of a signed or unsigned integer data type. For more information, see Integration Services 
Data Types. 


Result Types 


Determined by data types of the two arguments. For more information, see Integration Services Data Types in 
Expressions. 


Remarks 


If either condition is null, the expression result is null. 


Expression Examples 


This example performs a bitwise exclusive OR operation between variables NumberA and NumberB. 
NumberA contains 3 (00000011) and NumberB contains 7 (00000111). 


@NumberA * @NumberB 


The expression evaluates to 4 (00000100). 
00000011 
00000111 
00000100 


This example performs a bitwise exclusive OR operation between the ReorderPoint and SafetyStockLevel 
columns. 


ReorderPoint * SafetyStockLevel 


If ReorderPoint is 10 and SafetyStockLevel is 8, the expression evaluates to 2 (00000010). 
00001010 
00001000 
00000010 


This example performs a bitwise exclusive OR operation between two integers. 
345 


The expression evaluates to 6 (00000110). 
00000011 
00000101 


00000110 


See Also 


|| (Logical OR) (SSIS Expression) 

| (Bitwise Inclusive OR) (SSIS Expression) 
Operator Precedence and Associativity 
Operators (SSIS Expression) 


& (Bitwise AND) (SSIS Expression) 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Performs a bitwise AND operation of two integer values. It compares each bit of its first operand to the 
corresponding bit of its second operand. If both bits are 1, the corresponding result bit is set to 1. Otherwise, the 
corresponding result bit is set to 0. 


Both conditions must be a signed integer type or both conditions must be an unsigned integer type. 


Syntax 


integer_expression1 & integer_expression2 


Arguments 


integer_expression1, integer_expression2 
Is any valid expression of a signed or unsigned integer data type. For more information, see Integration Services 
Data Types. 


Result Types 


Determined by data types of the two arguments. For more information, see Integration Services Data Types in 
Expressions. 


Remarks 


If either condition is null, the expression result is null. 


Expression Examples 


This example performs a bitwise AND operation between the columns NumberA and NumberB. NumberA 
contains 3 (0000011) and column NumberB contains 7 (00000111). 


NumberA & NumberB 


The expression evaluates to 3 (00000011). 
00000011 
00000111 
00000011 


This example performs a bitwise AND operation between the ReorderPoint and SafetyStockLevel columns. 


ReorderPoint & SafetyStockLevel 


If ReorderPoint is 10 and SafetyStockLevel is 8, the expression evaluates to 8 (00001000). 
00001010 
00001000 
00001000 


This example performs a bitwise AND operation between two integers. 
3&5 


The expression evaluates to 1(00000001). 
00000011 
00000101 


00000001 


See Also 


&& (Logical AND) (SSIS Expression) 
Operator Precedence and Associativity 
Operators (SSIS Expression) 


~ (Bitwise Not) (SSIS Expression) 
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Applies to: Q@ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Performs a bitwise negation of an integer. This operator can be applied to signed and unsigned integer data 
types. 


Syntax 


~integer_expression 


Arguments 


integer_expression 
Is any valid expression of an integer data type. integer_expression is an integer that is transformed into a binary 
number for the bitwise operation. For more information, see Integration Services Data Types. 


Result Types 


Returns the data type of /nteger_expression. 


Remarks 


None 


Expression Examples 


This example performs a bitwise ~ (NOT) operation on the number 170 (0000 0000 1010 1010). The number is 
a signed integer. 


~ 170 


The expression evaluates to -170 (1111111101010101). 


0000000010101010 


1111111101010101 


See Also 


Operator Precedence and Associativity 
Operators (SSIS Expression) 


= (Equal) (SSIS Expression) 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Performs a comparison to determine if two expressions are equal. The expression evaluator automatically 
converts many data types before it performs the comparison. For more information, see Integration Services 
Data Types in Expressions. 


However, some data types require that the expression include an explicit cast before the expression can be 
evaluated successfully. For more information about legal casts between data types, see Cast (SSIS Expression). 


Syntax 


expression1 == expression2 


Arguments 


expression, expression2 


Is any valid expression. 


Result Types 


DT_BOOL 


Remarks 


If either expression in the comparison is null, the comparison result is null. If both expressions are null, the result 
is null. 


The expression set, expression? and expression2, must follow one of these rules: 


e Numeric Both expression? and expression2 must be a numeric data type. The intersection of the data 
types must be a numeric data type, as specified in the rules about the implicit numeric conversions that 
the expression evaluator performs. The intersection of the two numeric data types cannot be null. For 
more information, see Integration Services Data Types in Expressions. 


e Character Both expression? and expression2 must evaluate to either a DI_STR or a DT_WSTR data type. 
The two expressions can evaluate to different string data types. 


NOTE 


String comparisons are case, accent, kana, and width-sensitive. 





e Date, Time, or Date/Time Both expression? and expression2 must evaluate to one of the following 
data types: DT_DBDATE, DT_DATE, DT_DBTIME, DT_DBTIME2, DT_DBTIMESTAMP, DT_DBTIMESTAMP2, 
DT_DBTIMESTAPMOFFSET, or DT_FILETIME. 





NOTE 
The system does not support comparisons between an expression that evaluates to a time data type and an 


expression that evaluates to either a date or a date/time data type. The system generates an error. 








When comparing the expressions, the system applies the following conversion rules in the order listed: 


o When the two expressions evaluate to the same data type, a comparison of that data type is 


performed. 


o If one expression is a DT_DBTIMESTAMPOFFSET data type, the other expression is implicitly 
converted to DT_DBTIMESTAMPOFFSET and a DT_DBTIMESTAMPOFFSET comparison is performed. 
For more information, see Integration Services Data Types in Expressions. 


o If one expression is a DIT_DBTIMESTAMP2 data type, the other expression is implicitly converted to 
DT_DBTIMESTAMP2 and a DT_DBTIMESTAMP2 comparison is performed. 


o If one expression is a DI_DBTIME2 data type, the other expression is implicitly converted to 
DT_DBTIME2, and a DT_DBTIME2 comparison is performed. 


o If one expression is of a type other than DT_DBTIMESTAMPOFFSET, DT_DBTIMESTAMP2, or 
DT_DBTIME2, the expressions are converted to the DT_DBTIMESTAMP data type before they are 
compared. 


When comparing the expressions, the system makes the following assumptions: 


o If each expression is a data type that includes fractional seconds, the system assumes that the data 
type with the least number of digits for fractional seconds has zeros for the remaining digits. 


o If each expression is a date data type, but only one has a time zone offset, the system assumes that 
the date data type without the time zone offset is in Coordinated Universal Time (UTC). 


Logical Both expression? and expression2 must evaluate to a Boolean. 


GUID Both expression7 and expression2 must evaluate to the DT_GUID data type. 


Binary Both expression? and expression2 must evaluate to the DT_BYTES data type. 


BLOB Both expression? and expression2 must evaluate to the same Binary Large Object Block (BLOB) 
data type: DT_TEXT, DT_NTEXT, or DT_IMAGE. 


For more information about data types, see Integration Services Data Types. 


Expression Examples 


This example evaluates to TRUE if the current date is July 4, 2003. For more information, see GETDATE (SSIS 


Expression). 
"7/4/2003" == GETDATE() 


This example evaluates to TRUE if the value in the ListPrice column is 500. 
ListPrice == 500 


This example uses the variable LPrice. It evaluates to TRUE if the value of LPrice is 500. The data type of the 
variable must be numeric for the expression to parse successfully. 


@LPrice == 500 


See Also 


!= (Unequal) (SSIS Expression) 
Operator Precedence and Associativity 
Operators (SSIS Expression) 


|= (Unequal) (SSIS Expression) 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Performs a comparison to determine if two expressions with compatible data types are not equal. The 
expression evaluator automatically converts many data types before it performs the comparison. 


However, some data types require that the expression include an explicit cast before the expression can be 
evaluated successfully. For more information about legal casts between data types, see Cast (SSIS Expression). 


Syntax 


expression1 != expression2 


Arguments 


expression, expression2 
Is any valid expression. 


Result Types 


DT_BOOL 


Remarks 


If either expression in the comparison is null, the comparison result is null. If both expressions are null, the result 
is null. 


The expression set, expression? and expression2, must follow one of these rules: 


e Numeric Both expression? and expression2 must be a numeric data type. The intersection of the data 
types must be a numeric data type, as specified in the rules about the implicit numeric conversions that 
the expression evaluator performs. The intersection of the two numeric data types cannot be null. For 
more information, see Integration Services Data Types in Expressions. 


e Character Both expression7 and expression2 must evaluate to either a DT_STR or a DT_WSTR data type. 
The two expressions can evaluate to different string data types. 





NOTE 


String comparisons are case, accent, kana, and width-sensitive. 








e Date, Time, or Date/Time Both expression? and expression2 must evaluate to one of the following 
data types: DT_DBDATE, DT_DATE, DT_DBTIME, DT_DBTIME2, DT_DBTIMESTAMP, DT_DBTIMESTAMP2, 
DT_DBTIMESTAPMOFFSET, or DT_FILETIME. 





NOTE 


The system does not support comparisons between an expression that evaluates to a time data type and an 


expression that evaluates to either a date or a date/time data type. The system generates an error. 








When comparing the expressions, the system applies the following conversion rules in the order listed: 


o When the two expressions evaluate to the same data type, a comparison of that data type is 


performed. 


o If one expression is a DT_DBTIMESTAMPOFFSET data type, the other expression is implicitly 
converted to DT_DBTIMESTAMPOFFSET and a DT_DBTIMESTAMPOFFSET comparison is performed. 
For more information, see Integration Services Data Types in Expressions. 


o If one expression is a DIT_DBTIMESTAMP2 data type, the other expression is implicitly converted to 
DT_DBTIMESTAMP2 and a DT_DBTIMESTAMP2 comparison is performed. 


o If one expression is a DI_DBTIME2 data type, the other expression is implicitly converted to 
DT_DBTIME2, and a DT_DBTIME2 comparison is performed. 


o If one expression is of a type other than DT_DBTIMESTAMPOFFSET, DT_DBTIMESTAMP2, or 
DT_DBTIME2, the expressions are converted to the DT_DBTIMESTAMP data type before they are 
compared. 


When comparing the expressions, the system makes the following assumptions: 


o If each expression is a data type that includes fractional seconds, the system assumes that the data 
type with the least number of digits for fractional seconds has zeros for the remaining digits. 


o If each expression is a date data type, but only one has a time zone offset, the system assumes that 
the date data type without the time zone offset is in Coordinated Universal Time (UTC). 


Logical Both expression? and expression2 must evaluate to a Boolean. 


GUID Both expression7 and expression2 must evaluate to the DT_GUID data type. 


Binary Both expression? and expression2 must evaluate to the DT_BYTES data type. 


BLOB Both expression? and expression2 must evaluate to the same Binary Large Object Block (BLOB) 
data type: DT_TEXT, DT_NTEXT, or DT_IMAGE. 


For more information about data types, see Integration Services Data Types. 


Expression Examples 


This example evaluates to TRUE only if the current date is not July 4, 2003. For more information, see GETDATE 


(SSIS Expression). 
"7/4/2003" != GETDATE() 

This example evaluates to TRUE if the value in the ListPrice column is not 500. 
ListPrice != 500 


This example uses the variable LPrice. It evaluates to TRUE if the value of LPrice is not 500. The data type on 


the variable must be numeric in order for the expression to parse. 


@LPrice != 500 


See Also 


== (Equal) (SSIS Expression) 
Operator Precedence and Associativity 
Operators (SSIS Expression) 


> (Greater Than) (SSIS Expression) 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Performs a comparison to determine if the first expression is greater than the second one. The expression 
evaluator automatically converts many data types before it performs the comparison. 





NOTE 
This operator does not support comparisons that use the DT_TEXT, DT_NTEXT, or DT_IMAGE data types. 











However, some data types require that the expression include an explicit cast before the expression can be 
evaluated successfully. For more information about legal casts between data types, see Cast (SSIS Expression). 


Syntax 


expression1 > expression2 


Arguments 


expression, expression2 


Is any valid expression. Both expressions must have implicitly convertible data types. 


Result Types 


DT_BOOL 


Remarks 


If either expression in the comparison is null, the comparison result is null. If both expressions are null, the result 
is null. 


The expression set, expression? and expression2, must follow one of these rules: 


e Numeric Both expression? and expression2 must be a numeric data type. The intersection of the data 
types must be a numeric data type as specified in the rules about the implicit numeric conversions that 
the expression evaluator performs. The intersection of the two numeric data types cannot be null. For 
more information, see Integration Services Data Types in Expressions. 


e Character Both expression? and expression2 must evaluate to either a DI_STR or a DT_WSTR data type. 
The two expressions can evaluate to different string data types. 





NOTE 


String comparisons are case, accent, kana, and width-sensitive. 





e Date, Time, or Date/Time Both expression? and expression2 must evaluate to one of the following 


data types: DT_DBDATE, DT_DATE, DT_DBTIME, DT_DBTIME2, DT_DBTIMESTAMP. DT_DBTIMESTAMP2, 
DT_DBTIMESTAPMOFFSET, or DT_FILETIME. 





NOTE 


The system does not support comparisons between an expression that evaluates to a time data type and an 


expression that evaluates to either a date or a date/time data type. The system generates an error. 








When comparing the expressions, the system applies the following conversion rules in the order listed: 


o When the two expressions evaluate to the same data type, a comparison of that data type is 
performed. 


o If one expression is a DT_DBTIMESTAMPOFFSET data type, the other expression is implicitly 
converted to DT_DBTIMESTAMPOFFSET and a DT_DBTIMESTAMPOFFSET comparison is performed. 


For more information, see Integration Services Data Types in Expressions. 


o If one expression is a DT_DBTIMESTAMP2 data type, the other expression is implicitly converted to 
DT_DBTIMESTAMP2 and a DT_DBTIMESTAMP2 comparison is performed. 


o If one expression is a DI_DBTIME2 data type, the other expression is implicitly converted to 
DT_DBTIME2, and a DT_DBTIME2 comparison is performed. 


o If one expression is of a type other than DT_DBTIMESTAMPOFFSET, DT_DBTIMESTAMP2, or 
DT_DBTIME2, the expressions are converted to the DT_DBTIMESTAMP data type before they are 
compared. 


When comparing the expressions, the system makes the following assumptions: 


o If each expression is a data type that includes fractional seconds, the system assumes that the data 
type with the least number of digits for fractional seconds has zeros for the remaining digits. 


o If each expression is a date data type, but only one has a time zone offset, the system assumes that 
the date data type without the time zone offset is in Coordinated Universal Time (UTC). 


For more information about data types, see Integration Services Data Types. 


Expression Examples 


This example evaluates to TRUE if the current date is earlier than July 4, 2003. For more information, see 
GETDATE (SSIS Expression). 


"7/4/2003" > GETDATE() 
This example evaluates to TRUE if the value in the ListPrice column is greater than 500. 
ListPrice > 500 


This example uses the variable LPrice. It evaluates to TRUE if the value of LPrice is greater than 500. The data 
type of the variable must be numeric in order for the expression to parse. 


@LPrice > 500 


See Also 


< (Less Than) (SSIS Expression) 

>= (Greater Than or Equal To) (SSIS Expression) 
<= (Less Than or Equal To) (SSIS Expression) 
== (Equal) (SSIS Expression) 

Operator Precedence and Associativity 
Operators (SSIS Expression) 


< (Less Than) (SSIS Expression) 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Performs a comparison to determine if the first expression is less than the second one. The expression evaluator 
automatically converts many data types before it performs the comparison. 





NOTE 
This operator does not support comparisons that use the DT_TEXT, DT_NTEXT, or DT_IMAGE data types. 











However, some data types require that the expression include an explicit cast before the expression can be 
evaluated successfully. For more information about legal casts between data types, see Cast (SSIS Expression). 


Syntax 


expression1 < expression2 


Arguments 


expression, expression2 


Is any valid expression. 


Result Types 


DT_BOOL 


Remarks 


If either expression in the comparison is null, the comparison result is null. If both expressions are null, the result 
is null. 


The expression set, expression? and expression2, must follow one of these rules: 


e Numeric Both expression? and expression2 must be a numeric data type. The intersection of the data 
types must be a numeric data type as specified in the rules about the implicit numeric conversions that 
the expression evaluator performs. The intersection of the two numeric data types cannot be null. For 
more information, see Integration Services Data Types in Expressions. 


e Character Both expression? and expression2 must evaluate to either a DI_STR or a DT_WSTR data type. 
The two expressions can evaluate to different string data types. 





NOTE 


String comparisons are case, accent, kana, and width-sensitive. 





e Date, Time, or Date/Time Both expression? and expression2 must evaluate to one of the following 


data types: DT_DBDATE, DT_DATE, DT_DBTIME, DT_DBTIME2, DT_DBTIMESTAMP. DT_DBTIMESTAMP2, 
DT_DBTIMESTAPMOFFSET, or DT_FILETIME. 





NOTE 


The system does not support comparisons between an expression that evaluates to a time data type and an 


expression that evaluates to either a date or a date/time data type. The system generates an error. 








When comparing the expressions, the system applies the following conversion rules in the order listed: 


o When the two expressions evaluate to the same data type, a comparison of that data type is 
performed. 


o If one expression is a DT_DBTIMESTAMPOFFSET data type, the other expression is implicitly 
converted to DT_DBTIMESTAMPOFFSET and a DT_DBTIMESTAMPOFFSET comparison is performed. 


For more information, see Integration Services Data Types in Expressions. 


o If one expression is a DT_DBTIMESTAMP2 data type, the other expression is implicitly converted to 
DT_DBTIMESTAMP2 and a DT_DBTIMESTAMP2 comparison is performed. 


o If one expression is a DI_DBTIME2 data type, the other expression is implicitly converted to 
DT_DBTIME2, and a DT_DBTIME2 comparison is performed. 


o If one expression is of a type other than DT_DBTIMESTAMPOFFSET, DT_DBTIMESTAMP2, or 
DT_DBTIME2, the expressions are converted to the DT_DBTIMESTAMP data type before they are 
compared. 


When comparing the expressions, the system makes the following assumptions: 


o If each expression is a data type that includes fractional seconds, the system assumes that the data 
type with the least number of digits for fractional seconds has zeros for the remaining digits. 


o If each expression is a date data type, but only one has a time zone offset, the system assumes that 
the date data type without the time zone offset is in Coordinated Universal Time (UTC). 


For more information about data types, see Integration Services Data Types. 


Expression Examples 


This example evaluates to TRUE if the current date is later than July 4, 2003. For more information, see GETDATE 
(SSIS Expression). 


"7/4/2003" < GETDATE() 
This example evaluates to TRUE if the value in the ListPrice column is less than 500. 
ListPrice < 500 


This example uses the variable LPrice. It evaluates to TRUE if the value of LPrice is less than 500. The data type 
of the variable must be numeric in order for the expression to parse. 


@LPrice < 500 


See Also 


> (Greater Than) (SSIS Expression) 

>= (Greater Than or Equal To) (SSIS Expression) 
<= (Less Than or Equal To) (SSIS Expression) 
Operator Precedence and Associativity 
Operators (SSIS Expression) 


>= (Greater Than or Equal To) (SSIS Expression) 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Performs a comparison to determine if the first expression is greater than or equal to the second one. The 
expression evaluator automatically converts many data types before it performs the comparison. 





NOTE 
This operator does not support comparisons that use the DT_TEXT, DT_NTEXT, or DT_IMAGE data types. 











However, some data types require that the expression include an explicit cast before the expression can be 
evaluated successfully. For more information about legal casts between data types, see Cast (SSIS Expression). 





NOTE 


There are no spaces between the two characters in this operator. 





Syntax 


expression1 >= expression2 


Arguments 


expression, expression2 


Is any valid expression. 


Result Types 


DT_BOOL 


Remarks 


If either expression in the comparison is null, the comparison result is null. If both expressions are null, the result 
is null. 


The expression set, expression? and expression2, must follow one of these rules: 


e Numeric Both expression? and expression2 must be a numeric data type. The intersection of the data 
types must be a numeric data type as specified in the rules about the implicit numeric conversions that 
the expression evaluator performs. The intersection of the two numeric data types cannot be null. For 
more information, see Integration Services Data Types in Expressions. 


e Character Both expression? and expression2 must evaluate to either a DI_STR or a DT_WSTR data type. 
The two expressions can evaluate to different string data types. 





NOTE 


String comparisons are case, accent, kana, and width-sensitive. 





e Date, Time, or Date/Time Both expression? and expression2 must evaluate to one of the following 
data types: DT_DBDATE, DT_DATE, DT_DBTIME, DT_DBTIME2, DT_DBTIMESTAMP. DT_DBTIMESTAMP2, 
DT_DBTIMESTAPMOFFSET, or DT_FILETIME. 





NOTE 


The system does not support comparisons between an expression that evaluates to a time data type and an 


expression that evaluates to either a date or a date/time data type. The system generates an error. 








When comparing the expressions, the system applies the following conversion rules in the order listed: 


o When the two expressions evaluate to the same data type, a comparison of that data type is 
performed. 


o If one expression is a DT_DBTIMESTAMPOFFSET data type, the other expression is implicitly 
converted to DT_DBTIMESTAMPOFFSET and a DT_DBTIMESTAMPOFFSET comparison is performed. 
For more information, see Integration Services Data Types in Expressions. 


o If one expression is a DT_DBTIMESTAMP2 data type, the other expression is implicitly converted to 
DT_DBTIMESTAMP2 and a DT_DBTIMESTAMP2 comparison is performed. 


o If one expression is a DT_DBTIME2 data type, the other expression is implicitly converted to 
DT_DBTIME2, and a DT_DBTIME2 comparison is performed. 


o If one expression is of a type other than DT_DBTIMESTAMPOFFSET, DT_DBTIMESTAMP2, or 
DT_DBTIME2, the expressions are converted to the DT_DBTIMESTAMP data type before they are 
compared. 


When comparing the expressions, the system makes the following assumptions: 


© If each expression is a data type that includes fractional seconds, the system assumes that the data 
type with the least number of digits for fractional seconds has zeros for the remaining digits. 


o If each expression is a date data type, but only one has a time zone offset, the system assumes that 
the date data type without the time zone offset is in Coordinated Universal Time (UTC). 


For more information about data types, see Integration Services Data Types. 


Expression Examples 


This example evaluates to TRUE if the current date is July 4, 2003 or earlier. For more information, see GETDATE 
(SSIS Expression). 


"7/4/2003" >= GETDATE() 
This example evaluates to TRUE if the value in the ListPrice column is greater than or equal to 500. 
ListPrice >= 500 


This example uses the variable LPrice. It evaluates to TRUE if the value of LPrice is greater than or equal to 500. 
The data type of the variable must be numeric in order for the expression to parse. 


@LPrice >= 500 


See Also 


> (Greater Than) (SSIS Expression) 

< (Less Than) (SSIS Expression) 

<= (Less Than or Equal To) (SSIS Expression) 
Operator Precedence and Associativity 
Operators (SSIS Expression) 


<= (Less Than or Equal To) (SSIS Expression) 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Performs a comparison to determine if the first expression is less than or equal to the second one. The 
expression evaluator automatically converts many data types before it performs the comparison. 





NOTE 
This operator does not support comparisons that use the DT_TEXT, DT_NTEXT, or DT_IMAGE data types. 











However, some data types require that the expression include an explicit cast before the expression can be 
evaluated successfully. For more information about legal casts between data types, see Cast (SSIS Expression). 





NOTE 


There are no spaces between the two characters in this operator. 





Syntax 


expression1 <= expression2 


Arguments 


expression, expression2 


Is any valid expression. 


Result Types 


DT_BOOL 


Remarks 


If either expression in the comparison is null, the comparison result is null. If both expressions are null, the result 
is null. 


The expression set, expression? and expression2, must follow one of these rules: 


e Numeric Both expression? and expression2 must be a numeric data type. The intersection of the data 
types must be a numeric data type as specified in the rules about the implicit numeric conversions that 
the expression evaluator performs. The intersection of the two numeric data types cannot be null. For 
more information, see Integration Services Data Types in Expressions. 


e Character Both expression? and expression2 must evaluate to either a DI_STR or a DT_WSTR data type. 
The two expressions can evaluate to different string data types. 





NOTE 


String comparisons are case, accent, kana, and width-sensitive. 





e Date, Time, or Date/Time Both expression? and expression2 must evaluate to one of the following 
data types: DT_DBDATE, DT_DATE, DT_DBTIME, DT_DBTIME2, DT_DBTIMESTAMP. DT_DBTIMESTAMP2, 
DT_DBTIMESTAPMOFFSET, or DT_FILETIME. 





NOTE 


The system does not support comparisons between an expression that evaluates to a time data type and an 


expression that evaluates to either a date or a date/time data type. The system generates an error. 








When comparing the expressions, the system applies the following conversion rules in the order listed: 


o When the two expressions evaluate to the same data type, a comparison of that data type is 
performed. 


o If one expression is a DT_DBTIMESTAMPOFFSET data type, the other expression is implicitly 
converted to DT_DBTIMESTAMPOFFSET and a DT_DBTIMESTAMPOFFSET comparison is performed. 
For more information, see Integration Services Data Types in Expressions. 


o If one expression is a DT_DBTIMESTAMP2 data type, the other expression is implicitly converted to 
DT_DBTIMESTAMP2 and a DT_DBTIMESTAMP2 comparison is performed. 


o If one expression is a DT_DBTIME2 data type, the other expression is implicitly converted to 
DT_DBTIME2, and a DT_DBTIME2 comparison is performed. 


o If one expression is of a type other than DT_DBTIMESTAMPOFFSET, DT_DBTIMESTAMP2, or 
DT_DBTIME2, the expressions are converted to the DT_DBTIMESTAMP data type before they are 
compared. 


When comparing the expressions, the system makes the following assumptions: 


© If each expression is a data type that includes fractional seconds, the system assumes that the data 
type with the least number of digits for fractional seconds has zeros for the remaining digits. 


o If each expression is a date data type, but only one has a time zone offset, the system assumes that 
the date data type without the time zone offset is in Coordinated Universal Time (UTC). 


For more information about data types, see Integration Services Data Types. 


Expression Examples 


This example evaluates to TRUE if the current date is July 4, 2003 or later. For more information, see GETDATE 
(SSIS Expression). 


"7/4/2003" <= GETDATE() 
This example evaluates to TRUE if the value in the ListPrice column is less than or equal to 500. 
ListPrice <= 500 


This example evaluates the variable LPrice and evaluates to TRUE if the value is less than or equal to 500. The 
data type of LPrice must be numeric in order for the expression to parse. 


@LPrice <= 500 


See Also 


> (Greater Than) (SSIS Expression) 

< (Less Than) (SSIS Expression) 

>= (Greater Than or Equal To) (SSIS Expression) 
Operator Precedence and Associativity 
Operators (SSIS Expression) 


? : (Conditional) (SSIS Expression) 


11/23/2021 * 3 minutes to read « Edit Online 





Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Returns one of two expressions based on the evaluation of a Boolean expression. If the Boolean expression 
evaluates to TRUE, then the first expression is evaluated and the result is the expression result. If the Boolean 
expression evaluates to FALSE then the second expression is evaluated and its result is the expression result. 


Syntax 


boolean_expression?expression1:expression2 


Arguments 


boolean_expression 
Is any valid expression that evaluates to TRUE, FALSE, or NULL. 


expression? 


Is any valid expression. 


expression2 
Is any valid expression. 


Result Types 


The data type of expression? or expression2. 


Remarks 


If the boolean_expression evaluates to NULL, the expression result is NULL. If a selected expression, either 
expression? or expression2 is NULL, the result is NULL. If a selected expression is not NULL, but the one not 
selected is NULL, the result is the value of the selected expression. 


If expression? and expression2 have the same data type, the result is that data type. The following additional 
rules apply to result types: 


e The DT_TEXT data type requires that expression? and expression2 have the same code page. 
e The length of a result with the DT_BYTES data type is the length of the longer argument. 
The expression set, expression? and expression2, must evaluate to valid data types and follow one of these rules: 


e Numeric Both expression? and expression2 must be a numeric data type. The intersection of the data 
types must be a numeric data type as specified in the rules about the implicit numeric conversions that 
the expression evaluator performs. The intersection of the two numeric data types cannot be null. For 
more information, see Integration Services Data Types in Expressions. 


e String Both expression? and expression2 must be a string data type: DT_STR or DT_WSTR. The two 
expressions can evaluate to different string data types. The result has the DI_WSTR data type with a 


length of the longer argument. 


e Date, Time, or Date/Time Both expression7 and expression2 must evaluate to one of the following 
data types: DT_DBDATE, DT_DATE, DT_DBTIME, DT_DBTIME2, DT_DBTIMESTAMP, DT_DBTIMESTAMP2, 
DT_DBTIMESTAPMOFFSET, or DT_FILETIME. 





NOTE 


The system does not support comparisons between an expression that evaluates to a time data type and an 


expression that evaluates to either a date or a date/time data type. The system generates an error. 








When comparing the expressions, the system applies the following conversion rules in the order listed: 


o When the two expressions evaluate to the same data type, a comparison of that data type is 
performed. 


o If one expression is a DT_DBTIMESTAMPOFFSET data type, the other expression is implicitly 
converted to DT_DBTIMESTAMPOFFSET and a DT_DBTIMESTAMPOFFSET comparison is performed. 


For more information, see Integration Services Data Types in Expressions. 


o If one expression is a DT_DBTIMESTAMP2 data type, the other expression is implicitly converted to 
DT_DBTIMESTAMP2 and a DT_DBTIMESTAMP2 comparison is performed. 


o If one expression is a DT_DBTIME2 data type, the other expression is implicitly converted to 
DT_DBTIME2, and a DT_DBTIME2 comparison is performed. 


o If one expression is of a type other than DT_DBTIMESTAMPOFFSET, DT_DBTIMESTAMP2, or 
DT_DBTIME2, the expressions are converted to the DT_DBTIMESTAMP data type before they are 
compared. 


When comparing the expressions, the system makes the following assumptions: 


o If each expression is a data type that includes fractional seconds, the system assumes that the data 
type with the least number of digits for fractional seconds has zeros for the remaining digits. 


o If each expression is a date data type, but only one has a time zone offset, the system assumes that 
the date data type without the time zone offset is in Coordinated Universal Time (UTC). 


For more information about data types, see Integration Services Data Types. 


Expression Examples 


This example shows an expression that conditionally evaluates to savannah or unknown . 
@AnimalName == "Elephant"? "savannah": "unknown" 


This example shows an expression that references a ListPrice column. ListPrice has the DT_CY data type. The 
expression conditionally multiplies ListPrice by .2 or .1. 


ListPrice < 350.00 ? ListPrice * .2 3 ListPrice * .2 


See Also 


Operator Precedence and Associativity 
Operators (SSIS Expression) 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


The expression language includes a set of functions for use in expressions. An expression can use a single 
function, but typically an expression combines functions with operators and uses multiple functions. 


The functions can be categorized into the following groups: 


e Mathematical functions that perform calculations based on numeric input values provided as parameters 
to the functions and return numeric values. 


e String functions that perform operations on string or hexadecimal input values and return a string or 
numeric value. 


e Date and time functions that perform operations on date and time values and return string, numeric, or 
date and time values. 


e System functions that return information about an expression. 


The expression language provides the following mathematical functions. 


FUNCTION DESCRIPTION 

ABS (SSIS Expression) Returns the absolute, positive value of a numeric expression. 
EXP (SSIS Expression) Returns the exponent to base e of the specified expression. 
CEILING (SSIS Expression) Returns the smallest integer that is greater than or equal to 


a numeric expression. 


FLOOR (SSIS Expression) Returns the largest integer that is less than or equal to a 
numeric expression. 


LN (SSIS Expression) Returns the natural logarithm of a numeric expression. 

LOG (SSIS Expression) Returns the base-10 logarithm of a numeric expression. 
POWER (SSIS Expression) Returns the result of raising a numeric expression to a power. 
ROUND (SSIS Expression) Returns a numeric expression that is rounded to the 


specified length or precision. . 


SIGN (SSIS Expression) Returns the positive (+), negative (-), or zero (0) sign of a 
numeric expression. 


SQUARE (SSIS Expression) Returns the square of a numeric expression. 
SQRT (SSIS Expression) Returns the square root of a numeric expression. 


The expression evaluator provides the following string functions. 


FUNCTION 


CODEPOINT (SSIS Expression) 


FINDSTRING (SSIS Expression) 


HEX (SSIS Expression) 


LEN (SSIS Expression) 


LEFT (SSIS Expression) 


LOWER (SSIS Expression) 


LTRIM (SSIS Expression) 


REPLACE (SSIS Expression) 


REPLICATE (SSIS Expression) 


REVERSE (SSIS Expression) 


RIGHT (SSIS Expression) 


RTRIM (SSIS Expression) 


SUBSTRING (SSIS Expression) 


TRIM (SSIS Expression) 


UPPER (SSIS Expression) 


DESCRIPTION 


Returns the Unicode code value of the leftmost character of 
a character expression. 


Returns the one-based index of the specified occurrence of a 
character string within an expression. 


Returns a string representing the hexadecimal value of an 
integer. 


Returns the number of characters in a character expression. 


Returns the specified number of characters from the leftmost 
portion of the given character expression. 


Returns a character expression after converting uppercase 
characters to lowercase characters. 


Returns a character expression after removing leading 
spaces. 


Returns a character expression after replacing a string within 
the expression with either a different string or an empty 
string. 


Returns a character expression, replicated a specified number 
of times. 


Returns a character expression in reverse order. 


Returns the specified number of characters from the 
rightmost portion of the given character expression. 


Returns a character expression after removing trailing spaces. 


Returns a part of a character expression. 


Returns a character expression after removing leading and 
trailing spaces. 


Returns a character expression after converting lowercase 
characters to uppercase characters. 


The expression evaluator provides the following date and time functions. 


FUNCTION 


DATEADD (SSIS Expression) 


DATEDIFF (SSIS Expression) 


DATEPART (SSIS Expression) 


DESCRIPTION 


Returns a new DT_DBTIMESTAMP value by adding a date or 
time interval to a specified date. 


Returns the number of date and time boundaries crossed 
between two specified dates. 


Returns an integer representing a datepart of a date. 


FUNCTION DESCRIPTION 


DAY (SSIS Expression) Returns an integer that represents the day of the specified 
date. 

GETDATE (SSIS Expression) Returns the current date of the system. 

GETUTCDATE (SSIS Expression) Returns the current date of the system in UTC time 


(Universal Time Coordinate or Greenwich Mean Time). 


MONTH (SSIS Expression) Returns an integer that represents the month of the 
specified date. 


YEAR (SSIS Expression) Returns an integer that represents the year of the specified 
date. 


The expression evaluator provides the following null functions. 


FUNCTION DESCRIPTION 

ISNULL (SSIS Expression) Returns a Boolean result based on whether an expression is 
null. 

NULL (SSIS Expression) Returns a null value of a requested data type. 


Expression names are shown in uppercase characters, but expression names are not case-sensitive. For example, 


using "null" works as well as using "NULL". 


See Also 


Operators (SSIS Expression) 
Examples of Advanced Integration Services Expressions 
Integration Services (SSIS) Expressions 


ABS (SSIS Expression) 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Returns the absolute, positive value of a numeric expression. 


Syntax 


ABS(numeric_expression) 


Arguments 


numeric_expression 


Is a signed or unsigned numeric expression. 


Result Types 


The data type of the numeric expression submitted to the function. 


Remarks 


ABS returns a null result if the argument is null. 


Expression Examples 


These examples apply the ABS function to a positive and a negative number. Both return 1.23. 


ABS(-1.23) 
ABS(1.23) 


This example applies the ABS function to an expression that subtracts values in the variables HighTemperature 
and LowTempature. 


ABS(@HighTemperature - @LowTemperature) 


See Also 


Functions (SSIS Expression) 


@aTRINICR OSS Na cotessiela)) 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Returns the smallest integer that is greater than or equal to a numeric expression. 


Syntax 


CEILING(numeric_expression) 


Arguments 


numeric_expression 
Is a valid numeric expression. 


Result Types 


The data type of the numeric expression submitted to the function. 


Remarks 


CEILING returns a null result if the argument is null. 


Expression Examples 


These examples apply the CEILING function to positive, negative, and zero values. 
CEILING(123.74) 

Returns 124.00 
CEILING(-124.27) 

Returns -124.00 
CEILING(@.0@) 


Returns 0.00 


See Also 


FLOOR (SSIS Expression) 
Functions (SSIS Expression) 


CODEPOINT (SSIS Expression) 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Returns the Unicode code point of the leftmost character of a character expression. 


Syntax 


CODEPOINT(character_expression) 


Arguments 


character_expression 
Is a character expression whose leftmost character will be evaluated. 


Result Types 


DT_UI2 


Remarks 


character_expression must have the DT_WSTR data type. 


CODEPOINT returns a null result if character_expression is null or an empty string. 


Expression Examples 


This example uses a string literal. The return result is 77, the Unicode code point for M. 


CODEPOINT("Mountain Bike") 


This example uses a variable. If Name is Touring Front Wheel, the return result is 84, the Unicode code point for 
T. 


CODEPOINT (@Name) 


See Also 


Functions (SSIS Expression) 


DYN END] DRGs) si .(0)(-5116)8) 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Returns a new DT_DBTIMESTAMP value after adding a number that represents a date or time interval to the 
specified datepart in a date. The number parameter must evaluate to an integer, and the date parameter must 
evaluate to a valid date. 


Syntax 


DATEADD(datepart, number, date) 


Arguments 


datepart 
Is the parameter that specifies which part of the date to add a number to. 


number 
Is the value used to increment datepart The value must be an integer value that is known when the expression 
is parsed. 


date 


Is an expression that returns a valid date or a string in date format. 


Result Types 


DT_DBTIMESTAMP 


Remarks 


The following table lists the dateparts and abbreviations recognized by the expression evaluator. Datepart 
names are not case sensitive. 


DATEPART ABBREVIATIONS 
Year yy: YYYY 
Quarter qq, 4 

Month mm, m 
Dayofyear dy, y 

Day dd, d 


Week wk, ww 


DATEPART ABBREVIATIONS 


Weekday dw, w 
Hour Hh 
Minute mi, n 
Second ss, S 
Millisecond Ms 


The number argument must be available when the expression is parsed. The argument can be a constant or a 


variable. You cannot use column values because the values are not known when the expression is parsed. 


The datepart argument must be enclosed by quotation marks. 


A date literal must be explicitly cast to one of the date data types. For more information, see Integration Services 


Data Types. 


DATEADD returns a null result if the argument is null. 


Errors occur if a date is invalid, if the date or time unit is not a string, or if the increment is not a static integer. 


SSIS Expression Examples 


This example adds one month to the current date. 


DATEADD("Month", 1,GETDATE()) 


This example adds 21 days to the dates in the ModifiedDate column. 


DATEADD("day", 21, ModifiedDate) 
This example adds 2 years to a literal date. 


DATEADD("yyyy", 2, (DT_DBTIMESTAMP)"8/6/2003") 


See Also 


DATEDIFF (SSIS Expression) 
DATEPART (SSIS Expression) 
DAY (SSIS Expression) 
MONTH (SSIS Expression) 
YEAR (SSIS Expression) 
Functions (SSIS Expression) 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Returns the number of date and time boundaries crossed between two specified dates. The datepart parameter 
identifies which date and time boundaries to compare. 


Syntax 


DATEDIFF(datepart, startdate, endate) 


Arguments 


datepart 


Is the parameter that specifies which part of the date to compare and return a value for. 


startdate 
Is the start date of the interval. 


endate 
Is the end date of the interval. 


Result Types 


DT_|4 


Remarks 


The following table lists the dateparts and abbreviations recognized by the expression evaluator. 


DATEPART ABBREVIATIONS 
Year yy, yyyy 
Quarter qq, 4 

Month mm, m 
Dayofyear dy, y 

Day dd, d 

Week wk, ww 
Weekday dw, w 


Hour Hh 


DATEPART ABBREVIATIONS 


Minute mi, n 
Second ss, S 
Millisecond Ms 


DATEDIFF returns a null result if any argument is null. 


A date literal must be explicitly cast to one of the date data types. For more information, see Integration Services 
Data Types. 


An error occurs if a date is not valid, if the date or time unit is not a string, if the start date is not a date, or if the 
end date is not a date. 


If the end date is earlier than the start date, the function returns a negative number. If the start and end dates are 


equal or fall within the same interval, the function returns zero. 


SSIS Expression Examples 


This example calculates the number of days between two date literals. If the date is in "mm/dd/yyyy” format, the 
function returns 7. 


DATEDIFF("dd", (DT_DBTIMESTAMP)"8/1/2003", (DT_DBTIMESTAMP) "8/8/2003" ) 
This example returns the number of months between a date literal and the current date. 
DATEDIFF("mm", (DT_DBTIMESTAMP) "8/1/2003", GETDATE()) 


This example returns the number of weeks between the date in the ModifiedDate column and the 
YearEndDate variable. If YearEndDate has a date data type, no explicit casting is required. 


DATEDIFF("Week", ModifiedDate,@YearEndDate) 


See Also 


DATEADD (SSIS Expression) 
DATEPART (SSIS Expression) 
DAY (SSIS Expression) 
MONTH (SSIS Expression) 
YEAR (SSIS Expression) 
Functions (SSIS Expression) 


DATEPART (SSIS Expression) 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Returns an integer representing a datepart of a date. 


Syntax 


DATEPART(datepart, date) 


Arguments 


datepart 
Is the parameter that specifies for which part of the date to return a new value. 


date 
Is an expression that returns a valid date or a string in date format. 


Result Types 


DT_|4 


Remarks 


DATEPART returns a null result if the argument is null. 


A date literal must be explicitly cast to one of the date data types. For more information, see Integration Services 
Data Types. 


The following table lists the dateparts and abbreviations recognized by the expression evaluator. Datepart 
names are not case sensitive. 


DATEPART ABBREVIATIONS 
Year yy: YYYY 
Quarter qq, 4 

Month mm, m 
Dayofyear dy, y 

Day dd, d 

Week wk, ww 


Weekday dw 


DATEPART ABBREVIATIONS 


Hour Hh, hh, HH 
Minute mi, n 
Second ss, S 
Millisecond Ms 


SSIS Expression Examples 


This example returns the integer that represents the month in a date literal. If the date is in mm/dd/yyyy" format, 
this example returns 11. 


DATEPART(“month", (DT_DBTIMESTAMP) "11/04/2002" ) 


This example returns the integer that represents the day in the ModifiedDate column. 


DATEPART("dd", ModifiedDate) 


This example returns the integer that represents the year of the current date. 


DATEPART("“yy", GETDATE() ) 
These examples all return 19. 


DATEPART("HH", (DT_DATE) "2020-09-02 19:24" ) 
DATEPART("hh", (DT_DATE) "2020-09-02 19:24" ) 
DATEPART("Hh", (DT_DATE) "2020-09-02 19:24" ) 


See Also 


DATEADD (SSIS Expression) 
DATEDIFF (SSIS Expression) 
DAY (SSIS Expression) 
MONTH (SSIS Expression) 
YEAR (SSIS Expression) 
Functions (SSIS Expression) 


DAY (SSIS Expression) 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Returns an integer that represents the day datepart of a date. 


Syntax 


DAY (date) 


Arguments 


date 
Is an expression that returns a valid date or a string in date format. 


Result Types 


DT_|4 


Remarks 


DAY returns a null result if the argument is null. 


A date literal must be explicitly cast to one of the date data types. For more information, see Integration Services 
Data Types. 





NOTE 


The expression fails to validate when a date literal is explicitly cast to one of these date data types: 
DT_DBTIMESTAMPOFFSET and DT_DBTIMESTAMP2. 











Using the DAY function is briefer but equivalent to using DATEPART("Day”, date). 


Expression Examples 


This example returns the number of the day in a date literal. If the date format is in "mm/dd/yyyy" format, this 
example returns 23. 


DAY ( (DT_DBTIMESTAMP ) "11/23/2002" ) 


This example returns the integer that represents the day in the ModifiedDate column. 


DAY (ModifiedDate) 


This example returns the integer that represents the day of the current date. 


DAY (GETDATE()) 


See Also 


DATEADD (SSIS Expression) 
DATEDIFF (SSIS Expression) 
DATEPART (SSIS Expression) 
MONTH (SSIS Expression) 
YEAR (SSIS Expression) 
Functions (SSIS Expression) 


EXP (SSIS Expression) 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Returns the exponent to base e of a numeric expression. The EXP function complements the action of the LN 
function and is sometimes referred to as the antilogarithm. 


Syntax 


EXP(numeric_expression) 


Arguments 


numeric_expression 


Is a valid numeric expression. 


Result Types 


DT_R8& 


Remarks 


The numeric expression is cast to the DT_R8 data type before the exponent is computed. For more information, 
see Integration Services Data Types. 


The return result is always a positive number. 


Expression Examples 


These examples apply the EXP function to positive and negative values and to zero. 
EXP(74) 

Returns 1.373382979540176E+32. 
EXP(-27) 

Returns 1.879528816539083E-12. 
EXP(@) 

Returns 1. 


See Also 


LOG (SSIS Expression) 


Functions (SSIS Expression) 


FINDSTRING (SSIS Expression) 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Returns the location of the specified occurrence of a string within a character expression. The return result is the 
one-based index of the occurrence. The string parameter must evaluate to a character expression, and the 
occurrence parameter must evaluate to an integer. If the string is not found, the return value is 0. If the string 
occurs fewer times than the occurrence argument specifies, the return value is 0. 


Syntax 


FINDSTRING(character_expression, searchstring, occurrence) 


Arguments 


character_expression 


Is the character string to search in. 


searchstring 
Is the character string to search for. 


occurrence 


Is a signed or unsigned integer specifying which occurrence of searchstring to report. 


Result Types 


DT_|4 


Remarks 


FINDSTRING works only with the DT_WSTR data type. character_expression and searchstring arguments that are 
string literals or data columns with the DT_STR data type are implicitly cast to the DT_WSTR data type before 
FINDSTRING performs its operation. Other data types must be explicitly cast to the DI_WSTR data type. For 
more information, see Integration Services Data Types and Cast (SSIS Expression). 


FINDSTRING returns null if either character_expression or searchstring are null. 


Use a value of 1 in the occurrence argument to get the index of the first occurrence, 2 for the second occurrence 
and so forth. 


The occurrence must be an integer with a value greater than 0. 


Expression Examples 


This example uses a string literal. It returns the value 11. 


FINDSTRING("New York, NY, NY", "NY", 1) 


This example uses a string literal. Because the string "NY" occurs only two times, the return result is 0. 


FINDSTRING("New York, NY, NY", "NY", 3) 


This example uses the Name column. It returns the location of the second "n" in the Name column. The return 
result varies depending on the value in Name. If Name contains Anderson, the function returns 8. 


FINDSTRING(Name, "n", 2) 


This example uses the Name and Size columns. It returns the location of the leftmost character of the Size 
value in the Name column. The return result varies depending on column values. If Name contains 
Mountain,500Red,42 and Size contains 42, the return result is 17. 


FINDSTRING(Name, Size,1) 


See Also 


REPLACE (SSIS Expression) 
Functions (SSIS Expression) 


FLOOR (SSIS Expression) 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Returns the largest integer that is less than or equal to a numeric expression. 


Syntax 


FLOOR(numeric_expression) 


Arguments 


numeric_expression 
Is a valid numeric expression. 


Result Types 


The numeric data type of the argument expression. The result is the integer portion of the calculated value in the 
same data type as numeric_expression. 


Remarks 


FLOOR returns a null result if the argument is null. 


Expression Examples 


These examples apply the FLOOR function to positive, negative, and zero values. 
FLOOR (123.45) 

Returns 123.00 
FLOOR(-123.45) 

Returns -124.00 
FLOOR (@.@@) 


Returns 0.00 


See Also 


CEILING (SSIS Expression) 
Functions (SSIS Expression) 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Returns the current date of the system in a DT_DBTIMESTAMP format. The GETDATE function takes no 
arguments. 





NOTE 
The length of the return result from the GETDATE function is 29 characters. 











Syntax 


GETDATE() 


Arguments 


None 


Result Types 


DT_DBTIMESTAMP 


Expression Examples 


This example returns the year of the current date. 
DATEPART ( "year" , GETDATE()) 

This example returns the number of days between a date in the ModifiedDate column and the current date. 
DATEDIFF("dd" ,ModifiedDate,GETDATE()) 

This example adds three months to the current date. 


DATEADD("Month", 3, GETDATE()) 


See Also 


GETUTCDATE (SSIS Expression) 
Functions (SSIS Expression) 


GETUTCDATE (SSIS Expression) 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Returns the current date of the system in UTC time (Universal Time Coordinate or Greenwich Mean Time) using 
a DT_DBTIMESTAMP format. The GETUTCDATE function takes no arguments. 


Syntax 


GETUTCDATE() 


Arguments 


None 


Result Types 


DT_DBTIMESTAMP 


Expression Examples 


This example returns the year of the current date in UTC time. 


DATEPART( "year", GETUTCDATE() ) 


This example returns the number of days between a date in the ModifiedDate column and the current UTC 
date. 


DATEDIFF("dd" ,ModifiedDate, GETUTCDATE()) 
This example adds three months to the current UTC date. 


DATEADD("Month" , 3, GETUTCDATE() ) 


See Also 


GETDATE (SSIS Expression) 


Functions (SSIS Expression) 


HEX (SSIS Expression) 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Returns a string representing the hexadecimal value of an integer. 


Syntax 


HEX(integer_expression) 


Arguments 


integer_expression 
Is a signed or unsigned integer. 


Result Types 


DT_WSTR 


Remarks 


HEX returns null if integer_expression is null. 


The integer_expression argument must evaluate to an integer. For more information, see Integration Services 
Data Types. 


The return result does not include qualifiers such as the Ox prefix. To include a prefix, use the + (Concatenate) 
operator. For more information, see + (Concatenate) (SSIS Expression). 


The letters A - F, used in HEX notations, appear as uppercase characters. 
The length of the resulting string for integer data types is as follows: 

e DT_I1 and DT_UI1 return a string with a maximum length of 2. 

e DT_I2 and DT_UI2 return a string with a maximum length of 4. 

e DT_I4 and DT_UI4 return a string with a maximum length of 8. 


e DT_I8 and DT_UI8 return a string with a maximum length of 16. 


Expression Examples 


This example uses a numeric literal. The function returns the value 190. 


HEX(4@0) 


This example uses the ReorderPoint column. The column data type is smallint. If ReorderPoint is 750, the 
function returns 2EE. 


HEX(ReorderPoint ) 


This example uses LocalelD, a system variable. If LocalelD is 1033, the function returns 409. 


HEX(@LocaleID) 


See Also 


Functions (SSIS Expression) 


ISNULL (SSIS Expression) 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Returns a Boolean result based on whether an expression is null. 


Syntax 


ISNULL (expression) 


Arguments 


expression 


Is a valid expression of any data type. 


Result Types 


DT_BOOL 


Expression Examples 


This example returns TRUE if the DiscontinuedDate column contains a null value. 


ISNULL (DiscontinuedDate) 


This example returns "Unknown last name’ if the value in the LastName column is null, otherwise it returns the 
value in LastName. 


ISNULL(LastName)? "Unknown last name":LastName 


This example always returns TRUE if the DaysToManufacture column is null, regardless of the value of the 
variable AddDays. 


ISNULL(DaysToManufacture + @AddDays) 


See Also 


Functions (SSIS Expression) 
COALESCE (Transact-SQL) 


LEFT (SSIS Expression) 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Returns the specified number of characters from the leftmost portion of the given character expression. 


Syntax 


LEFT(character_expression, number ) 


Arguments 


character_expression 
Is a character expression from which to extract characters. 


number 
Is an integer expression that indicates the number of characters to be returned. 


Result Types 


DT_WSTR 


Remarks 

If number is greater than the length of character_expression, the function returns character_expression. 
If number is zero, the function returns a zero-length string. 

If number is a negative number, the function returns an error. 

The number argument can take variables and columns. 


LEFT works only with the DT_WSTR data type. A character_expression argument that is a string literal or a data 
column with the DT_STR data type is implicitly cast to the DT_WSTR data type before LEFT performs its 
operation. Other data types must be explicitly cast to the DT_WSTR data type. For more information, see 
Integration Services Data Types and Cast (SSIS Expression). 


LEFT returns a null result if either argument is null. 


Expression Examples 


The following example uses a string literal. The return result is "Mountain" . 


LEFT("Mountain Bike", 8) 


See Also 


RIGHT (SSIS Expression) 
Functions (SSIS Expression) 


LEN (SSIS Expression) 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Returns the number of characters in a character expression. If the string includes leading and trailing blanks, the 
function includes them in the count. LEN returns identical values for the same string of single and double byte 
characters. 


Syntax 


LEN(character_expression) 


Arguments 


character_expression 
Is the expression to evaluate. 


Result Types 


DT_|4 


Remarks 


The character_expression argument can be a DT_WSTR, DT_TEXT, DT_NTEXT, or DT_IMAGE data type. For more 
information, see Integration Services Data Types. 


If character_expression is a string literal or a data column with the DT_STR data type, it is implicitly cast to the 
DT_WSTR data type before LEN performs its operation. Other data types must be explicitly cast to the DI_WSTR 
data type. For more information, see Cast (SSIS Expression). 


If the argument passed to the LEN function has a Binary Large Object Block (BLOB) data type, such as DT_TEXT, 
DT_NTEXT, or DT_IMAGE, the function returns a byte count. 


LEN returns a null result if the argument is null. 


Expression Examples 


This example returns the length of a string literal. The return result is 12. 
LEN("Ball Bearing") 


This example returns the difference between the length of values in the FirstName and LastName columns. 


LEN(FirstName) - LEN(LastName) 


Returns the length of a computer name using the System variable MachineName. 


LEN(@MachineName) 


See Also 


Functions (SSIS Expression) 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Returns the natural logarithm of a numeric expression. 


Syntax 


LN(numeric_expression) 


Arguments 


numeric_expression 


Is a valid non-zero and non-negative numeric expression. 


Result Types 


DT_R8& 


Remarks 


The numeric expression is cast to the DT_R8 data type before the logarithm is computed. For more information, 
see Integration Services Data Types. 


If numeric_expression evaluates to zero or a negative value, the return result is null. 


Expression Examples 


This example uses a numeric literal. The function returns the value 3.737766961828337. 
LN(42) 

This example uses the column Length. If the column value is 53.99, the function returns 3.9887988442302. 
LN(Length) 


This example uses the variable Length. The variable must have a numeric data type or the expression must 
include an explicit cast to a numeric data type. If Length is 234.567, the function returns 5.45774126708797. 


LN(@Length) 


See Also 


LOG (SSIS Expression) 
Functions (SSIS Expression) 


LOG (SSIS Expression) 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Returns the base-10 logarithm of a numeric expression. 


Syntax 


LOG(numeric_expression) 


Arguments 


numeric_expression 


Is a valid nonzero or nonnegative numeric expression. 


Result Types 


DT_R8& 


Remarks 


The numeric expression is cast to the DT_R8 data type before the logarithm is computed. For more information, 
see Integration Services Data Types. 


If numeric_expression evaluates to zero or a negative value, the return result is null. 


Expression Examples 


This example uses a numeric literal. The function returns the value 1.988291341907488. 
LOG (97.34) 

This example uses the column Length. If the column is 101.24, the function returns 2.005352136486217. 
LOG(Length) 


This example uses the variable Length. The variable must have a numeric data type or the expression must 
include an explicit cast to a numeric SSIS data type. If Length is 234.567, the function returns 
2.370266913465859. 


LOG(@Length) 


See Also 


EXP (SSIS Expression) 
LN (SSIS Expression) 


Functions (SSIS Expression) 


LOWER (SSIS Expression) 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Returns a character expression after converting uppercase characters to lowercase characters. 


Syntax 


LOWER(character_expression) 


Arguments 


character_expression 


Is a character expression to convert to lowercase characters. 


Result Types 


DT_WSTR 


Remarks 


LOWER works only with the DT_WSTR data type. A character_expression argument that is a string literal or a 
data column with the DT_STR data type is implicitly cast to the DI_WSTR data type before LOWER performs its 
operation. Other data types must be explicitly cast to the DT_WSTR data type. For more information, see 
Integration Services Data Types and Cast (SSIS Expression). 


LOWER returns a null result if the argument is null. 


Expression Examples 


This example converts a string literal to lowercase characters. The return result is "new york". 


LOWER("New York") 


This example converts all characters from the Color input column, except the first character, to lowercase 
characters. If Color is YELLOW, the return result is "Yellow". For more information, see SUBSTRING (SSIS 
Expression). 


LOWER(SUBSTRING(Color, 2, 15)) 


This example converts the value in the CityName variable to lowercase characters. 


LOWER (@CityName) 


See Also 


UPPER (SSIS Expression) 
Functions (SSIS Expression) 


LTRIM (SSIS Expression) 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Returns a character expression after removing leading spaces. 


NOTE 


LTRIM does not remove white-space characters such as the tab or line feed characters. Unicode provides code points for 
many different types of spaces, but this function recognizes only the Unicode code point 0x0020. When double-byte 
character set (DBCS) strings are converted to Unicode they may include space characters other than 0x0020 and the 
function cannot remove such spaces. To remove all kinds of spaces, you can use the Microsoft Visual Basic .NET LTrim 
method in a script run from the Script component. 








Syntax 


LTRIM(character expression) 


Arguments 


character_expression 


Is a character expression from which to remove spaces. 


Result Types 


DT_WSTR 


Remarks 


LTRIM works only with the DT_WSTR data type. A character_expression argument that is a string literal or a data 
column with the DT_STR data type is implicitly cast to the DT_WSTR data type before LTRIM performs its 
operation. Other data types must be explicitly cast to the DT_WSTR data type. For more information, see 
Integration Services Data Types and Cast (SSIS Expression). 


LTRIM returns a null result if the argument is null. 


Expression Examples 


This example removes leading spaces from a string literal. The return result is "Hello". 
LTRIM(" Hello") 
This example removes leading spaces from the FirstName column. 


LTRIM(FirstName) 


This example removes leading spaces from the FirstName variable. 


LTRIM(@FirstName) 


See Also 


RTRIM (SSIS Expression) 
TRIM (SSIS Expression) 
Functions (SSIS Expression) 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Returns an integer that represents the month datepart of a date. 


Syntax 


MONTH(date) 


Arguments 


date 
Is a date in any date format. 


Result Types 


DT_|4 


Remarks 


MONTH returns a null result if the argument is null. 


A date literal must be explicitly cast to one of the date data types. For more information, see Integration Services 
Data Types. 





NOTE 


The expression fails to validate when a date literal is explicitly cast to one of these date data types: 
DT_DBTIMESTAMPOFFSET and DT_DBTIMESTAMP2. 











Using the MONTH function is briefer but equivalent to using DATEPART("Month", date). 


Expression Examples 


This example returns the number of the month in a date literal. If the date is in "mm/dd/yyyy" format, this 
example returns 11. 


MONTH( (DT_DBTIMESTAMP ) "11/23/2002" ) 


This example returns the integer that represents the month in the ModifiedDate column. 


MONTH(ModifiedDate) 


This example returns the integer that represents the month of the current date. 


MONTH(GETDATE ()) 


See Also 


DATEADD (SSIS Expression) 
DATEDIFF (SSIS Expression) 
DATEPART (SSIS Expression) 
DAY (SSIS Expression) 
YEAR (SSIS Expression) 
Functions (SSIS Expression) 


NULL (SSIS Expression) 
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Applies to: Q sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Returns a null value of a requested data type. 


Syntax 


NULL(typespec) 


Arguments 
typespec 


Is a valid data type. For more information, see Integration Services Data Types. 


Result Types 


Any valid data type with a null value. 


Remarks 


NULL returns a null result if the argument is null. 


Parameters are required to request a null value for some data types. The following table lists these data types 
and their parameters. 


DATA TYPE PARAMETER EXAMPLE 
DT_STR charcount (DT_STR,30,1252) casts 30 characters 
to the DT_STR data type using the 
codepage 1252 code page. 
DT_WSTR charcount (DT_WSTR,20) casts 20 characters to 


the DT_WSTR data type. 


DT_BYTES bytecount (DT_BYTES,50) casts 50 bytes to the 
DT_BYTES data type. 


DT_DECIMAL scale (DT_DECIMAL,2) casts a numeric value 
to the DT_DECIMAL data type using a 
scale of 2. 
DT_NUMERIC precision (DT_NUMERIC,10,3) casts a numeric 
value to the DT_NUMERIC data type 
scale using a precision of 10 and a scale of 


3: 


DATA TYPE PARAMETER EXAMPLE 


DT_TEXT codepage (DT_TEXT,1252) casts a value to the 
DT_TEXT data type using the 1252 
code page. 


Expression Examples 
These examples return the null value of the data types: DT_STR, DT_DATE, and DT_BOOL. 
NULL(DT_STR, 10,1252) 


NULL(DT_DATE) 
NULL(DT_BOOL) 


See Also 


ISNULL (SSIS Expression) 
Functions (SSIS Expression) 


POWER (SSIS Expression) 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Returns the result of raising a numeric expression to a power. The power parameter must evaluate to an integer. 


Syntax 


POWER(numeric_expression, power) 


Arguments 


numeric_expression 
Is a valid numeric expression. 


power 
Is a valid numeric expression. 


Result Types 


DT_R8& 


Remarks 


The numeric_expression and power arguments are cast to the DT_R8 data type before the power is computed. 
For more information, see Integration Services Data Types. 


If numeric_expression evaluates to zero and power is negative, the expression evaluator returns an error and 
sets the return result to null. 


If numeric_expression or power evaluate to indeterminate results, the return result is null. 


The power argument can be a fraction. For example, you can use the value 0.5 as the power. 


Expression Examples 


This example uses a numeric literal. The function raises 4 to the power of 3 and returns 64. 
POWER(4, 3) 


This example uses the Length column and the DimensionCount variable. If Length is 8, and 
DimensionCount is 2, the return result is 64. 


POWER(Length, @DimensionCount) 


See Also 


Functions (SSIS Expression) 


REPLACE (SSIS Expression) 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Returns a character expression after replacing a character string within the expression with either a different 
character string or an empty string. 





NOTE 


The REPLACE function frequently uses long strings. The consequences of truncation can be handled gracefully or cause a 
warning or an error. For more information, see Syntax (SSIS). 








Syntax 


REPLACE(character_expression, searchstring, replacementstring) 


Arguments 


character_expression 


Is a valid character expression that the function searches. 


searchstring 
Is a valid character expression that the function attempts to locate. 


replacementstring 
Is a valid character expression that is the replacement expression. 


Result Types 


DT_WSTR 


Remarks 


The length of searchstring must not be zero. 
The length of rep/acementstring may be zero. 
The searchstring and replacementstring arguments can use variables and columns. 


REPLACE works only with the DT_WSTR data type. character_expression1, character_expression2, and 
character_expression3 arguments that are string literals or data columns with the DT_STR data type are 
implicitly cast to the DT_WSTR data type before REPLACE performs its operation. Other data types must be 
explicitly cast to the DT_WSTR data type. For more information, see Cast (SSIS Expression). 


REPLACE returns a null result if any argument is null. 


Expression Examples 


This example uses a string literal. The return result is "All Terrain Bike". 


REPLACE("Mountain Bike", "Mountain","All Terrain") 


This example removes the string "Bike" from the Product column. 


REPLACE(Product, "Bike","") 


This example replaces values in the DaysToManufacture column. The column has an integer data type and the 
expression includes casting DaysToManufacture to the DT_WSTR data type. 


REPLACE( (DT_WSTR, 8)DaysToManufacture, "6","5") 


See Also 


SUBSTRING (SSIS Expression) 
Functions (SSIS Expression) 


REPLACENULL (SSIS Expression) 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Returns the value of second expression parameter if the value of first expression parameter is NULL; otherwise, 
returns the value of first expression. 


Syntax 


REPLACENULL(expression 1,expression 2) 


Arguments 


expression 7 
The result of this expression is checked against NULL. 


expression 2 
The result of this expression is returned if the first expression evaluates to NULL. 


Result Types 


DT_WSTR 


Remarks 

@ The length of expression 2 may be zero. 

e REPLACENULL returns a null result if any argument is null. 

e BLOB columns (DT_TEXT, DT_NTEXT, DT_IMAGE) are not supported for either parameter. 


e The two expressions are expected to have the same return type. If they do not, the function attempts to 
cast the 2nd expression to the return type of the 1st expression, which may result in an error if the data 
types are incompatible. 


Expression Examples 


The following example replaces any NULL value in a database column with a string (1900-01-01). This function 
is especially used in common Derived Column patterns where you want to replace NULL values with something 
else. 


REPLACENULL(MyColumn, "190@-@1-@1") 





NOTE 


The following example shows how it was done in SQL Server 2005 Integration Services (SSIS)/ SQL Server 2008 
Integration Services (SSIS). 











(DT_DBTIMESTAMP) (ISNULL(MyColumn) ? "19@@-@1-@1" : MyColumn) 


REPLICATE (SSIS Expression) 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Returns a character expression that is replicated a number of times. The times argument must evaluate to an 
integer. 





NOTE 


The REPLICATE function frequently uses long strings, and therefore is more likely to incur the 4000-character limit on 
expression length. If the evaluation result of an expression has the Integration Services data type DT_WSTR or DT_STR, the 
expression will be truncated at 4000 characters. If the result type of a sub-expression is DT_STR or DT_WSTR, that sub- 
expression likewise will be truncated to 4000 characters, regardless of the overall expression result type. The 
consequences of truncation can be handled gracefully or cause a warning or an error. For more information, see Syntax 
(SSIS). 





Syntax 


REPLICATE(character_expression, times) 


Arguments 


character_expression 
Is a character expression to replicate. 


times 


Is an integer expression that specifies the number of times character_expression is replicated. 


Result Types 


DT_WSTR 


Remarks 


If times is zero, the function returns a zero-length string. 
If times is a negative number, the function returns an error. 
The times argument can also use variables and columns. 


REPLICATE works only with the DT_WSTR data type. A character_expression argument that is a string literal or a 
data column with the DT_STR data type is implicitly cast to the DT_WSTR data type before REPLICATE performs 
its operation. Other data types must be explicitly cast to the DT_WSTR data type. For more information, see 
Integration Services Data Types and Cast (SSIS Expression). 


REPLICATE returns a null result if either argument is null. 


Expression Examples 





This example replicates a string literal three times. The return result is "Mountain BikeMountain BikeMountain 
Bike". 


REPLICATE("Mountain Bike", 3) 


This example replicates values in the Name column by the value in the Times variable. If Times is 3 and Name 
is Touring Front Wheel, the return result is Touring Front WheelTouring Front WheelTouring Front Wheel. 


REPLICATE(Name, @Times) 


This example replicates the value in the Name variable by the value in the Times column. Times has a non- 
integer data type and the expression includes an explicit cast to an integer data type. If Name contains Helmet 
and Times is 2, the return result is "HelmetHelmet". 


REPLICATE(@Name, (DT_I4(Times) ) 


See Also 


Functions (SSIS Expression) 


REVERSE (SSIS Expression) 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Returns a character expression in reverse order. 


Syntax 


REVERSE(character_expression) 


Arguments 


character_expression 
Is a character expression to be reversed. 


Result Types 


DT_WSTR 


Remarks 
The character_expression argument must have the DT_WSTR data type. 


REVERSE returns a null result if character_expression is null. 


Expression Examples 


This example uses a string literal. The return result is "ekiB niatnuoM". 
REVERSE("Mountain Bike") 
This example uses a variable. lf Name contains Touring Bike, the return result is "ekiB gniruoT". 


REVERSE (@Name) 


See Also 


Functions (SSIS Expression) 


RIGHT (SSIS Expression) 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Returns the specified number of characters from the rightmost portion of the given character expression. 


Syntax 


RIGHT(character_expression, integer_expression) 


Arguments 


character_expression 


Is a character expression from which to extract characters. 


integer_expression 


Is an integer expression that indicates the number of characters to be returned. 


Result Types 


DT_WSTR 


Remarks 


If integer_expression is greater than the length of character_expression, the function returns 
character_expression. 


If integer_expression is zero, the function returns a zero-length string. 
If integer_expression is a negative number, the function returns an error. 
The /nteger_expression argument can take variables and columns. 


RIGHT works only with the DT_WSTR data type. A character_expression argument that is a string literal or a data 
column with the DT_STR data type is implicitly cast to the DT_WSTR data type before RIGHT performs its 
operation. Other data types must be explicitly cast to the DT_WSTR data type. For more information, see 
Integration Services Data Types and Cast (SSIS Expression). 


RIGHT returns a null result if either argument is null. 


Expression Examples 


The following example uses a string literal. The return result is “Bike” . 
RIGHT("Mountain Bike", 4) 


The following example returns the number of rightmost characters that is specified in the Times variable, from 


the Name column. If Name is Touring Front Wheel and Times is 5, the return result is “Wheel” . 


RIGHT(Name, @Times) 


The following example also returns the number of rightmost characters that is specified in the Times variable, 
from the Name column. Times has a noninteger data type and the expression includes an explicit cast to the 
DT_l2 data type. If Name is Touring Front Wheel and Times is 4.32, the return resultis “heel" because the 
RIGHT function converts the value of 4.32 to 4, and then returns the rightmost four characters. 


RIGHT(Name, (DT_I2)@Times) ) 


See Also 


LEFT (SSIS Expression) 
Functions (SSIS Expression) 


ROLE] NID Os (0)C=5[0)8)) 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Returns a numeric expression that is rounded to the specified length or precision. The length parameter must 
evaluate to an integer. 


Syntax 


ROUND(numeric_expression, length) 


Arguments 


numeric_expression 


Is an expression of a valid numeric type. For more information, see Integration Services Data Types. 


length 


Is an integer expression. It is the precision to which numeric_expression is rounded. 


Result Types 


The same type as numeric_expression. 


Remarks 
The /ength argument must evaluate to a positive integer or zero. 


ROUND returns a null result if the argument is null. 


Expression Examples 


These examples round numeric literals to a length of three. The first return result is 137.1570, the second 
137.1580. 


ROUND (137.1574, 3) 
ROUND (137.1575, 3) 


See Also 


Functions (SSIS Expression) 


RTRIM (SSIS Expression) 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Returns a character expression after removing trailing spaces. 


NOTE 


RTRIM does not remove white space characters such as the tab or line feed characters. Unicode provides code points for 
many different types of spaces, but this function recognizes only the Unicode code point 0x0020. When double-byte 
character set (DBCS) strings are converted to Unicode they may include space characters other than 0x0020 and the 
function cannot remove such spaces. To remove all kinds of spaces, you can use the Microsoft Visual Basic .NET RTrim 
method in a script run from the Script component. 








Syntax 


RTRIM(character expression) 


Arguments 


character_expression 


Is a character expression from which to remove spaces. 


Result Types 


DT_WSTR 


Remarks 


RTRIM works only with the DT_WSTR data type. A character_expression argument that is a string literal or a data 
column with the DT_STR data type is implicitly cast to the DT_WSTR data type before RTRIM performs its 
operation. Other data types must be explicitly cast to the DT_WSTR data type. For more information, see 
Integration Services Data Types and Cast (SSIS Expression). 


RTRIM returns a null result if the argument is null. 


Expression Examples 


This example removes trailing spaces from a string literal. The return result is "Hello". 
RTRIM("Hello ") 
This example removes trailing spaces from a concatenation of the FirstName and LastName columns. 


RTRIM(FirstName + " " + LastName) 


This example removes trailing spaces from the FirstName variable. 


RTRIM(@FirstName) 


See Also 


LTRIM (SSIS Expression) 
TRIM (SSIS Expression) 
Functions (SSIS Expression) 


SI(CINM (SSIS =(0)K>SS1(0)8)) 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Returns the positive (+1), negative (-1), or zero (0) sign of a numeric expression. 


Syntax 


SIGN(numeric_expression) 


Arguments 


numeric_expression 


Is a valid signed numeric expression. For more information, see Integration Services Data Types. 


Result Types 


DT_|4 


Remarks 


SIGN returns a null result if the argument is null. 


Expression Examples 


This example returns the sign of a numeric literal. The return result is -1. 


SIGN(-123.45) 


This example returns the sign of the result of subtracting the StandardCost column from the DealerPrice 
column. 


SIGN(DealerPrice - StandardCost) 


See Also 


Functions (SSIS Expression) 


SQRT (SSIS Expression) 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Returns the square root of a numeric expression. 


Syntax 


SQRT (numeric_expression) 


Arguments 


numeric_expression 


Is anumeric expression of any numeric data type. For more information, see Integration Services Data Types. 


Result Types 


DT_R8& 


Remarks 


SQRT returns a null result if the argument is null. 
SQRT fails if the argument is a negative value. 


The argument is cast to the DT_R8 data type before the square root operation. 


Expression Examples 


This example returns the square root of a numeric literal. The return result is 12. 
SQRT (144) 


This example returns the square root of an expression, the result of subtracting values in the Value1 and 
Value2 columns. 


SQRT(Value1 - Value2) 


This example returns the length of the third side of a right triangle by applying the SQUARE function to two 
variables and then calculating the square root of their sum. If Side1 contains 3 and Side2 contains 4, the SQRT 
function returns 5. 


SQRT(SQUARE(@Side1) + SQUARE(@Side2) ) 





NOTE 


In expressions, variable names always include the @ prefix. 





See Also 


Functions (SSIS Expression) 


SO] U/N tam (sis l= 0]coS(0)8)) 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Returns the square of a numeric expression. 


Syntax 


SQUARE (numeric_expression) 


Arguments 


numeric_expression 


Is anumeric expression of any numeric data type. For more information, see Integration Services Data Types. 


Result Types 


DT_R8& 


Remarks 


SQUARE returns a null result if the argument is null. 


The argument is cast to the DT_R8 data type before the square operation. 


Expression Examples 


This example returns the square of 12. The return result is 144. 
SQUARE (12) 


This example returns the square of the result of subtracting values in two columns. If Value1 contains 12 and 
Value2 contains 4, the SQUARE function returns 64. 


SQUARE(Value1 - Value2) 


This example returns the length of the third side of a right angle triangle by applying the SQUARE function to 
two variables and then calculating the square root of their sum. If Side1 contains 3 and Side2 contains 4, the 
SQRT function returns 5. 


SQRT(SQUARE(@Side1) + SQUARE(@Side2) ) 





NOTE 


In expressions, variable names always include the @ prefix. 





See Also 


Functions (SSIS Expression) 


SUBSTRING (SSIS Expression) 
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Applies to: Q@ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Returns the part of a character expression that starts at the specified position and has the specified length. The 
position parameter and the /ength parameter must evaluate to integers. 


Syntax 


SUBSTRING(character_expression, position, length) 


Arguments 


character_expression 


Is a character expression from which to extract characters. 


position 
Is an integer that specifies where the substring begins. 


length 
Is an integer that specifies the length of the substring as number of characters. 


Result Types 


DT_WSTR 


Remarks 


SUBSTRING uses a one-based index. If position is 1, the substring begins with the first character in 
character_expression. 


SUBSTRING works only with the DT_WSTR data type. A character_expression argument that is a string literal or 
a data column with the DT_STR data type is implicitly cast to the DI_WSTR data type before SUBSTRING 
performs its operation. Other data types must be explicitly cast to the DT_WSTR data type. For more information, 
see Integration Services Data Types and Cast (SSIS Expression). 


SUBSTRING returns a null result if the argument is null. 
All arguments in the expression can use variables and columns. 
The /ength argument can exceed the length of the string. In that case, the function returns the remainder of the 


string. 


Expression Examples 


This example returns two characters, beginning with character 4, from a string literal. The return result is "ph". 


SUBSTRING("elephant", 4, 2) 


This example returns the remainder of a string literal, beginning at the fourth character. The return result is 
"phant". It is not an error for the /ength argument to exceed the length of the string. 


SUBSTRING ("elephant",4,52) 
This example returns the first letter from the MiddleName column. 
SUBSTRING(MiddleName, 1,1) 


This example uses variables in the position and /ength arguments. If Start is 1 and Length is 5, the function 
returns the first five characters in the Name column. 


SUBSTRING(Name, @Start,@Length) 

This example returns the last four characters from the PostalCode variable beginning at the sixth character. 
SUBSTRING (@PostalCode,6,4) 

This example returns a zero-length string from a string literal. 


SUBSTRING ("Redmond",4,@) 


See Also 


Functions (SSIS Expression) 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Returns a token (substring) from a string based on the specified delimiters that separate tokens in the string and 
the number of the token that denotes which token to be returned. 


Syntax 


TOKEN(character_expression, delimiter_string, occurrence) 


Arguments 


character_expression 
A string that contains tokens separated by delimiters. 


delimiter_string 


A string that contains delimiter characters. For example, "; ," contains three delimiter characters semi-colon, a 
blank space, and a comma. 


occurrence 


A signed or unsigned integer that specifies the token to be returned. For example, if you specify 3 as a value for 
this parameter, the third token in the string is returned. 


Result Types 


DT_WSTR 


Remarks 


This function splits up the <character_expression> string into a set of tokens separated by the delimiters 
specified in the <delimiter_string> and then returns the Nth token where N is the number of occurrence of the 
token specified by the <occurrence> parameter. See Examples section for sample usages of this function. 


The following remarks apply to the TOKEN function: 
e The delimiter string can contain one or more delimiter characters. 


e Ifthe value of <occurrence> parameter is higher than the total number of tokens in the string, the 
function returns NULL. 


e Leading delimiters are skipped. 


e@ TOKEN works only with the DT_WSTR data type. A character_expression argument that is a string literal 
or a data column with the DT_STR data type is implicitly cast to the DT_WSTR data type before TOKEN 
performs its operation. Other data types must be explicitly cast to the DI_WSTR data type. 


e TOKEN returns a null result if the character_expression is null. 


e You can use variables and columns as values of all arguments in the expression. 


Expression Examples 


In the following example, the TOKEN function returns "a". The string “a little white dog" has 4 tokens "a", "little", 


"white", "dog" separated by the delimiter "" (space character). The second argument, a delimiter string, specifies 


only one delimiter, the space character, to be used in splitting the input string into tokens. The last argument, 1, 
specifies that the first token to be returned. The first token is "a" in this sample string. 


TOKEN("a little white dog"," ",1) 


In the following example, the TOKEN function returns "dog". The delimiter string in this example contains 5 
delimiters. The input string contains 4 tokens: "a", "little", "white", "dog". 


TOKEN("a:little|white dog","| ,.:",4) 


mn 


In the following example, the TOKEN function returns "" (an empty string) because there are no 99 tokens in the 


string. 
TOKEN("a little white dog"," ",99) 


In the following example, the TOKEN function returns the full string. The function parses the input string for 
delimiters and since there are none in the string, it just adds the entire string as the first token. 


TOKEN("a little white dog","|",1) 

In the following example, the TOKEN function returns "a". It ignores all the leading space characters. 
TOKEN(" a little white dog", "", 1) 

In the following example, the TOKEN function returns the year from a date string. 
TOKEN("20@9/01/01", "/", 1) 


In the following example, the TOKEN function returns the file name from the specified path. For example, if the 
value of User::Path is "c:\program files\data\myfile.txt", the TOKEN function returns "myfile.txt". The 
TOKENCOUNT function returns 4 and the TOKEN function return the 4th token, "myfile.txt". 


TOKEN(@[User::Path], "\\", TOKENCOUNT(@[User::Path], "\\")) 


See Also 


Functions (SSIS Expression) 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Returns the number of tokens in a string that contains tokens separated by the specified delimiters. 


Syntax 


TOKENCOUNT(character_expression, delimiter_string) 


Arguments 


character_expression 


A string that contains tokens separated by delimiters. 


delimiter_string 


A string that contains delimiter characters. For example, "; ," contains three delimiter characters semi-colon, a 
blank space, and a comma. 


Result Types 


DT_|4 


Remarks 

The following remarks apply to the TOKEN function: 

e The delimiter string can contain one or more delimiter characters. 
e Leading delimiters are skipped. 


e TOKENCOUNT works only with the DI_WSTR data type. A character_expression argument that is a string 
literal or a data column with the DT_STR data type is implicitly cast to the DT_WSTR data type before 
TOKEN performs its operation. Other data types must be explicitly cast to the DI_WSTR data type. 


TOKENCOUNT returns 0 (zero) if the character_expression is null. 


e You can use variables and columns as arguments for this expression. 


Expression Examples 
In the following example, the TOKENCOUNT function returns 3 because the string contains three tokens: "01", 
"72","2011". 


TOKENCOUNT("@1/12/2011", "/") 


In the following example, the TOKENCOUNT function returns 4 because there are four tokens ("a", "little", 


"white", "dog"). 


TOKENCOUNT("a little white dog"," ") 


In the following example, the TOKENCOUNT function returns 1. The function parses the input string for 
delimiters and since there are none in the string, it just adds the entire string as the first token. 


TOKENCOUNT("a little white dog","|") 


In the following example, the TOKENCOUNT function returns 4. The delimiter string in this example contains 5 
delimiters. The input string contains 4 tokens: "a", "little", "white", "dog". 


TOKENCOUNT("a:little|white dog","| ,.:") 
In the following example, the TOKENCOUNT function returns 4. It ignores all the leading space characters. 


TOKENCOUNT (" a little white dog", " ") 


See Also 


Functions (SSIS Expression) 


TRIM (SSIS Expression) 


11/23/2021 * 2 minutes to read « Edit Online 





Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Returns a character expression after removing leading and trailing spaces. 


NOTE 


TRIM does not remove white-space characters such as the tab or line feed characters. Unicode provides code points for 
many different types of spaces, but this function recognizes only the Unicode code point 0x0020. When double-byte 
character set (DBCS) strings are converted to Unicode they may include space characters other than 0x0020 and the 
function cannot remove such spaces. To remove all kinds of spaces, you can use the Microsoft Visual Basic .NET Trim 
method in a script run from the Script component. 








Syntax 


TRIM(character_expression) 


Arguments 


character_expression 


Is a character expression from which to remove spaces. 


Result Types 


DT_WSTR 


Remarks 


TRIM returns a null result if the argument is null. 


TRIM works only with the DT_WSTR data type. A character_expression argument that is a string literal or a data 
column with the DT_STR data type is implicitly cast to the DT_WSTR data type before TRIM performs its 
operation. Other data types must be explicitly cast to the DT_WSTR data type. For more information, see 
Integration Services Data Types and Cast (SSIS Expression). 


Expression Examples 


This example removes leading and trailing spaces from a string literal. The return result is "New York". 


TRIM(" New York ") 


This example removes leading and trailing spaces from the result of concatenating the FirstName and 
LastName columns. The empty string between FirstName and LastName is not removed. 


TRIM(FirstName + " "+ LastName) 


See Also 


LTRIM (SSIS Expression) 
RTRIM (SSIS Expression) 
Functions (SSIS Expression) 


UPPER (SSIS Expression) 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Returns a character expression after converting lowercase characters to uppercase characters. 


Syntax 


UPPER(character_expression) 


Arguments 


character_expression 


Is a character expression to convert to uppercase characters. 


Result Types 


DT_WSTR 


Remarks 


UPPER works only with the DT_WSTR data type. A character_expression argument that is a string literal or a data 
column with the DT_STR data type is implicitly cast to the DT_WSTR data type before UPPER performs its 
operation. Other data types must be explicitly cast to the DT_WSTR data type. For more information, see 
Integration Services Data Types and Cast (SSIS Expression). 


UPPER returns a null result if the argument is null. 


Expression Examples 


This example converts a string literal to uppercase characters. The return result is "HELLO". 


UPPER("hello") 


This example converts the first character in the FirstName column to an uppercase character. If FirstName is 
anna, the return result is "A". For more information, see SUBSTRING (SSIS Expression). 


UPPER(SUBSTRING(FirstName, 1, 1)) 


This example converts the value in the PostalCode variable to uppercase characters. If PostalCode is k4b1s2, 
the return result is "K4B1S2". 


UPPER(@PostalCode) 


See Also 


LOWER (SSIS Expression) 
Functions (SSIS Expression) 
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Returns an integer that represents the year datepart of a date. 


Syntax 


YEAR (date) 


Arguments 


date 
Is a date in any date format. 


Result Types 


DT_|4 


Remarks 


YEAR returns a null result if the argument is null. 


A date literal must be explicitly cast to one of the date data types. For more information, see Integration Services 
Data Types. 





NOTE 


The expression fails to validate when a date literal is explicitly cast to one of these date data types: 
DT_DBTIMESTAMPOFFSET and DT_DBTIMESTAMP2. 











Using the YEAR function is briefer but equivalent to using the DATEPART("Year", date) function. 


Expression Examples 


This example returns the number of the year in a date literal. If the date is in mm/dd/yyyy format, this example 
returns "2002". 


YEAR ((DT_DBTIMESTAMP) "11/23/2002" ) 


This example returns the integer that represents the year in the ModifiedDate column. 


YEAR (ModifiedDate) 


This example returns the integer that represents the year of the current date. 


YEAR (GETDATE()) 


See Also 


DATEADD (SSIS Expression) 
DATEDIFF (SSIS Expression) 
DATEPART (SSIS Expression) 
DAY (SSIS Expression) 
MONTH (SSIS Expression) 
Functions (SSIS Expression) 
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At run time, executables (packages and Foreach Loop, For Loop, Sequence, and task host containers) raise 
events. For example, an OnError event is raised when an error occurs. You can create custom event handlers for 
these events to extend package functionality and make packages easier to manage at run time. Event handlers 
can perform tasks such as the following: 


e Clean up temporary data storage when a package or task finishes running. 

e Retrieve system information to assess resource availability before a package runs. 
e Refresh data in a table when a lookup in a reference table fails. 

e Send an e-mail message when an error or a warning occurs or when a task fails. 


If an event has no event handler, the event is raised to the next container up the container hierarchy in a 
package. If this container has an event handler, the event handler runs in response to the event. If not, the event 
is raised to the next container up the container hierarchy. 


The following diagram shows a simple package that has a For Loop container that contains one Execute SQL 
task. 


Package 
For Loop Container 





Only the package has an event handler, for its OnError event. If an error occurs when the Execute SQL task runs, 
the OnError event handler for the package runs. The following diagram shows the sequence of calls that causes 
the OnError event handler for the package to execute. 


Package No 
Event Handler Event Handler 


runs runs 







Event Handler No Event Handler 


For Loop 
Container 
Event Handler 
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Event Handler 
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Event Handler 


runs 


Event Handler 


Task Host 


Event handlers are members of an event handler collection, and all containers include this collection. If you 
create the package using SSIS Designer, you can see the members of the event handler collections in the Event 
Handlers folders on the Package Explorer tab of SSIS Designer. 


You can configure the event handler container in the following ways: 
@ Specify a name and description for the event handler. 


e Indicate whether the event handler runs, whether the package fails if the event handler fails, and the 
number of errors that can occur before the event handler fails. 


e Specify an execution result to return instead of the actual execution result that the event handler returns 


at run time. 
e Specify the transaction option for the event handler. 


e Specify the logging mode that the event handler uses. 


Event Handler Content 


Creating an event handler is similar to building a package; an event handler has tasks and containers, which are 
sequenced into a control flow, and an event handler can also include data flows. The SSIS Designer includes the 
Event Handlers tab for creating custom event handlers. 


You can also create event handlers programmatically. For more information, see Handling Events 


Programmatically. 


Run-Time Events 


The following table lists the event handlers that Integration Services provides, and describes the run-time events 


that cause the event handler to run. 
EVENT HANDLER EVENT 


OnError The event handler for the OnError event. This event is 
raised by an executable when an error occurs. 


OnExecStatusChanged The event handler for the OnExecStatusChanged event. 
This event is raised by an executable when its execution 
status changes. 


OnInformation The event handler for the OnInformation event. This event 
is raised during the validation and execution of an executable 
to report information. This event conveys information only, 
no errors or warnings. 


OnPostExecute The event handler for the OnPostExecute event. This event 
is raised by an executable immediately after it has finished 
running. 


OnPostValidate The event handler for the OnPostValidate event. This 
event is raised by an executable when its validation is 
finished. 


OnPreExecute The event handler for the OnPreExecute event. This event 
is raised by an executable immediately before it runs. 


OnPreValidate The event handler for the OnPreValidate event. This event 
is raised by an executable when its validation starts. 


EVENT HANDLER EVENT 


OnProgress The event handler for the OnProgress event. This event is 
raised by an executable when measurable progress is made 
by the executable. 


OnQueryCancel The event handler for the OnQueryCancel event. This 
event is raised by an executable to determine whether it 
should stop running. 


OnTaskFailed The event handler for the OnTaskFailed event. This event is 
raised by a task when it fails. 


OnVariableValueChanged The event handler for the OnVariableValueChanged 
event. This event is raised by an executable when the value 
of a variable changes. The event is raised by the executable 
on which the variable is defined. This event is not raised if 
you set the RaiseChangeEvent property for the variable to 
False. For more information, see Integration Services (SSIS) 
Variables. 


OnWarning The event handler for the OnWarning event. This event is 
raised by an executable when a warning occurs. 


Add an event handler to a package 


At run time, containers and tasks raise events. You can create custom event handlers that respond to these 
events by running a workflow when the event is raised. For example, you can create an event handler that sends 
an e-mail message when a task fails. 


An event handler is similar to a package. Like a package, an event handler can provide scope for variables, and 
includes a control flow and optional data flows. You can build event handlers for packages, the Foreach Loop 
container, the For Loop container, the Sequence container, and all tasks. 


You create event handlers by using the design surface of the Event Handlers tab in SSIS Designer. 


When the Event Handlers tab is active, the Control Flow Items and Maintenance Plan Tasks nodes of the 
Toolbox in SSIS Designer contain the task and containers for building the control flow in the event handler. The 
Data Flow Sources, Transformations, and Data Flow Destinations nodes contain the data sources, 
transformations, and destinations for building the data flows in the event handler. For more information, see 
Control Flow and Data Flow. 


The Event Handlers tab also includes the Connections Managers area where you can create and modify the 
connection managers that event handlers use to connect to servers and data sources. For more information, see 
Create Connection Managers. 


Add an event handler on the Event Handlers tab 


1. In SQL Server Data Tools (SSDT), open the Integration Services project that contains the package you 


want. 
2. In Solution Explorer, double-click the package to open it. 


3. Click the Event Handlers tab. 


+ & X | Package.dtsx [Design]* x . 
%,., Control Flow | (6) Data Flow | 7 Event Handlers | “o Package Explorer Os 


Right-click here to add a new connection manager to the SSIS package. 





Creating the control flow and data flows in an event handler is similar to creating the control flow and 
data flows in a package. For more information, see Control Flow and Data Flow. 


4. In the Executable list, select the executable for which you want to create an event handler. 
5. Inthe Event handler list, select the event handler you want to build. 
6. Click the link on the design surface of the Event Handler tab. 


7. Add control flow items to the event handler, and connect items using a precedence constraint by 


dragging the constraint from one control flow item to another. For more information, see Control Flow. 


8. Optionally, add a Data Flow task, and on the design surface of the Data Flow tab, create a data flow for 
the event handler. For more information, see Data Flow. 


9. On the File menu, click Save Selected Items to save the package. 


Set the properties of an event handler 


You can set properties in the Properties window of SQL Server Data Tools (SSDT) or programmatically. 


For information about how to set these properties in SQL Server Data Tools (SSDT), see Set the Properties of a 
Task or Container. 


For information about programmatically setting these properties, see DtsEventHandler. 


Related Tasks 


For information about how to add an event handler to a package, see Add an Event Handler to a Package. 


Integration Services (SSIS) Queries 


11/23/2021 * 6 minutes to read « Edit Online 





Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


The Execute SQL task, the OLE DB source, the OLE DB destination, and the Lookup transformation can use SQL 
queries. In the Execute SQL task, the SQL statements can create, update, and delete database objects and data; 
run stored procedures; and perform SELECT statements. In the OLE DB source and the Lookup transformation, 
the SQL statements are typically SELECT statements or EXEC statements. The latter most frequently run stored 
procedures that return result sets. 


A query can be parsed to establish whether it is valid. When parsing a query that uses a connection to SQL 
Server, the query is parsed, executed, and the execution outcome (success or failure) is assigned to the parsing 
outcome. If the query uses a connection to a data other than SQL Server, the statement is parsed only. 


You can provide the SQL statement in the following ways: 


1. Enter it directly in the designer. 
2. Specify a connection to a file contains the statement. 


3. Specify a variable that contains the statement. 


Direct Input SQL 


Query Builder is available in the user interface for the Execute SQL task, the OLE DB source, the OLE DB 
destination, and the Lookup transformation. Query Builder offers the following advantages: 


e Work visually or with SQL commands. 


Query Builder includes graphical panes that compose your query visually and a text pane that displays 
the SQL text of your query. You can work in either the graphical or text panes. Query Builder synchronizes 
the views so that the query text and graphical representation always match. 


e Join related tables. 


If you add more than one table to your query, Query Builder automatically determines how the tables are 
related and constructs the appropriate join command. 


@ Query or update databases. 


You can use Query Builder to return data using Transact-SQL SELECT statements, or to create queries that 
update, add, or delete records in a database. 


e View and edit results immediately. 


You can execute your query and work with a recordset in a grid that lets you scroll through and edit 
records in the database. 


Although Query Builder is visually limited to creating SELECT queries, you can type the SQL for other types of 
statements such as DELETE and UPDATE statements in the text pane. The graphical pane is automatically 
updated to reflect the SQL statement that you typed. 


You can also provide direct input by typing the query in the task or data flow component dialog box or the 
Properties window. 


For more information, see Query Builder. 


SQL in Files 


The SQL statement for the Execute SQL task can also reside in a separate file. For example, you can write queries 
using tools such as the Query Editor in SQL Server Management Studio, save the query to a file, and then read 
the query from the file when running a package. The file can contain only the SQL statements to run and 
comments. To use a SQL statement stored in a file, you must provide a file connection that specifies the file 


name and location. For more information, see File Connection Manager. 


SQL in Variables 


If the source of the SQL statement in the Execute SQL task is a variable, you provide the name of the variable 
that contains the query. The Value property of the variable contains the query text. You set the ValueType 
property of the variable to a string data type and then type or copy the SQL statement into the Value property. 
For more information, see Integration Services (SSIS) Variables and Use Variables in Packages. 


Query Builder dialog box 


Use the Query Builder dialog box to create a query for use in the Execute SQL task, the OLE DB source and the 
OLE DB destination, and the Lookup transformation. 


You can use Query Builder to perform the following tasks: 


e Working with a graphical representation of a query or with SQL commands Query Builder 
includes a pane that displays your query graphically and a pane that displays the SQL text of your query. 
You can work in either the graphical pane or the text pane. Query Builder synchronizes the views so that 


they are always current. 


e Joining related tables If you add more than one table to your query, Query Builder automatically 
determines how the tables are related and constructs the appropriate join command. 


e Querying or updating databases You can use Query Builder to return data by using Transact-SQL 
SELECT statements and to create queries that update, add, or delete records in a database. 


e Viewing and editing results immediately You can run your query and work with a recordset in a grid 
that allows you to scroll through and edit records in the database. 


The graphical tools in the Query Builder dialog box let you construct queries using drag-and-drop operations. 
By default, the Query Builder dialog box constructs SELECT queries, but you can also build INSERT, UPDATE, or 
DELETE queries. All types of SQL statements can be parsed and run in the Query Builder dialog box. For more 
information about SQL statements in packages, see Integration Services (SSIS) Queries. 


To learn more about the Transact-SQL language and its syntax, see Transact-SQL Reference (Database Engine). 


You can also use variables in a query to provide values to an input parameter, to capture values of output 
parameters, and to store return codes. To learn more about using variables in the queries that packages use, see 
Execute SQL Task, OLE DB Source, and Integration Services (SSIS) Queries. To learn more about using variables 
in the Execute SQL Task, see Parameters and Return Codes in the Execute SQL Task and Result Sets in the Execute 
SQL Task. 


The Lookup and Fuzzy lookup transformations can also use variables with parameters and return codes. The 
information about the OLE DB source applies to these two transformations also. 


Options 
Toolbar 
Use the toolbar to manage datasets, select panes to display, and control query functions. 


VALUE DESCRIPTION 


Show/Hide Diagram Pane Shows or hides the Diagram pane. 

Show/Hide Grid Pane Shows or hides the Grid pane. 

Show/Hide SQL Pane Shows or hides the SQL pane. 

Show/Hide Results Pane Shows or hides the Results pane. 

Run Runs the query. Results are displayed in the result pane. 
Verify SQL Verifies that the SQL statement is valid. 

Sort Ascending Sorts output rows on the selected column in the grid pane, 


in ascending order. 


Sort Descending Sorts output rows on the selected column in the grid pane, 
in descending order. 


Remove Filter Select a column name in the grid pane, and then click 
Remove Filter to remove sort criteria for the column. 


Use Group By Adds GROUP BY functionality to the query. 


Add Table Adds a new table to the query. 


Query Definition 
The query definition provides a toolbar and panes in which to define and test the query. 


PANE DESCRIPTION 


Diagram pane Displays the query in a diagram. The diagram shows the 
tables included in the query, and how they are joined. Select 
or clear the check box next to a column in a table to add or 
remove it from the query output. 


When you add tables to the query, Query Builder creates 
joins between tables based on tables, depending on the keys 
in the table. To add a join, drag a field from one table onto a 
field in another table. To manage a join, right-click the join, 
and then select a menu option. 


Right-click the Diagram pane to add or remove tables, 
select all the tables, and show or hide panes. 


Grid pane Displays the query in a grid. You can use this pane to add to 
and remove columns from the query and change the 
settings for each column. 


SQL pane Displays the query as SQL text. Changes made in the 
Diagram pane and the Grid pane will appear here, and 
changes made here will appear in the Diagram pane and 
the Grid pane. 


PANE DESCRIPTION 


Results pane Displays the results of the query when you click Run on the 
toolbar. 
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Packages use transactions to bind the database actions that tasks perform into atomic units, and by doing this 
maintain data integrity. All Microsoft Integration Services container types-packages, the For Loop, Foreach Loop, 
and Sequence containers, and the task hosts that encapsulate each task-can be configured to use transactions. 
Integration Services provides three options for configuring transactions: NotSupported, Supported, and 
Required. 


e Required indicates that the container starts a transaction, unless one is already started by its parent 
container. If a transaction already exists, the container joins the transaction. For example, if a package that 
is not configured to support transactions includes a Sequence container that uses the Required option, 
the Sequence container would start its own transaction. If the package were configured to use the 
Required option, the Sequence container would join the package transaction. 


e Supported indicates that the container does not start a transaction, but joins any transaction started by 
its parent container. For example, if a package with four Execute SQL tasks starts a transaction and all four 
tasks use the Supported option, the database updates performed by the Execute SQL tasks are rolled 
back if any task fails. If the package does not start a transaction, the four Execute SQL tasks are not bound 
by a transaction, and no database updates except the ones performed by the failed task are rolled back. 


e NotSupported indicates that the container does not start a transaction or join an existing transaction. A 
transaction started by a parent container does not affect child containers that have been configured to 
not support transactions. For example, if a package is configured to start a transaction and a For Loop 
container in the package uses the NotSupported option, none of the tasks in the For Loop can roll back 
if they fail. 


You configure transactions by setting the TransactionOption property on the container. You can set this property 
by using the Properties window in SQL Server Data Tools (SSDT), or you can set the property 
programmatically. 





NOTE 


The TransactionOption property influences whether or not the value of the IsolationLevel property requested by a 
container is applied. For more information, see the description of the IsolationLevel property in the topic, Setting 
Package Properties. 





Configure a package to use transactions 


When you configure a package to use transactions, you have two options: 


e Have a single transaction for the package. In this case, it is the package itself that /n/tiates this transaction, 
whereas individual tasks and containers in the package participate in this single transaction. 


e Have multiple transactions in the package. In this case, the package supports transactions, but individual 
tasks and containers in the package actually initiate the transactions. 


The following procedures describe how to configure both options. 


Configure a package to use a single transaction 





In this option, the package itself initiates a single transaction. You configure the package to initiate this 
transaction by setting the TransactionOption property of the package to Required. 


Next, you enlist specific tasks and containers in this single transaction. To enlist a task or container ina 
transaction, you set the TransactionOption property of that task or container to Supported. 


1. In SQL Server Data Tools (SSDT), open the Integration Services project that contains the package you 
want to configure to use a transaction. 


2. In Solution Explorer, double-click the package to open it. 

3. Click the Control Flow tab. 

4. Right-click anywhere in the background of the control flow design surface, and then click Properties. 
5. In the Properties window, set the TransactionOption property to Required. 


6. On the design surface of the ControlFlow tab, right-click the task or the container that you want to 
enroll in the transaction, and then click Properties. 


7. Inthe Properties window, set the TransactionOption property to Supported. 





NOTE 


To enlist a connection in a transaction, enroll the tasks that use the connection in the transaction. For more 


information, see Integration Services (SSIS) Connections. 








8. Repeat steps 6 and 7 for each task and container that you want to enroll in the transaction. 


Configure a package to use multiple transactions 


In this option, the package itself supports transactions but does not start a transaction. You configure the 
package to support transactions by setting the TransactionOption property of the package to Supported. 


Next, you configure the desired tasks and containers inside the package to initiate or participate in transactions. 
To configure a task or container to initiate a transaction, you set the TransactionOption property of that task or 
container to Required. 


1. In SQL Server Data Tools (SSDT), open the Integration Services project that contains the package you 
want to configure to use transaction.s 


2. In Solution Explorer, double-click the package to open it. 
3. Click the Control Flow tab. 
4. Right-click anywhere in the background of the control flow design surface, and then click Properties. 


5. In the Properties window, set the TransactionOption property to Supported. 





NOTE 


The package supports transactions, but the transactions are started by task or containers in the package. 








6. On the design surface of the ControlFlow tab, right-click the task or the container in the package for 
which you want to start a transaction, and then click Properties. 


7. Inthe Properties window, set the TransactionOption property to Required. 


8. If a transaction is started by a container, right-click the task or the container that you want to enroll in the 
transaction, and then click Properties. 


9. In the Properties window, set the TransactionOption property to Supported. 


NOTE 


To enlist a connection in a transaction, enroll the tasks that use the connection in the transaction. For more 


information, see Integration Services (SSIS) Connections. 





10. Repeat steps 6 through 9 for each task and container that starts a transaction. 


Multiple transactions in a package 


It is possible for a package to include unrelated transactions in an Integration Services package. Any time a 
container in the middle of a nested container hierarchy does not support transactions, the containers above or 
below it in the hierarchy start separate transactions if they are configured to support transactions. The 
transactions commit or roll back in order from the innermost task in the nested container hierarchy to the 
package. However, after the inner transaction commits, it does not roll back if an outer transaction is aborted. 


Example of multiple transactions in a package 


For example, a package has a Sequence container that holds two Foreach Loop containers, and each container 
include two Execute SQL tasks. The Sequence container supports transactions, the Foreach Loop containers do 
not, and the Execute SQL tasks do. In this example, each Execute SQL task would start its own transaction and 
would not roll back if the transaction on the Sequence task was aborted. 


The TransactionOption properties of the Sequence container, Foreach Loop container and the Execute SQL tasks 
are set as follows: 


e The TransactionOption property of the Sequence container is set to Required. 

e The TransactionOption properties of the Foreach Loop containers are set to NotSupported. 

e The TransactionOption properties of the Execute SQL tasks are set to Required. 

The following diagram shows the five unrelated transactions in the package. One transaction is started by the 


Sequence container and four transactions are started by the Execute SQL tasks. 


Sequence Container 
Foreach Loop Container 


Execute SQL Task 
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Foreach Loop Container 


Execute SQL Task 


[ Execute SQL Task 





Inherited transactions 


A package can run another package by using the Execute Package task. The child package, which is the package 
run by the Execute Package task, may create its own package transaction, or it may inherit the parent package 


transaction. 
A child package inherits the parent package transaction if both of the following are true: 


e The package is invoked by an Execute Package task. 


e The Execute Package task that invoked the package also joined the parent package transaction. 


Containers and tasks in the child package cannot join the parent package transaction unless the child package 
itself joins the transaction. 


Example of inherited transactions 


In the following diagram, there are three packages that all use transactions. Each package contains multiple 
tasks. To emphasize the behavior of the transactions, only the Execute Package tasks are shown. Package A runs 
packages B and C. In turn, package B runs packages D and E, and package C runs package F. 


Packages and tasks have the following transaction attributes: 
e TransactionOption is set to Required on packages A and C 


e TransactionOption is set to Supported on packages B and D, and on the tasks Execute Package B, 
Execute Package D, and Execute Package F. 


e TransactionOption is set to NotSupported on package E, and on the tasks Execute Package C and 


Execute Package E. 


Execute Package B 
Execute Package C 
Execute Package D 
Execute Package E 


Execute Package F 





Only packages B, D, and F can inherit transactions from their parent packages. 
Packages B and D inherit the transaction that was started by package A. 
Package F inherits the transaction that was started by package C. 

Packages A and C control their own transactions. 


Package E does not use transactions. 


External Resources 


e Blog entry, How to Use Transactions in SQL Server Integration Services SSIS, on www.mssqltips.com 


See Also 


Inherited Transactions 
Multiple Transactions 


Deploy Integration Services (SSIS) Projects and 


Packages 
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Integration Services supports two deployment models, the project deployment model and the legacy package 


deployment model. The project deployment model enables you to deploy your projects to the Integration 


Services server. 


For more information about the legacy package deployment model, see Legacy Package Deployment (SSIS). 





NOTE 


packages without deploying the whole project. 


The project deployment model was introduced in SQL Server 2012 Integration Services (SSIS). With this deployment 
model, you were not able to deploy one or more packages without deploying the whole project. SQL Server 2016 
Integration Services (SSIS) introduced the Incremental Package Deployment feature, which lets you deploy one or more 








NOTE 


deploy SSIS packages to the following platforms: 


cloud. 





This article describes how to deploy SSIS packages in general, and how to deploy packages on premises. You can also 


e The Microsoft Azure cloud. For more info, see Lift and shift SQL Server Integration Services workloads to the 


e Linux. For more info, see Extract, transform, and load data on Linux with SSIS. 


Compare Project Deployment Model and legacy Package Deployment 


Model 


The type of deployment model that you choose for a project determines which development and administrative 


options are available for that project. The following table shows the differences and similarities between using 


the project deployment model and using the package deployment model. 


WHEN USING THE PROJECT DEPLOYMENT MODEL 


A project is the unit of deployment. 


Parameters are used to assign values to package properties. 


A project, containing packages and parameters, is built to a 
project deployment file (.ispac extension). 


A project, containing packages and parameters, is deployed 
to the SSISDB catalog on an instance of SQL Server. 


WHEN USING THE LEGACY PACKAGE DEPLOYMENT MODEL 


A package is the unit of deployment. 


Configurations are used to assign values to package 
properties. 


Packages (.dtsx extension) and configurations (.dtsConfig 
extension) are saved individually to the file system. 


Packages and configurations are copied to the file system on 
another computer. Packages can also be saved to the MSDB 
database on an instance of SQL Server. 





WHEN USING THE PROJECT DEPLOYMENT MODEL 


CLR integration is required on the database engine. 


Environment-specific parameter values are stored in 
environment variables. 


Projects and packages in the catalog can be validated on the 
server before execution. You can use SQL Server 
Management Studio, stored procedures, or managed code 
to perform the validation. 


Packages are executed by starting an execution on the 
database engine. A project identifier, explicit parameter 
values (optional), and environment references (optional) are 
assigned to an execution before it is started. 


You can also execute packages using dtExec. 


During execution, events that are produced by the package 
are captured automatically and saved to the catalog. You can 
query these events with Transact-SQL views. 


Packages are run in a separate Windows process. 


SQL Server Agent is used to schedule package execution. 


WHEN USING THE LEGACY PACKAGE DEPLOYMENT MODEL 


CLR integration is not required on the database engine. 


Environment-specific configuration values are stored in 
configuration files. 


Packages are validated just before execution. You can also 
validate a package with dtExec or managed code. 


Packages are executed using the dtExec and DTExecUI 
execution utilities. Applicable configurations are identified by 
command-prompt arguments (optional). 


During execution, events that are produced by a package are 
not captured automatically. A log provider must be added to 
the package to capture events. 


Packages are run in a separate Windows process. 


SQL Server Agent is used to schedule package execution. 


Features of Project Deployment Model 


The following table lists the features that are available to projects developed only for the project deployment 


model. 


FEATURE 


Parameters 


Environments 


DESCRIPTION 


A parameter specifies the data that will be used by a 
package. You can scope parameters to the package level or 
project level with package parameters and project 
parameters, respectively. Parameters can be used in 
expressions or tasks. When the project is deployed to the 
catalog, you can assign a literal value for each parameter or 
use the default value that was assigned at design time. In 
place of a literal value, you can also reference an 
environment variable. Environment variable values are 
resolved at the time of package execution. 


An environment is a container of variables that can be 
referenced by Integration Services projects. Each project can 
have multiple environment references, but a single instance 
of package execution can only reference variables from a 
single environment. Environments allow you to organize the 
values that you assign to a package. For example, you might 
have environments named "Dev", "test", and "Production". 


FEATURE DESCRIPTION 


Environment variables An environment variable defines a literal value that can be 
assigned to a parameter during package execution. To use an 
environment variable, create an environment reference (in 
the project that corresponds to the environment having the 
parameter), assign a parameter value to the name of the 
environment variable, and specify the corresponding 
environment reference when you configure an instance of 
execution. 


SSISDB catalog All Integration Services objects are stored and managed on 
an instance of SQL Server in a database referred to as the 
SSISDB catalog. The catalog allows you to use folders to 
organize your projects and environments. Each instance of 
SQL Server can have one catalog. Each catalog can have zero 
or more folders. Each folder can have zero or more projects 
and zero or more environments. A folder in the catalog can 
also be used as a boundary for permissions to Integration 
Services objects. 


Catalog stored procedures and views A large number of stored procedures and views can be used 
to manage Integration Services objects in the catalog. For 
example, you can specify values to parameters and 
environment variables, create and start executions, and 
monitor catalog operations. You can even see exactly which 
values will be used by a package before execution starts. 


Project Deployment 


At the center of the project deployment model is the project deployment file (.ispac extension). The project 
deployment file is a self-contained unit of deployment that includes only the essential information about the 
packages and parameters in the project. The project deployment file does not capture all of the information 
contained in the Integration Services project file (.dtproj extension). For example, additional text files that you 


use for writing notes are not stored in the project deployment file and thus are not deployed to the catalog. 


Permissions Required to Deploy SSIS Projects and Packages 


If you change the SSIS service account from the default, you may have to give additional permissions to the 
non-default service account before you can deploy packages successfully. If the non-default service account 
doesn't have the required permissions, you may see the following error message. 


A .NET Framework error occurred during execution of user-defined routine or aggregate 
"deploy_project_internal": System.ComponentModel.Win32Exception: A required privilege is not held by the 
client. 


This error is typically the result of missing DCOM permissions. To fix the error, do the following: 


1. Open the Component Services console (or run Dcomcnfg.exe). 


2. In the Component Services console, expand Component Services > Computers > My Computer > 
DCOM Config. 


3. In the list, locate Microsoft SQL Server Integration Services xx.0 for the version of SQL Server that 
you're using. For example, SQL Server 2016 is version 13. 


4. Right-click and select Properties. 
5. In the Microsoft SQL Server Integration Services 13.0 Properties dialog box, select the Security tab. 


6. For each of the three sets of permissions - Launch and Activation, Access, and Configuration - select 


Customize, then select Edit to open the Permission dialog box. 


7. Inthe Permission dialog box, add the non-default service account and grant Allow permissions as required. 
Typically, an account has Local Launch and Local Activation permissions. 


8. Click OK twice, then close the Component Services console. 


For more info about the error described in this section and about the permissions required by the SSIS service 
account, see the following blog post: 


e System.ComponentModel.Win32Exception: A required privilege is not held by the client while Deploying 
SSIS Project 


Deploy Projects to Integration Services Server 


In the current release of Integration Services, you can deploy your projects to the Integration Services server. 
The Integration Services server enables you to manage packages, run packages, and configure runtime values 
for packages by using environments. 





NOTE 

As in earlier versions of Integration Services, in the current release you can also deploy your packages to an instance of 
SQL Server and use Integration Services service to run and manage the packages. You use the package deployment 
model. For more information, see Legacy Package Deployment (SSIS). 





To deploy a project to the Integration Services server, complete the following tasks: 
1. Create an SSISDB catalog, if you haven't already. For more information, see SSIS Catalog. 


2. Convert the project to the project deployment model by running the Integration Services Project 
Conversion Wizard. For more information, see the following instructions: To convert a project to the 
project deployment model 


e If you created the project in SQL Server 2014 Integration Services (SSIS) or later, by default the 
project uses the project deployment model. 


e If you created the project in an earlier release of Integration Services, after you open the project 
file in Visual Studio, convert the project to the project deployment model. 





NOTE 


If the project contains one or more datasources, the datasources are removed when the project 
conversion is completed. To create a connection to a data source that the packages in the project can 
share, add a connection manager at the project level. For more information, see Add, Delete, or Share a 
Connection Manager in a Package. 











Depending on whether you run the Integration Services Project Conversion Wizard from 
Visual Studio or from SQL Server Management Studio, the wizard performs different conversion 
tasks. 


o If you run the wizard from Visual Studio, the packages contained in the project are 
converted from Integration Services 2005, 2008, or 2008 R2 to the format that is used by 
the current version of Integration Services. The original project (.dtproj) and package (.dtsx) 
files are upgraded. 


o If you run the wizard from SQL Server Management Studio, the wizard generates a project 
deployment file (.ispac) from the packages and configurations contained in the project. The 
original package (.dtsx) files are not upgraded. 





4. 


You can select an existing file or create a new file, in the Selection Destination page of the 
wizard. 


To upgrade package files when a project is converted, run the Integration Services 
Project Conversion Wizard from Visual Studio. To upgrade package files separately from 
a project conversion, run the Integration Services Project Conversion Wizard from 
SQL Server Management Studio and then run the SSIS Package Upgrade Wizard. If you 
upgrade the package files separately, ensure that you save the changes. Otherwise, when 
you convert the project to the project deployment model, any unsaved changes to the 


package are not converted. 


For more information on package upgrade, see Upgrade Integration Services Packages and Upgrade 
Integration Services Packages Using the SSIS Package Upgrade Wizard. 


. Deploy the project to the Integration Services server. For more information, see the instructions below: To 


deploy a project to the Integration Services Server. 


(Optional) Create an environment for the deployed project. 


To convert a project to the project deployment model 


1. 


2: 


Open the project in Visual Studio, and then in Solution Explorer, right-click the project and click Convert 
to Project Deployment Model. 


-Or- 
From Object Explorer in Management Studio, right-click the Projects node and select Import Packages. 


Complete the wizard. 


To deploy a project to the Integration Services Server 


1. 


Open the project in Visual Studio, and then From the Project menu, select Deploy to launch the 
Integration Services Deployment Wizard. 


or 


In SQL Server Management Studio, expand the Integration Services > SSISDB node in Object Explorer, 
and locate the Projects folder for the project you want to deploy. Right-click the Projects folder, and then 
click Deploy Project. 


or 


From the command prompt, run isdeploymentwizard.exe from %ProgramFiles%\Microsoft SQL 
Server\130\DTS\Binn. On 64-bit computers, there is also a 32-bit version of the tool in 
%ProgramFiles(x86)%\Microsoft SQL Server\130\DTS\Binn. 


. On the Select Source page, click Project deployment file to select the deployment file for the project. 


or 


Click Integration Services catalog to select a project that has already been deployed to the SSISDB 
catalog. 


. Complete the wizard. 


Deploy Packages to Integration Services Server 


The Incremental Package Deployment feature introduced in SQL Server 2016 Integration Services (SSIS) lets 


you deploy one or more packages to an existing or new project without deploying the whole project. 


Deploy packages by using the Integration Services Deployment Wizard 


1. From the command prompt, run isdeploymentwizard.exe from %ProgramFiles%\Microsoft SQL 
Server\130\DTS\Binn. On 64-bit computers, there is also a 32-bit version of the tool in 
%ProgramFiles(x86)%\Microsoft SQL Server\130\DTS\Binn. 


2. On the Select Source page, switch to Package Deployment model. Then, select the folder that 
contains source packages and configure the packages. 


3. Complete the wizard. Follow the remaining steps described in Package Deployment Model. 


Deploy packages by using SQL Server Management Studio 


1. In SQL Server Management Studio, expand the Integration Services Catalogs > SSISDB node in 
Object Explorer. 


2. Right-click the Projects folder, and then click Deploy Projects. 
3. If you see the Introduction page, click Next to continue. 


4. On the Select Source page, switch to Package Deployment model. Then, select the folder that 
contains source packages and configure the packages. 


5. Complete the wizard. Follow the remaining steps described in Package Deployment Model. 


Deploy packages by using SQL Server Data Tools (Visual Studio) 
1. In Visual Studio, with an Integration Services project open, select the package or packages that you want 


to deploy. 


2. Right-click and select Deploy Package. The Deployment Wizard opens with the selected packages 
configured as the source packages. 


3. Complete the wizard. Follow the remaining steps described in Package Deployment Model. 


Deploy packages by using the deploy_packages stored procedure 

You can use the [catalog].[deploy_packages] stored procedure to deploy one or more SSIS packages to the 
SSIS Catalog. The following code example demonstrates the use of this stored procedure to deploy packages to 
an SSIS server. For more info, see catalog.deploy_packages. 


private static void Main(string[] args) 


{ 

// Connection string to SSISDB 

var connectionString = "Data Source=.;Initial Catalog=SSISDB; Integrated 
Security=True;MultipleActiveResultSets=false"; 


using (var sqlConnection = new SqlConnection(connectionString) ) 
{ 


sqlConnection.Open(); 


var sqlCommand = new SqlCommand 


{ 
Connection = sqlConnection, 
CommandType = CommandType.StoredProcedure, 
CommandText = "[catalog].[deploy_packages]" 
}3 


var packageData = Encoding.UTF8.GetBytes(File.ReadAllText(@"C:\Test\Package.dtsx")); 


// DataTable: name is the package name without extension and package data is byte array of package. 
var packageTable = new DataTable(); 

packageTable.Columns.Add("name", typeof(string) ); 

packageTable.Columns.Add("package_data", typeof(byte[])); 

packageTable.Rows.Add("Package", packageData) ; 


// Set the destination project and folder which is named Folder and Project. 

sqlCommand.Parameters.Add(new SqlParameter("@folder_name", SqlDbType.NVarChar, 
ParameterDirection.Input, "Folder", -1)); 

sqlCommand.Parameters.Add(new SqlParameter("@project_name", SqlDbType.NVarChar, 
ParameterDirection.Input, "Project", -1)); 

sqlCommand.Parameters.Add(new SqlParameter("@packages_table", SqlDbType.Structured, 
ParameterDirection.Input, packageTable, -1)); 


var result = sqlCommand.Parameters.Add("RetVal", SqlDbType. Int) ; 
result.Direction = ParameterDirection.ReturnValue; 


sqlcommand.ExecuteNonQuery() ; 


‘| Bee 





Deploy packages using the Management Object Model API 


The following code example demonstrates the use of the Management Object Model API to deploy packages to 


server. 


static void Main() 
{ 
// Before deploying packages, make sure the destination project exists in SSISDB. 
var connectionString = "Data Source=.;Integrated Security=True;MultipleActiveResultSets=false"; 
var catalogName = "SSISDB"; 
var folderName = "Folder"; 
var projectName = "Project"; 


// Get the folder instance. 

var sqlConnection = new SqlConnection(connectionString) ; 

var store = new Microsoft.SqlServer .Management.IntegrationServices.IntegrationServices(sqlConnection) ; 
var folder = store.Catalogs[catalogName].Folders[folderName] ; 


// Key is package name without extension and value is package binaries. 
var packageDict = new Dictionary<string, string>(); 


var packageData = File.ReadAllText(@"C:\Folder\Package.dtsx") ; 
packageDict.Add("Package", packageData) ; 


// Deploy package to the destination project. 
folder .DeployPackages(projectName, packageDict) ; 


| Pad 





Convert to Package Deployment Model Dialog Box 


The Convert to Package Deployment Model command allows you to convert a package to the package 
deployment model after checking the project and each package in the project for compatibility with that model. 
If a package uses features unique to the project deployment model, such as parameters, then the package 
cannot be converted. 


Converting a package to the package deployment model requires two steps. 


1. When you select the Convert to Package Deployment Model command from the Project menu, the 
project and each package are checked for compatibility with this model. The results are displayed in the 
Results table. 


If the project or a package fails the compatibility test, click Failed in the Result column for more 
information. Click Save Report to save a copy of this information to a text file. 


2. If the project and all packages pass the compatibility test, then click OK to convert the package. 


NOTE 


To convert a project to the project deployment model, use the Integration Services Project Conversion Wizard. For 


more information, see Integration Services Project Conversion Wizard. 





Integration Services Deployment Wizard 
The Integration Services Deployment Wizard supports two deployment models: 


e Project deployment model 


e Package deployment model 


The Project Deployment model allows you to deploy a SQL Server Integration Services (SSIS) project as a 
single unit to the SSIS Catalog. 


The Package Deployment model allows you to deploy packages that you have updated to the SSIS Catalog 
without having to deploy the whole project. 





NOTE 
The Wizard default deployment is the Project Deployment model. 





Launch the wizard 


Launch the wizard by either: 
e Typing "SQL Server Deployment Wizard" in Windows Search 
or 


e Search for the executable file 1s DeploymentWizard.exe under the SQL Server installation folder; for 
example: "C:\Program Files (x86)\Microsoft SQL Server\130\DTS\Binn". 


NOTE: If you see the Introduction page, click Next to switch to the Select Source page. 


The settings on this page are different for each deployment model. Follow steps in the Project Deployment 
Model section or Package Deployment Model section based on the model you selected in this page. 


Project Deployment Model 

Select Source 

To deploy a project deployment file that you created, select Project deployment file and enter the path to the 
ispac file. To deploy a project that resides in the Integration Services catalog, select Integration Services 
catalog, and then enter the server name and the path to the project in the catalog. Click Next to see the Select 
Destination page. 


Select Destination 

To select the destination folder for the project in the Integration Services catalog, enter the SQL Server instance 
or click Browse to select from a list of servers. Enter the project path in SSISDB or click Browse to select it. Click 
Next to see the Review page. 


Review (and deploy) 


The page allows you to review the settings you have selected. You can change your selections by clicking 
Previous, or by clicking any of the steps in the left pane. Click Deploy to start the deployment process. 


Results 

After the deployment process is complete, you should see the Results page. This page displays the success or 
failure of each action. If the action fails, click the Failed in the Result column to display an explanation of the 
error. Click Save Report... to save the results to an XML file or Click Close to exit the wizard. 


Package Deployment Model 

Select Source 

The Select Source page in the Integration Services Deployment Wizard shows settings specific to the 
package deployment model when you selected the Package Deployment option for the deployment model. 


To select the source packages, click the Browse... button to select the folder that contains the packages or type 
the folder path in the Packages folder path textbox and click Refresh button at the bottom of the page. Now, 
you should see all the packages in the specified folder in the list box. By default, all the packages are selected. 
Click the checkbox in the first column to choose which packages you want to be deployed to server. 


Refer to the Status and Message columns to verify the status of package. If the status is set to Ready or 
Warning, the deployment wizard would not block the deployment process. If the status is set to Error, the 
wizard wouldn't proceed to deploy the selected packages. To view the detailed Warning or Error messages, click 


the link in the Message column. 


If the sensitive data or package data are encrypted with a password, type the password in the Password column 
and click the Refresh button to verify whether the password is accepted. If the password is correct, the status 
would change to Ready and the warning message will disappear. If there are multiple packages with the same 
password, select the packages with the same encryption password, type the password in the Password textbox 
and select the Apply button. The password would be applied to the selected packages. 


If the status of all the selected packages is not set to Error, the Next button will be enabled so that you can 
continue with the package deployment process. 


Select Destination 

After selecting package sources, click the Next button to switch to the Select Destination page. Packages must 
be deployed to a project in the SSIS Catalog (SSISDB). Before deploying packages, ensure the destination project 
already exists in the SSIS Catalog. Create an empty project if a project does not exist. In the Select Destination 
page, type the server name in the Server Name textbox or click the Browse... button to select a server 
instance. Then click the Browse... button next to the Path textbox to specify the destination project. If the project 
does not exist, click the New project... button to create an empty project as the destination project. The project 
must be created under a folder. 


Review and deploy 

Click Next on the Select Destination page to switch to the Review page in the Integration Services 
Deployment Wizard. In the review page, review the summary report about the deployment action. After the 
verification, click the Deploy button to perform the deployment action. 


Results 

After the deployment is complete, you should see the Results page. On the Results page, review results from 
each step in the deployment process. Click Save Report to save the deployment report or Close to the close 
the wizard. 


Create and Map a Server Environment 


You create a server environment to specify runtime values for packages contained in a project you've deployed 
to the Integration Services server. You can then map the environment variables to parameters, for a specific 
package, for entry-point packages, or for all the packages in a given project. An entry-point package is typically 
a parent package that executes a child package. 





IMPORTANT 


For a given execution, a package can execute only with the values contained in a single server environment. 





You can query views for a list of server environments, environment references, and environment variables. You 


can also call stored procedures to add, delete, and modify environments, environment references, and 
environment variables. For more information, see the Server Environments, Server Variables, and Server 


Environment References section in SSIS Catalog. 


To create and use a server environment 


1. In Management Studio, expand the Integration Services Catalogs SSISDB node in Object Explorer, and 
locate the Environments folder of the project for which you want to create an environment. 


2. Right-click the Environments folder, and then click Create Environment. 
3. Type a name for the environment and optionally add a description. Click OK. 
4. Right-click the new environment and then click Properties. 


5. On the Variables page, do the following to add a variable. 


10. 


11. 


12. 


i 


a. Select the Type for the variable. The name of the variable does not need to match the name of the 
project parameter that you map to the variable. 


b. Enter an optional Description for the variable. 
c. Enter the Value for the environment variable. 


For information about the rules for environment variable names, see the Environment Variable 
section in SSIS Catalog. 


d. Indicate whether the variable contains sensitive value, by selecting or clearing the Sensitive 
checkbox. 


If you select Sensitive, the variable value does not display in the Value field. 


Sensitive values are encrypted in the SSISDB catalog. For more information about the encryption, 
see SSIS Catalog. 


. On the Permissions page, grant or deny permissions for selected users and roles by doing the following. 


a. Click Browse, and then select one or more users and roles in the Browse All Principals dialog 
box. 


b. In the Logins or roles area, select the user or role that you want to grant or deny permissions for. 


c. In the Explicit area, select Grant or Deny next to each permission. 


. To script the environment, click Script. By default, the script displays in a new Query Editor window. 





TIP 


You need to click Script after you've made one or changes to the environment properties, such as adding a 


variable, and before you click OK in the Environment Properties dialog box. Otherwise, a script is not 


generated. 








. Click OK to save your changes to the environment properties. 


. Under the SSISDB node in Object Explorer, expand the Projects folder, right-click the project, and then 


click Configure. 


On the References page, click Add to add an environment, and then click OK to save the reference to 
the environment. 


Right-click the project again, and then click Configure. 


To map the environment variable to a parameter that you added to the package at design-time or toa 
parameter that was generated when you converted the Integration Services project to the project 
deployment model, do the following: 


a. In the Parameters tab on the Parameters page, click the browse button next to the Value field. 
b. Click Use environment variable, and then select the environment variable you created. 


To map the environment variable to a connection manager property, do the following. Parameters are 
automatically generated on the SSIS server for the connection manager properties. 


a. Inthe Connection Managers tab on the Parameters page, click the browse button next to the 
Value field. 


b. Click Use environment variable, and then select the environment variable you created. 


14. Click OK twice to save your changes. 


Deploy and Execute SSIS Packages using Stored Procedures 


When you configure an Integration Services project to use the project deployment model, you can use stored 
procedures in the SSIS catalog to deploy the project and execute the packages. For information about the project 
deployment model, see Deployment of Projects and Packages. 


You can also use SQL Server Management Studio or SQL Server Data Tools (SSDT) to deploy the project and 
execute the packages. For more information, see the topics in the See Also section. 





TIP 


You can easily generate the Transact-SQL statements for the stored procedures listed in the procedure below, with the 
exception of catalog.deploy_project, by doing the following: 


1. In SQL Server Management Studio, expand the Integration Services Catalogs node in Object Explorer and 


navigate to the package you want to execute. 
2. Right-click the package, and then click Execute. 


3. As needed, set parameters values, connection manager properties, and options in the Advanced tab such as the 


logging level. 
For more information about logging levels, see Enable Logging for Package Execution on the SSIS Server. 


4. Before clicking OK to execute the package, click Script. The Transact-SQL appears in a Query Editor window in 
SQL Server Management Studio. 





To deploy and execute a package using stored procedures 


1. Call catalog.deploy_project (SSISDB Database) to deploy the Integration Services project that contains the 
package to the Integration Services server. 


To retrieve the binary contents of the Integration Services project deployment file, for the 
@project_stream parameter_, use a SELECT statement with the OPENROWSET function and the BULK 
rowset provider. The BULK rowset provider enables you to read data from a file. The SINGLE_BLOB 
argument for the BULK rowset provider returns the contents of the data file as a single-row, single- 
column rowset of type varbinary(max). For more information, see OPENROWSET (Transact-SQL). 


In the following example, the SSISPackages_ProjectDeployment project is deployed to the SSIS Packages 
folder on the Integration Services server. The binary data is read from the project file 
(SSISPackage_ProjectDeployment.ispac) and is stored in the _@ProjectBinary parameter of type 
varbinary(max). The @ProjectBinary parameter value is assigned to the @project_stream parameter. 


DECLARE @ProjectBinary as varbinary(max) 

DECLARE @operation_id as bigint 

Set @ProjectBinary = (SELECT * FROM OPENROWSET(BULK '‘C:\MyProjects\ 
SSISPackage_ProjectDeployment.ispac', SINGLE_BLOB) as BinaryData) 


Exec catalog.deploy_project @folder_name = 'SSIS Packages’, @project_name = 
"DeployViaStoredProc_SSIS', @Project_Stream = @ProjectBinary, @operation_id = @operation_id out 


2. Call catalog.create_execution (SSISDB Database) to create an instance of the package execution, and 
optionally call catalog.set_execution_parameter_value (SSISDB Database) to set runtime parameter 
values. 


In the following example, catalog.create_execution creates an instance of execution for package.dtsx that 





is contained in the SSISPackage_ProjectDeployment project. The project is located in the SSIS Packages 
folder. The execution_id returned by the stored procedure is used in the call to 
catalog.set_execution_parameter_value. This second stored procedure sets the LOGGING_LEVEL 
parameter to 3 (verbose logging) and sets a package parameter named Parameter1 to a value of 1. 


For parameters such as LOGGING_LEVEL the object_type value is 50. For package parameters the 
object_type value is 30. 


Declare @execution_id bigint 

EXEC [SSISDB].[catalog].[create_execution] @package_name=N'Package.dtsx', @execution_id=@execution_id 
OUTPUT, @folder_name=N'SSIS Packages', @project_name=N'SSISPackage ProjectDeployment' , 
@use32bitruntime=False, @reference_id=1 


Select @execution_id 

DECLARE @var@ smallint = 3 

EXEC [SSISDB].[catalog].[set_execution_parameter_value] @execution_id, @object_type=50, 
@parameter_name=N'LOGGING_LEVEL', @parameter_value=@var@ 


DECLARE @vari1 int = 1 
EXEC [SSISDB].[catalog].[set_execution_parameter_value] @execution_id, @object_type=30, 
@parameter_name=N'Parameter1', @parameter_value=@var1 


GO 


3. Call catalog.start_execution (SSISDB Database) to execute the package. 


In the following example, a call to catalog.start_execution is added to the Transact-SQL to start the 
package execution. The execution_id returned by the catalog.create_execution stored procedure is used. 


Declare @execution_id bigint 

EXEC [SSISDB].[catalog].[create_execution] @package_name=N'Package.dtsx', @execution_id=@execution_id 
OUTPUT, @folder_name=N'SSIS Packages', @project_name=N'SSISPackage ProjectDeployment' , 
@use32bitruntime=False, @reference_id=1 


Select @execution_id 

DECLARE @var@ smallint = 3 

EXEC [SSISDB].[catalog].[set_execution_parameter_value] @execution_id, @object_type=50, 
@parameter_name=N'LOGGING_LEVEL', @parameter_value=@var@ 


DECLARE @vari1 int = 1 
EXEC [SSISDB].[catalog].[set_execution_parameter_value] @execution_id, @object_type=30, 


@parameter_name=N'Parameter1', @parameter_value=@var1 


EXEC [SSISDB].[catalog].[start_execution] @execution_id 
GO 


To deploy a project from server to server using stored procedures 


You can deploy a project from server to server by using the catalog.get_project (SSISDB Database) and 
catalog.deploy_project (SSISDB Database) stored procedures. 


You need to do the following before running the stored procedures. 


@ Create a linked server object. For more information, see Create Linked Servers (SQL Server Database 
Engine). 


On the Server Options page of the Linked Server Properties dialog box, set RPC and RPC Out to 
True. Also, set Enable Promotion of Distributed Transactions for RPC to False. 


e Enable dynamic parameters for the provider you selected for the linked server, by expanding the 


Providers node under Linked Servers in Object Explorer, right-clicking the provider, and then clicking 
Properties. Select Enable next to Dynamic parameter. 


e Confirm that the Distributed Transaction Coordinator (DTC) is started on both servers. 


Call catalog.get_project to return the binary for the project, and then call catalog.deploy_project. The value 
returned by catalog.get_project is inserted into a table variable of type varbinary(max). The linked server can't 
return results that are varbinary(max). 


In the following example, catalog.get_project returns a binary for the SSISPackages project on the linked server. 
The catalog.deploy_project deploys the project to the local server, to the folder named DestFolder. 


declare @resultsTableVar table ( 
project_binary varbinary(max) 


) 


INSERT @resultsTableVar (project_binary) 
EXECUTE [MyLinkedServer].[SSISDB].[catalog].[get_project] ‘Packages', 'SSISPackages' 


declare @project_binary varbinary(max) 
select @project_binary = project_binary from @resultsTableVar 


exec [SSISDB].[CATALOG].[deploy_project] 'DestFolder', 'SSISPackages', @project_binary 


Integration Services Project Conversion Wizard 


The Integration Services Project Conversion Wizard converts a project to the project deployment model. 





NOTE 
If the project contains one or more datasources, the datasources are removed when the project conversion is completed. 
To create a connection to a data source that can be shared by the packages in the project, add a connection manager at 


the project level. For more information, see Add, Delete, or Share a Connection Manager in a Package. 





What do you want to do? 

e@ Open the Integration Services Project Conversion Wizard 
e@ Set Options on the Locate Packages Page 

e Set Options on the Select Packages Page 

e@ Set Options on the Select Destination Page 

e Set Options on the Specify Project Properties Page 

e Set Options on the Update Execute Package Task Page 
e Set Options on the Select Configurations Page 

e Set Options on the Create Parameters Page 

@ Set Options on the Configure Parameters Page 

e Set the Options on the Review page 

@ Set the Options on the Perform Conversion 


Open the Integration Services Project Conversion Wizard 





Do one of the following to open the Integration Services Project Conversion Wizard. 


e@ Open the project in Visual Studio, and then in Solution Explorer, right-click the project and click Convert 
to Project Deployment Model. 


e From Object Explorer in Management Studio, right-click the Projects node in the Integration Services 
Catalog and select Import Packages. 


Depending on whether you run the Integration Services Project Conversion Wizard from Visual Studio or 
from SQL Server Management Studio, the wizard performs different conversion tasks. 


Set Options on the Locate Packages Page 


NOTE 


The Locate Packages page is available only when you run the wizard from Management Studio. 





The following option displays on the page when you select File system in the Source drop-down list. Select 
this option when the package is resides in the file system. 


Folder 
Type the package path, or navigate to the package by clicking Browse. 


The following options display on the page when you select SSIS Package Store in the Source drop-down list. 
For more information about the package store, see Package Management (SSIS Service). 


Server 


Type the server name or select the server. 


Folder 
Type the package path, or navigate to the package by clicking Browse. 


The following options display on the page when you select Microsoft SQL Server in the Source drop-down 
list. Select this option when the package resides in Microsoft SQL Server. 


Server 


Type the server name or select the server. 


Use Windows authentication 
Microsoft Windows Authentication mode allows a user to connect through a Windows user account. If you use 
Windows Authentication, you do not need to provide a user name or password. 


Use SQL Server authentication 

When a user connects with a specified login name and password from a non-trusted connection, SQL Server 
authenticates the connection by checking to see if a SQL Server login account has been set up and if the 
specified password matches the one previously recorded. If SQL Server does not have a login account set, 


authentication fails, and the user receives an error message. 


User name 
Specify a user name when you are using SQL Server Authentication. 


Password 
Provide the password when you are using SQL Server Authentication. 


Folder 
Type the package path, or navigate to the package by clicking Browse. 


Set Options on the Select Packages Page 


Package Name 


Lists the package file. 


Status 
Indicates whether a package is ready to convert to the project deployment model. 


Message 
Displays a message associated with the package. 


Password 
Displays a password associated with the package. The password text is hidden. 


Apply to selection 
Click to apply the password in the Password text box, to the selected package or packages. 


Refresh 
Refreshes the list of packages. 


Set Options on the Select Destination Page 


On this page, specify the name and path for a new project deployment file (.ispac) or select an existing file. 





NOTE 


The Select Destination page is available only when you run the wizard from Management Studio. 





Output path 
Type the path for the deployment file or navigate to the file by clicking Browse. 


Project name 
Type the project name. 


Protection level 
Select the protection level. For more information, see Access Control for Sensitive Data in Packages. 


Project description 
Type an optional description for the project. 


Set Options on the Specify Project Properties Page 





NOTE 


The Specify Project Properties page is available only when you run the wizard from Visual Studio. 





Project name 


Lists the project name. 


Protection level 
Select a protection level for the packages contained in the project. For more information about protection levels, 
see Access Control for Sensitive Data in Packages. 


Project description 
Type an optional project description. 


Set Options on the Update Execute Package Task Page 


Update Execute Package Tasks contain in the packages, to use a project-based reference. For more information, 
see Execute Package Task Editor. 


Parent Package 
Lists the name of the package that executes the child package using the Execute Package task. 


Task name 
Lists the name of the Execute Package task. 


Original reference 
Lists the current path of the child package. 


Assign reference 
Select a child package stored in the project. 


Set Options on the Select Configurations Page 


Select the package configurations that you want to replace with parameters. 


Package 
Lists the package file. 


Type 
Lists the type of configuration, such as an XML configuration file. 


Configuration String 
Lists the path of the configuration file. 


Status 
Displays a status message for the configuration. Click the message to view the entire message text. 


Add Configurations 
Add package configurations contained in other projects to the list of available configurations that you want to 


replace with parameters. You can select configurations stored in a file system or stored in SQL Server. 


Refresh 
Click to refresh the list of configurations. 


Remove configurations from all packages after conversion 
It is recommended that you remove all configurations from the project by selecting this option. 


If you don't select this option, only the configurations that you selected to replace with parameters are removed. 


Set Options on the Create Parameters Page 


Select the parameter name and scope for each configuration property. 


Package 
Lists the package file. 


Parameter Name 


Lists the parameter name. 


Scope 
Select the scope of the parameter, either package or project. 


Set Options on the Configure Parameters Page 


Name 
Lists the parameter name. 


Scope 
Lists the scope of the parameter. 


Value 
Lists the parameter value. 


Click the ellipsis button next to the value field to configure the parameter properties. 


In the Set Parameter Details dialog box, you can edit the parameter value. You can also specify whether the 


parameter value must be provided when you run the package. 


You can modify value in the Parameters page of the Configure dialog box in Management Studio, by clicking 
the browse button next to the parameter. The Set Parameter Value dialog box appears. 


The Set Parameter Details dialog box also lists the data type of the parameter value and the origin of the 


parameter. 


Set the Options on the Review page 


Use the Review page to confirm the options that you've selected for the conversion of the project. 


Previous 


Click to change an option. 


Convert 
Click to convert the project to the project deployment model. 


Set the Options on the Perform Conversion 


The Perform Conversion page shows status of the project conversion. 


Action 


Lists a specific conversion step. 


Result 
Lists the status of each conversion step. Click the status message for more information. 


The project conversion is not saved until the project is saved in Visual Studio. 


Save report 
Click to save a summary of the project conversion in an .xml file. 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


SQL Server Integration Services includes tools and wizards that make it simple to deploy packages from the 
development computer to the production server or to other computers. 


There are four steps in the package deployment process: 


1. The first step is optional and involves creating package configurations that update properties of package 
elements at run time. The configurations are automatically included when you deploy the packages. 


2. The second step is to build the Integration Services project to create a package deployment utility. The 
deployment utility for the project contains the packages that you want to deploy 


3. The third step is to copy the deployment folder that was created when you built the Integration Services 
project to the target computer. 


4. The fourth step is to run, on the target computer, the Package Installation Wizard to install the packages 
to the file system or to an instance of SQL Server. 


Package Configurations 


SQL Server Integration Services provides package configurations that you can use to update the values of 
properties at run time. 


NOTE: Configurations are available for the package deployment model. Parameters are used in place of 
configurations for the project deployment model. The project deployment model enables you to deploy 
Integration Services projects to the Integration Services server. For more information about the deployment 
models, see Deployment of Projects and Packages. 


A configuration is a property/value pair that you add to a completed package. Typically, you create a package set 
properties on the package objects during package development, and then add the configuration to the package. 
When the package runs, it gets the new values of the property from the configuration. For example, by using a 
configuration, you can change the connection string of a connection manager, or update the value of a variable. 


Package configurations provide the following benefits: 


e Configurations make it easier to move packages from a development environment to a production 
environment. For example, a configuration can update the path of a source file, or change the name of a 
database or server. 


e Configurations are useful when you deploy packages to many different servers. For example, a variable in 
the configuration for each deployed package can contain a different disk space value, and if the available 
disk space does not meet this value, the package does not run. 


e Configurations make packages more flexible. For example, a configuration can update the value of a 
variable that is used in a property expression. 


Integration Services supports several different methods of storing package configurations, such as XML files, 
tables in a SQL Server database, and environment and package variables. 


Each configuration is a property/value pair. The XML configuration file and SQL Server configuration types can 


include multiple configurations. 


The configurations are included when you create a package deployment utility for installing packages. When 
you install the packages, the configurations can be updated as a step in the package installation. 


Understanding How Package Configurations Are Applied at Run Time 


When you use the dtexec command prompt utility (dtexec.exe) to run a deployed package, the utility applies 
package configurations twice. The utility applies configurations both before and after it applies the options that 
you specified on command line. 


As the utility loads and runs the package, events occur in the following order: 
1. The dtexec utility loads the package. 


2. The utility applies the configurations that were specified in the package at design time and in the order 
that is specified in the package. (The one exception to this is the Parent Package Variables configurations. 
The utility applies these configurations only once and later in the process.) 


3. The utility then applies any options that you specified on the command line. 


4. The utility then reloads the configurations that were specified in the package at design time and in the 
order specified in the package. (Again, the exception to this rule is the Parent Package Variables 
configurations). The utility uses any command-line options that were specified to reload the 
configurations. Therefore, different values might be reloaded from a different location. 


5. The utility applies the Parent Package Variable configurations. 
6. The utility runs the package. 
The way in which the dtexec utility applies configurations affects the following command-line options: 


e You can use the /Connection or /Set option at run time to load package configurations from a location 
other than the location that you specified at design time. 


e You can use the /ConfigFile option to load additional configurations that you did not specify at design 
time. 


However, these command-line options do have some restrictions: 


e You cannot use the /Set or the /Connection option to override single values that are also set by a 
configuration. 


e You cannot use the /ConfigFile option to load configurations that replace the configurations that you 
specified at design time. 


For more information about these options, and how the behavior of these options differs between SQL Server 
2019 Integration Services (SSIS) and earlier versions, see Behavior Changes to Integration Services Features in 
SQL Server 2016. 


Package Configuration Types 


The following table describes the package configuration types. 
TYPE DESCRIPTION 


XML configuration file An XML file contains the configurations. The XML file can 
include multiple configurations. 


Environment variable An environment variable contains the configuration. 


TYPE DESCRIPTION 
Registry entry A Registry entry contains the configuration. 


Parent package variable A variable in the package contains the configuration. This 
configuration type is typically used to update properties in 
child packages. 


SQL Server table A table in a SQL Server database contains the configuration. 
The table can include multiple configurations. 


XML Configuration Files 
If you select the XML configuration file configuration type, you can create a new configuration file, reuse an 


existing file and add new configurations, or reuse an existing file but overwrite existing file content. 
An XML configuration file includes two sections: 


e Aheading that contains information about the configuration file. This element includes attributes such as 
when the file was created and the name of the person who generated the file. 


e Configuration elements that contain information about each configuration. This element includes 


attributes such as the property path and the configured value of a property. 


The following XML code demonstrates the syntax of an XML configuration file. This example shows a 
configuration for the Value property of an integer variable named myvar . 


\<?xml version="1.0"?> 
<DTSConfiguration> 
<DTSConfigurationHeading> 
<DTSConfigurationFileInfo 
GeneratedBy="DomainName\UserName" 
GeneratedFromPackageName="Package” 
GeneratedFromPackageID="{2AFQ6766-817A-4E28-9878 -@DE37A150648}" 
GeneratedDate="2/01/2005 5:58:09 PM"/> 
</DTSConfigurationHeading> 
<Configuration ConfiguredType="Property" Path="\Package.Variables[User: :MyVar].Value" ValueType="Int32"> 
<ConfiguredValue>@</ConfiguredValue> 
</Configuration> 
</DTSConfiguration> 
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Registry Entry 

If you want to use a Registry entry to store the configuration, you can either use an existing key or create a new 
key in HKEY_CURRENT_USER. The Registry key that you use must have a value named Value. The value can bea 
DWORD or a String. 


If you select the Registry entry configuration type, you type the name of the Registry key in the Registry entry 
box. The format is <registry key>. If you want to use a Registry key that is not at the root of 
HKEY_CURRENT_USER, use the format <Registry key\registry key\...> to identify the key. For example, to use the 
MyPackage key located in SSISPackages, type SSISPackages\My Package. 


SQL Server 

If you select the SQL Server configuration type, you specify the connection to the SQL Server database in 
which you want to store the configurations. You can save the configurations to an existing table or create a new 
table in the specified database. 


The following SQL statement shows the default CREATE TABLE statement that the Package Configuration Wizard 
provides. 


CREATE TABLE [dbo].[SSIS Configurations ] 


( 

ConfigurationFilter NVARCHAR(255) NOT NULL, 
ConfiguredValue NVARCHAR(255) NULL, 
PackagePath NVARCHAR(255) NOT NULL, 
ConfiguredValueType NVARCHAR(2@) NOT NULL 

) 


The name that you provide for the configuration is the value stored in the ConfigurationFilter column. 


Direct and Indirect Configurations 


Integration Services provides direct and indirect configurations. If you specify configurations directly, Integration 
Services creates a direct link between the configuration item and the package object property. Direct 
configurations are a better choice when the location of the source does not change. For example, if you are sure 


that all deployments in the package use the same file path, you can specify an XML configuration file. 


Indirect configurations use environment variables. Instead of specifying the configuration setting directly, the 
configuration points to an environment variable, which in turn contains the configuration value. Using indirect 
configurations is a better choice when the location of the configuration can change for each deployment of a 
package. 


Create Package Configurations 


Create package configurations by using the Package Configuration Organizer dialog box and the Package 
Configuration Wizard. To access these tools, click Package Configurations on the SSIS menu in SQL Server 
Data Tools (SSDT). 


NOTES: 


You can also access the Package Configuration Organizer by clicking the ellipsis button next to the 
Configuration property. The Configuration property appears in the properties window for the package. 


Configurations are available for the package deployment model. Parameters are used in place of 
configurations for the project deployment model. The project deployment model enables you to deploy 
Integration Services projects to the Integration Services server. For more information about the deployment 
models, see Deployment of Projects and Packages. 


In the Package Configuration Organizer dialog box, you can enable packages to use configurations, add 
and delete configurations, and set the preferred order in which configurations should be loaded. 


When package configurations load in the preferred order, configurations load from the top of the list shown 
in the Package Configuration Organizer dialog box to the bottom of the list. However, at run time, 
package configurations might not load in the preferred order. In particular, parent package configurations 
load after configurations of other types. 


If multiple configurations set the same object property, the value loaded last is used at run time. 


From the Package Configuration Organizer dialog box, you run the Package Configuration Wizard, which 
guides you through the steps to create a configuration. To run the Package Configuration Wizard, add a new 
configuration in the Package Configurations Organizer dialog box or edit an existing one. On the wizard 
pages, you choose the configuration type, select whether you want to access the configuration directly or use 
environment variables, and select the properties to save in the configuration. 


The following example shows the target properties of a variable and a package as they appear on the 
Completing the Wizard page of the Package Configuration Wizard.: 


\Package.Variables[User ::TodaysDate].Properties[RaiseChangedEvent] 
\Package.Proper ties[MaximumErrorCount] 

\Package.Properties[LoggingMode] 

\Package.Properties[LocalelD] 

\Package\My SQL Task.Variables[User::varTableName].Properties[Value] 

In this example, the configuration updates these properties: 

e The RaiseChangedEvent property of user-defined variable, TodaysDate . 

e The MaximumErrorCount, LoggingMode, and LocalelD properties of the package. 


e The Value property of user-defined variable, varTableName , within scope of the task, My SQL Task. 


The "\Package" represents the root, and periods (.) separate the objects that define the path to the property that 
the configuration updates. The names of variables and properties are enclosed in brackets. The term Package is 
always used in configuration, regardless of the package name; however, all other objects in the path use their 


user-defined names. 


After the wizard finishes, the new configuration is added to the configuration list in the Package 
Configuration Organizer dialog box. 


NOTE: The last page in the Package Configuration Wizard, Completing the Wizard, lists the target properties 
in the configuration. If you want to update properties when you run packages by using the dtexec 
command prompt utility, you can generate the strings that represent the property paths by running the 
Package Configuration Wizard and then copy and paste them into the command prompt window for use 


with the set option of dtexec. 


The following table describes the columns in the configuration list in the Package Configuration Organizer 


dialog box. 

COLUMN DESCRIPTION 

Configuration Name The name of the configuration. 

Configuration Type The configuration type. 

Configuration String The location of the configuration. The location can be a path, 
an environment variable, a Registry key, a parent package 
variable name, or a table in a SQL Server database. 

Target Object The name of the object with a property that has a 
configuration. If the configuration is an XML configuration 
file, the column is blank, because the configuration can 
update multiple objects. 

Target Property The name of the property. If the configuration writes to an 


XML configuration file or a SQL Server table, the column is 
blank, because the configuration can update multiple 
objects. 


To create a package configuration 


1. In SQL Server Data Tools (SSDT), open the Integration Services project that contains the package you 


want. 


9. 


10. 


ial 


. In Solution Explorer, double-click the package to open it. 
. In SSIS Designer, click the Control Flow, Data Flow, Event Handler, or Package Explorer tab. 
. On the SSIS menu, click Package Configurations. 


. Inthe Package Configuration Organizer dialog box, select Enable package configurations, and 


then click Add. 


. On the welcome page of the Package Configuration Wizard page, click Next. 


. On the Select Configuration Type page, specify the configuration type, and then set the properties that 


are relevant to the configuration type. For more information, see Package Configuration Wizard UI 
Reference. 


. On the Select Properties to Export page, select the properties of package objects to include in the 


configuration. If the configuration type supports only one property, the title of this wizard page is Select 
Target Property. For more information, see Package Configuration Wizard UI Reference. 


NOTE: Only the XML Configuration File and SQL Server configuration types support including 
multiple properties in a configuration. 

On the Completing the Wizard page, type the name of the configuration, and then click Finish. 

View the configuration in the Package Configuration Organizer dialog box. 


Click Close. 


Package Configurations Organizer 


Use the Package Configurations Organizer dialog box to enable package configurations, view a list of 


configurations for the current package, and specify the preferred order in which the configurations should be 
loaded. 


NOTE: Configurations are available for the package deployment model. Parameters are used in place of 
configurations for the project deployment model. The project deployment model enables you to deploy 
Integration Services projects to the Integration Services server. For more information about the deployment 


models, see Deployment of Projects and Packages. 


If multiple configurations update the same property, values from configurations listed lower in the configuration 


list will replace values from configurations higher in the list. The last value loaded into the property is the value 


that is used when the package runs. Also, if the package uses a combination of direct configuration such as an 


XML configuration file and an indirect configuration such as an environment variable, the indirect configuration 


that points to the location of the direct configuration must be higher in the list. 


NOTE: When package configurations load in the preferred order, configurations load from the top of the list 
shown in the Package Configuration Organizer dialog box to the bottom of the list. However, at run 
time, package configurations might not load in the preferred order. In particular, Parent Package 
Configurations load after configurations of other types. 


Package configurations update the values of properties of package objects at run time. When a package is 


loaded, the values from the configurations replace the values that were set when the package was developed. 


Integration Services supports different configuration types. For example, you can use an XML file that can 


contain multiple configurations, or an environment variable that contains a single configuration. For more 


information, see Package Configurations. 


Options 
Enable package configurations 
Select to use configurations with the package. 


Configuration Name 
View the name of the configuration. 


Configuration Type 
View the type of the location where configurations are stored. 


Configuration String 

View the location where the configuration values are stored. The location can be the path of a file, the name of 
an environment variable, the name of a parent package variable, a Registry key, or the name of a SQL Server 
table. 


Target Object 
View the name of the object that the configuration updates. If the configuration is an XML configuration file or a 
SQL Server table, the column is blank because the configuration can include multiple objects. 


Target Property 
View the name of the property modified by the configuration. This column is blank if the configuration type 


supports multiple configurations. 


Add 
Add a configuration by using the Package Configuration Wizard. 


Edit 
Edit an existing configuration by rerunning the Package Configuration Wizard. 


Remove 


Select a configuration, and then click Remove. 


Arrows 
Select a configuration and use the up and down arrows to move it up or down in the list. Configurations are 
loaded in the sequence in which they appear in the list. 


Package Configuration Wizard UI Reference 


Use the Package Configuration Wizard to create configurations that update the properties of an Integration 
Services package and its objects at run time. This wizard runs when you add a new configuration or modify an 
existing one in the Package Configurations Organizer dialog box. To open the Package Configurations 
Organizer dialog box, select Package Configurations on the SSIS menu in SQL Server Data Tools (SSDT). For 
more information, see Create Package Configurations. 


NOTE: Configurations are available for the package deployment model. Parameters are used in place of 
configurations for the project deployment model. The project deployment model enables you to deploy 
Integration Services projects to the Integration Services server. For more information about the deployment 
models, see Deployment of Projects and Packages. 


The following sections describe pages of the Wizard. 


Welcome to the Package Configuration Wizard Page 

Use the SSIS Configuration Wizard to create configurations that update the properties of a package and its 
objects at run time. 

Options 


Don't show this page again 


Skip the welcome page the next time you open the wizard. 


Next 
Go the next page in the wizard. 


Select Configuration Type Page 


Use the Select Configuration Type page to specify the type of configuration to create. 


If you need additional information to determine which type of configuration to use, see Package Configurations. 


Static Options 
Configuration type 
Select the type of source in which to store the configuration, using the following options: 


VALUE DESCRIPTION 

XML configuration file Store the configuration as an XML file. Selecting this value 
displays the dynamic options in the section, Configuration 
Type. 

Environment variable Store the configuration in one of the environment variables. 


Selecting this value displays the dynamic options in the 
section, Configuration Type. 


Registry entry Store the configuration in the Registry. Selecting this value 
displays the dynamic options in the section, Configuration 
Type. 

Parent package variable Store the configuration as a variable in the package that 


contains the task. Selecting this value displays the dynamic 
options in the section, Configuration Type. 


SQL Server Store the configuration in a table in SQL Server. Selecting this 
value displays the dynamic options in the section, 
Configuration Type. 


Next 
View the next page in the wizard sequence. 


Dynamic Options 
Configuration Type Option = XML Configuration File 


Specify configuration settings directly 
Use to specify settings directly. 


VALUE DESCRIPTION 

Configuration file name Type the path of the configuration file that the wizard 
generates. 

Browse Use the Select Configuration File Location dialog box to 


specify the path of the configuration file that the wizard 
generates. If the file does not exist, it is created by the 
wizard. 


Configuration location is stored in an environment variable 
Use to specify the environment variable in which to store the configuration. 


VALUE 


Environment variable 


Configuration Type Option = Environment Variable 


Environment variable 


DESCRIPTION 


Select an environment variable from the list. 


Select the environment variable that contains the configuration information. 


Configuration Type Option = Registry Entry 


Specify configuration settings directly 


Use to specify settings directly. 


VALUE 


Registry entry 


DESCRIPTION 


Type the Registry key that contains the configuration 
information. The format is <registry key>. 


The Registry key must already exist in HKEY_CURRENT_USER 
and have a value named Value. The value can be a DWORD 
or a string. 


If you want to use a Registry key is not at the root of 
HKEY_CURRENT_USER, use the format <Registry 
key\registry key\...> to identify the key. 


Configuration location is stored in an environment variable 


Use to specify the environment variable to store the configuration in. 


VALUE 


Environment variable 


Configuration Type Option = Parent Package Variable 
Specify configuration settings directly 
Use to specify settings directly. 


VALUE 


Parent variable 


DESCRIPTION 


Select an environment variable from the list. 


DESCRIPTION 


Specify the variable in the parent package that contains the 
configuration information. 


Configuration location is stored in an environment variable 


Use to specify the environment variable that stores the configuration. 


VALUE 


Environment variable 


Configuration Type Options = SQL Server 
Specify configuration settings directly 
Use to specify settings directly. 


VALUE 


Connection 


DESCRIPTION 


Select an environment variable from the list. 


DESCRIPTION 


Select a connection from the list, or click New to create a 
new connection. 


VALUE DESCRIPTION 


Configuration table Select an existing table, or click New to write a SQL 
statement that creates a new table. 


Configuration filter Select an existing configuration name or type a new name. 


Many SQL Server configurations can be stored in the same 
table, and each configuration can include multiple 
configuration items. 


This user-defined value is stored in the table to identify 
configuration items that belong to a particular configuration 


Configuration location is stored in an environment variable 
Use to specify the environment variable where the configuration is stored. 


VALUE DESCRIPTION 


Environment variable Select an environment variable from the list. 


Select Objects to Export Page 
Use the Select Target Property or Select Properties to Export page to specify the object properties that 
the configuration contains. The ability to select multiple properties is available only if you select the XML 


configuration type. 


Options 
Objects 
Expand the package hierarchy and select the properties to export. 


Property attributes 
View the attributes of a property. 


Next 


Go to the next page in the wizard. 


Completing the Wizard Page 


Use the Completing the Wizard page to provide a name for the configuration and view settings used by the 
wizard to create the configuration. After the wizard completes, the Package Configurations Organizer is 
displayed, which lists all configurations for the package. 


Options 
Configuration name 
Type the name of the configuration. 


Preview 

View the settings used by the wizard to create the configuration. 

Finish 

Create the configuration and exit the Package Configuration Wizard. 


Use the Values of Variables and Parameters in a Child Package 


This procedure describes how to create a package configuration that uses the parent variable configuration type. 
This configuration type enables a child package that is run from a parent package to access a variable in the 
parent. 





NOTE 


You can also pass values to a child package by configuring the Execute Package Task to map parent package variables or 


parameters, or project parameters, to child package parameters. For more information, see Execute Package Task. 











It is not necessary to create the variable in the parent package before you create the package configuration in 
the child package. You can add the variable to the parent package at any time, but you must use the exact name 
of the parent variable in the package configuration. However, before you can create a parent variable 
configuration, there must be an existing variable in the child package that the configuration can update. For 
more information about adding and configuring variables, see Add, Delete, Change Scope of User-Defined 
Variable in a Package. 


The scope of the variable in the parent package that is used in a parent variable configuration can be set to the 
Execute Package task, to the container that has the task, or to the package. If multiple variables with the same 
name are defined in a package, the variable that is closest in scope to the Execute Package task is used. The 
closest scope to the Execute Package task is the task itself. 


To add a variable to a parent package 


1. In SQL Server Data Tools (SSDT), open the Integration Services project that contains the package to which 
you want to add a variable to pass to a child package. 


2. In Solution Explorer, double-click the package to open it. 

3. In SSIS Designer, to define the scope of the variable, do one of the following: 
@ To set the scope to the package, click anywhere on the design surface of the Control Flow tab. 
e To set the scope to a parent container of the Execute Package task, click the container. 
e To set the scope to the Execute Package task, click the task. 


4. Add and configure a variable. 





NOTE 


Select a data type that is compatible with the data that the variable will store. 





5. To save the updated package, click Save Selected Items on the File menu. 


To add a variable to a child package 


1. In SQL Server Data Tools (SSDT), open the Integration Services project that contains the package to which 
you want to add a parent variable configuration. 


2. In Solution Explorer, double-click the package to open it. 


3. In SSIS Designer, to set the scope to the package, click anywhere on the design surface of the Control 
Flow tab. 


4. Add and configure a variable. 





NOTE 


Select a data type that is compatible with the data that the variable will store. 





5. To save the updated package, click Save Selected Items on the File menu. 


Create a Deployment Utility 


The first step in deploying packages is to create a deployment utility for an Integration Services project. The 
deployment utility is a folder that contains the files you need to deploy the packages in an Integration Services 
project on a different server. The deployment utility is created on the computer on which the Integration 


Services project is stored. 


You create a package deployment utility for an Integration Services project by first configuring the build process 
to create a deployment utility, and then building the project. When you build the project, all packages and 
package configurations in the project are automatically included. To deploy additional files such as a Readme file 
with the project, place the files in the Miscellaneous folder of the Integration Services project. When the 


project is built, these files are also automatically included. 


You can configure each project deployment differently. Before you build the project and create the package 
deployment utility, you can set the properties on the deployment utility to customize the way the packages in 
the project will be deployed. For example, you can specify whether package configurations can be updated when 
the project is deployed. To access the properties of an Integration Services project, right-click the project and 
click Properties. 


The following table lists the deployment utility properties. 
PROPERTY DESCRIPTION 


AllowConfigurationChange A value that specifies whether configurations can be updated 
during deployment. 


CreateDeploymentUtility A value that specifies whether a package deployment utility 
is created when the project is built. This property must be 
True to create a deployment utility. 


DeploymentOutputPath The location, relative to the Integration Services project, of 
the deployment utility. 


When you build an Integration Services project, a manifest file, <project name>.SSISDeploymentManifest.xml., is 
created and added, together with copies of the project packages and package dependencies, to the 
bin\Deployment folder in the project, or to the location specified in the DeploymentOutputPath property. The 
manifest file lists the packages, the package configurations, and any miscellaneous files in the project. 


The content of the deployment folder is refreshed every time that you build the project. This means that any file 
saved to this folder that is not copied to the folder again by the build process will be deleted. For example, 
package configuration files saved to the deployment folders will be deleted. 


To create a package deployment utility 


1. In SQL Server Data Tools (SSDT), open the solution that contains the Integration Services project for 
which you want to create a package deployment utility. 


2. Right-click the project and click Properties. 
3. In the <project name> Property Pages dialog box, click Deployment Utility. 


4. To update package configurations when packages are deployed, set AllowConfigurationChanges to 
True. 


5. Set CreateDeploymentUtility to True. 


6. Optionally, update the location of the deployment utility by modifying the DeploymentOutputPath 
property. 


7. Click OK. 
8. In Solution Explorer, right-click the project, and then click Build. 


9. View the build progress and build errors in the Output window. 


Deploy Packages by Using the Deployment Utility 


When you have built a deployment utility to install packages from an Integration Services project on a different 
computer than the one on which the deployment utility was built, you must first copy the deployment folder to 
the destination computer. 


The path of the deployment folder is specified in the DeploymentOutputPath property of the Integration 
Services project for which you created the deployment utility. The default path is bin\Deployment, relative to the 
Integration Services project. For more information, see Create a Deployment Utility. 


You use the Package Installation Wizard to install the packages. To launch the wizard, double-click the 
deployment utility file after you have copied the deployment folder to the server. This file is named <project 
name>.SSISDeploymentManifest, and can be found in the deployment folder on the destination computer. 


NOTE 


Depending on the version of the package that you are deploying, you might encounter an error if you have different 
versions of SQL Server installed side-by-side. This error can occur because the .SSISDeploymentManifest file name 
extension is the same for all versions of Integration Services. Double-clicking the file calls the installer (dtsinstall.exe) for 
the most recently installed version of Integration Services, which might not be the same version as the deployment utility 
file. To work around this problem, run the correct version of dtsinstall.exe from the command line, and provide the path of 


the deployment utility file. 





The Package Installation Wizard guides you through the steps to install packages to the file system or to SQL 
Server. You can configure the installation in the following ways: 


e Choosing the location type and location to install the packages. 
e Choosing location to install package dependencies. 
e Validating the packages after they are installed on the target server. 


The file-based dependencies for packages are always installed to the file system. If you install a package to the 
file system, the dependencies are installed in the same folder as the one that you specify for the package. If you 
install a package to SQL Server, you can specify the folder in which to store the file-based dependencies. 


If the package includes configurations that you want to modify for use on the destination computer, you can 
update the values of the properties by using the wizard. 


In addition to installing packages by using the Package Installation Wizard, you can copy and move packages by 
using the dtutil command prompt utility. For more information, see dtutil Utility. 


To deploy packages to an instance of SQL Server 


1. Open the deployment folder on the target computer. 


2. Double-click the manifest file, <project name>.SSISDeploymentManifest, to start the Package Installation 
Wizard. 


3. On the Deploy SSIS Packages page, select the SQL Server deployment option. 


4. Optionally, select Validate packages after installation to validate packages after they are installed on 
the target server. 





5. On the Specify Target SQL Server page, specify the instance of SQL Server to install the packages to 
and select an authentication mode. If you select SQL Server Authentication, you must provide a user 


name and a password. 


6. On the Select Installation Folder page, specify the folder in the file system for the package 
dependencies that will be installed. 


7. If the package includes configurations, you can edit configurations by updating values in the Value list on 
the Configure Packages page. 


8. If you elected to validate packages after installation, view the validation results of the deployed packages. 


Redeployment of Packages 


After a project is deployed, you may need to update or extend package functionality and then redeploy the 
Integration Services project that contains the updated packages. As part of the process of redeploying packages, 
you should review the configuration properties that are included in the deployment utility. For example, you 
may not want to allow configuration changes after the package is redeployed. 


Process for Redeployment 


After you finish updating the packages, you rebuild the project, copy the deployment folder to the target 
computer, and then rerun the Package Installation Wizard. 


If you update only a few packages in the project, you may not want to redeploy the entire project. To deploy only 
a few packages, you can create a new Integration Services project, add the updated packages to the new project, 
and then build and deploy the project. Package configurations are automatically copied with the package when 
you add the package to a different project. 


Package Installation Wizard UI Reference 


Use the Package Installation Wizard to deploy a Integration Services project, including the packages and 


miscellaneous files it contains and any package dependencies. 


Before you deploy packages, you can create configurations and then deploy them with the packages. Integration 
Services uses configurations to dynamically update properties of packages and package objects at run time. For 
example, the connection string of an OLE DB connection can be set dynamically at run time by providing a 
configuration that maps a value to the property that contains the connection string. 


You cannot run the Package Installation Wizard until you build an Integration Services project and create a 
deployment utility. For more information, see Deploy Packages by Using the Deployment Utility. 


The following sections describe pages of the wizard. 


Welcome to the Package Installation Wizard Page 
Use the Package Installation Wizard to deploy an Integration Services project for which you built a package 


deployment utility. 


Do not show this starting page again 
Select to skip the starting page when you run the wizard again. 


Next 

Go to the next page in the wizard. 

Finish 

Skip to the Finish the Package Installation Wizard page. Use this option if you have backtracked through the 


wizard pages to revise your choices and have specified all of the required options. 


Configure Packages Page 


Use the Configure Packages page to edit package configurations. 
Options 


Configuration file 
Edit the contents of a configuration file by selecting the file from the list. 


Related Topics: Create Package Configurations 


Path 
View the path of the property to be configured. 


Type 
View the data type of the property. 


Value 
Specify the value of the configuration. 


Next 

Go to the next page in the wizard. 

Finish 

Skip to the Finish the Package Installation Wizard page. Use this option if you have backtracked through the 
wizard pages to revise your choices and have specified all of the required options. 


Confirm Installation Page 


Use the Confirm Installation page to start the installation of packages, to view the status, and to view the 
information that the wizard will use to install files from the specified project. 


Next 
Install the packages and their dependencies and go to the next wizard page when installation is completed. 


Status 

Shows the progress of the package installation. 

Finish 

Go to the Finish the Package Installation Wizard page. Use this option if you have backtracked through the 
wizard pages to revise your choices and have specified all the required options. 


Deploy SSIS Packages Page 


Use the Deploy SSIS Packages page to specify where to install Integration Services packages and their 
dependencies. 


Options 
File system deployment 
Deploy packages and dependencies in a specified folder in the file system. 


SQL Server deployment 
Deploy packages and dependencies in an instance of SQL Server. Use this option if SQL Server shares packages 
between servers. Any package dependencies are installed in the specified folder in the file system. 


Validate packages after installation 
Indicate whether to validate packages after installation. 


Next 

Go to the next page in the wizard. 

Finish 

Skip to the Finish the Package Installation Wizard page. Use this option if you have backtracked through the 
wizard pages to revise your choices and have specified all of the required options. 


Packages Validation Page 


Use the Packages Validation page to view the progress and results of the package validation. 


Next 
Go to the next page in the wizard. 


Select Installation Folder Page 


Use the Select Installation Folder page to specify the file system folder in which to install the packages and 
their dependencies. 


Options 
Folder 
Specify the path and folder in which to copy the package and its dependencies. 


Browse 


Browse to the target folder by using the Browse For Folder dialog box. 


Next 

Go to the next page in the wizard. 

Finish 

Skip to the Finish the Package Installation Wizard page. Use this option if you have backtracked through the 
wizard pages to revise your choices and if have specified all of the required options. 


Specify Target SQL Server Page 
Use the Specify Target SQL Server page to specify options for deploying the package to an instance of SQL 


Server. 


Options 
Server name 


Specify the name of the server to deploy the packages to. 


Use Windows Authentication 
Specify whether to use Windows Authentication to log on to the server. Windows Authentication is 
recommended for better security. 


Use SQL Server Authentication 
Specify whether the package should use SQL Server Authentication to log on to the server. If you use SQL 
Server Authentication, you must provide a user name and password. 


User name 


Specify a user name. 


Password 
Specify a password. 


Package path 
Specify the name of the logical folder, or enter "/" for the default folder. 


To select the folder in the SSIS Package dialog box, click browse (...). However, the dialog box does not provide a 
means to select the default folder. If you want to use the default folder, you have to enter "/" in the text box. 





NOTE 


If you do not enter a valid package path, the following error message appears: "One or more arguments are invalid." 





Rely on server storage for encryption 


Select to use security features of the Database Engine to help secure the packages. 


Next 
Go to the next page in the wizard. 


Finish 
Skip to the Finish the Package Installation Wizard page. Use this option if you have backtracked through the 


wizard pages to revise your choices and have specified all of the required options. 


Finish the Package Installation Page 

Use the Finish the Package Installation Wizard page to view a summary of the package installation results. 
This page provides details such as the name of the deployed Integration Services project, the packages that were 
installed, the configuration files, and the installation location. 

Finish 

Exit the wizard by clicking Finish. 


Run Integration Services (SSIS) Packages 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


To run an Integration Services package, you can use one of several tools depending on where those packages 


are stored. The tools are listed in the table below. 





NOTE 


packages on the following platforms: 


and Run an SSIS package in Azure. 





e Linux. For more info, see Extract, transform, and load data on Linux with SSIS. 


This article describes how to run SSIS packages in general, and how to run packages on premises. You can also run SSIS 


© The Microsoft Azure cloud. For more info, see Lift and shift SQL Server Integration Services workloads to the cloud 





To store a package on the Integration Services server, you use the project deployment model to deploy the 


project to the server. For information, see Deploy Integration Services (SSIS) Projects and Packages. 


To store a package in the SSIS Package store, the msdb database, or in the file system, you use the package 


deployment model. For more information, see Legacy Package Deployment (SSIS). 


PACKAGES THAT ARE 
STORED ON THE 
INTEGRATION SERVICES 


TOOL SERVER 
SQL Server Data Tools No 
SQL Server Yes 


Management Studio, 
when you are connected 
to an instance of the 
Database Engine that 
hosts the Integration 
Services server 


For more information, see 
Execute Package Dialog Box 


PACKAGES THAT ARE 
STORED IN THE SSIS 
PACKAGE STORE OR IN THE 
MSDB DATABASE 


No 


However, you can add an 
existing package to a 
project from the SSIS 
Package Store, which 
includes the msdb 
database. Adding an 
existing package to the 
project in this manner 
makes a local copy of the 
package in the file system. 


No 


However, you can import a 
package to the server from 
these locations. 


PACKAGES THAT ARE 
STORED IN THE FILE 
SYSTEM, OUTSIDE OF THE 
LOCATION THAT IS PART 
OF THE SSIS PACKAGE 
STORE 


Yes 


No 


However, you can import a 
package to the server from 
the file system. 





TOOL 


SQL Server 
Management Studio, 
when you are connected 
to an instance of the 
Database Engine that 
hosts the Integration 
Services server that is 
enabled as Scale Out 
Master 


For more information, see 
Run packages in Scale Out 


SQL Server 
Management Studio, 
when it is connected to 
the Integration Services 
service that manages 
the SSIS Package Store 


dtexec 


For more information, see 
dtexec Utility. 


dtexecui 


For more information, see 
Execute Package Utility 
(DtExecUI) UI Reference 


SQL Server Agent 


You use a SQL Server Agent 
job To schedule a package. 


For more information, see 
SQL Server Agent Jobs for 
Packages. 


Built-in stored 
procedure 


For more information, see 
catalog.start_execution 
(SSISDB Database) 


Managed API, by using 
types and members in 
the 
Microsoft.SqlServerManage 
ment.IntegrationServices 
namespace 


PACKAGES THAT ARE 
STORED ON THE 
INTEGRATION SERVICES 
SERVER 


Yes 


No 


Yes 


No 


Yes 


Yes 


Yes 


PACKAGES THAT ARE 
STORED IN THE SSIS 
PACKAGE STORE OR IN THE 
MSDB DATABASE 


No 


Yes 


Yes 


Yes 


Yes 


No 


No 


PACKAGES THAT ARE 
STORED IN THE FILE 
SYSTEM, OUTSIDE OF THE 
LOCATION THAT IS PART 
OF THE SSIS PACKAGE 
STORE 


No 


No 


However, you can import a 
package to the SSIS 
Package Store from the file 
system. 


Yes 


Yes 


Yes 


No 


No 


PACKAGES THAT ARE 
STORED IN THE FILE 


PACKAGES THAT ARE PACKAGES THAT ARE SYSTEM, OUTSIDE OF THE 
STORED ON THE STORED IN THE SSIS LOCATION THAT IS PART 
INTEGRATION SERVICES PACKAGE STORE OR IN THE OF THE SSIS PACKAGE 

TOOL SERVER MSDB DATABASE STORE 

Managed API, by using Not currently Yes Yes 

types and members in 

the 


Microsoft.SqlServerDts.Runt 
ime namespace 


Execution and Logging 


Integration Services packages can be enabled for logging and you can capture run-time information in log files. 
For more information, see Integration Services (SSIS) Logging. 


You can monitor Integration Services packages that are deployed to and run on the Integration Services server 
by using operation reports. The reports are available in SQL Server Management Studio. For more information, 
see Reports for the Integration Services Server. 


Run a Package in SQL Server Data Tools 


You typically run packages in SQL Server Data Tools (SSDT) during the development, debugging, and testing of 
packages. When you run a package from SSIS Designer, the package always runs immediately. 


While a package is running, SSIS Designer displays the progress of package execution on the Progress tab. You 
can view the start and finish time of the package and its tasks and containers, in addition to information about 
any tasks or containers in the package that failed. After the package finishes running, the run-time information 
remains available on the Execution Results tab. For more information, see the section, "Progress Reporting,” in 
the topic, Debugging Control Flow. 


Design-time deployment. When you run a package in SQL Server Data Tools, the package is built and then 
deployed to a folder. Before you run the package, you can specify the folder to which the package is deployed. If 
you do not specify a folder, the bin folder is used by default. This type of deployment is called design-time 
deployment. 


To run a package in SQL Server Data Tools 


1. In Solution Explorer, if your solution contains multiple projects, right-click the Integration Services project 
that contains the package, and then click Set as StartUp Object to set the startup project. 


2. In Solution Explorer, if your project contains multiple packages, right-click a package, and then click Set 
as StartUp Object to set the startup package. 


3. To run a package, use one of the following procedures: 


e Open the package that you want to run and then click Start Debugging on the menu bar, or 
press F5. After the package finishes running, press Shift+F5 to return to design mode. 


e In Solution Explorer, right-click the package, and then click Execute Package. 


To specify a different folder for design-time deployment 


1. In Solution Explorer, right-click the Integration Services project folder that contains the package you want 
to run, and then click Properties. 


2. Inthe <project name> Property Pages dialog box, click Build. 


3. Update the value in the OutputPath property to specify the folder you want to use for design-time 


deployment, and click OK. 


Run a Package on the SSIS Server Using SQL Server Management 
Studio 


After you deploy your project to the Integration Services server, you can run the package on the server. 


You can use operations reports to view information about packages that have run, or are currently running, on 


the server. For more information, see Reports for the Integration Services Server. 


To run a package on the server using SQL Server Management Studio 


1. Open SQL Server Management Studio and connect to the instance of SQL Server that contains the 
Integration Services catalog. 


2. In Object Explorer, expand the Integration Services Catalogs node, expand the SSISDB node, and 
navigate to the package contained in the project you deployed. 


3. Right-click the package name and select Execute. 


4. Configure the package execution by using the settings on the Parameters, Connection Managers, and 
Advanced tabs in the Execute Package dialog box. 


5. Click OK to run the package. 
-Or- 


Use stored procedures to run the package. Click Script to generate the Transact-SQL statement that 
creates an instance of the execution and starts an instance of the execution. The statement includes a call 
to the catalog.create_execution, catalog.set_execution_parameter_value, and catalog.start_execution 
stored procedures. For more information about these stored procedures, see catalog.create_execution 
(SSISDB Database), catalog.set_execution_parameter_value (SSISDB Database), and 
catalog.start_execution (SSISDB Database). 


Execute Package Dialog Box 
Use the Execute Package dialog box to run a package that is stored on the Integration Services server. 


An Integration Services package may contain parameters that values stored in environment variables. Before 
executing such a package, you must specify which environment will be used to provide the environment 
variable values. A project may contain multiple environments, but only one environment can be used for 
binding environment variable values at the time of execution. If no environment variables are used in the 


package, an environment is not required. 

What do you want to do? 

@ Open the Execute Package dialog box 

e Set the Options on the General page 

e Set the Options on the Parameters tab 

e Set the Options on the Connection Managers tab 

e@ Set the Options on the Advanced tab 

e Scripting the Options in the Execute Package Dialog Box 


Open the Execute Package dialog box 


1. In SQL Server Management Studio, connect to the Integration Services server. 


You're connecting to the instance of the SQL Server Database Engine that hosts the SSISDB database. 
2. In Object Explorer, expand the tree to display the Integration Services Catalogs node. 
3. Expand the SSISDB node. 
4. Expand the folder that contains the package you want to run. 
5. Right-click the package, and then click Execute. 


Set the Options on the General page 


Select Environment to specify the environment that is applied with the package is run. 


Set the Options on the Parameters tab 


Use the Parameters tab to modify the parameter values that are used when the package runs. 


Set the Options on the Connection Managers tab 


Use the Connection Managers tab to set the properties of the package connection manager‘(s). 


Set the Options on the Advanced tab 


Use the Advanced tab to manage properties and other package settings. 


Add, Edit, Remove 
Click to add, edit, or remove a property. 


Logging level 
Select the logging level for the package execution. For more information, see 
catalog.set_execution_parameter_value (SSISDB Database). 


Dump on errors 
Specify whether a dump file is created when errors occur during the package execution. For more information, 
see Generating Dump Files for Package Execution. 


32-bit runtime 
Specify that the package will execute on a 32-bit system. 


Scripting the Options in the Execute Package Dialog Box 


While you are in the Execute Package dialog box, you can also use the Script button on the toolbar to write 
Transact-SQL code for you. The generated script calls the stored procedures catalog.start_execution (SSISDB 
Database) with the same options that you have selected in the Execute Package dialog box. The script appears 
in a new script window in Management Studio. 


See Also 


dtexec Utility 
Start the SQL Server Import and Export Wizard 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Use the Execute Package Utility to run Integration Services packages. The utility runs packages that are stored 
in one of three locations: Microsoft SQL Server database, the SSIS Package Store, and the file system. This user 
interface, which can be opened from SQL Server Management Studio or by typing dtexecui at a command 
prompt, is an alternative to running packages by using the DTExec command prompt tool. 


Packages execute in the same process as the dtexecui.exe utility. Because this utility is a 32-bit tool, packages 
run by using dtexecui.exe in a 64-bit environment run in Windows on Win32 (WOW). When developing and 
testing commands by using the dtexecui.exe utility on a 64-bit computer, you should test the commands in 64- 
bit mode by using the 64-bit version of dtexec.exe before deploying or scheduling the commands on a 
production server. 


The Execute Package Utility is a graphical user interface for the DTExec command prompt tool. The user 
interface makes it easy to configure options and it automatically assembles the command line that is passed to 
the DTExec command prompt tool when you run the package from the specified options. 


The Execute Package Utility can also be used to assemble command lines that you use when running DTExec 
directly. 


To open Execute Package Utility in SQL Server Management Studio 


1. In SQL Server Management Studio, on the View menu, click Object Explorer. 
2. In Object Explorer, click Connect, and then click Integration Services. 


3. In the Connect to Server dialog box, enter the server name in the Server name list, and then click 
Connect. 


4. Expand the Stored Packages folder and subfolders, right-click the package you want to run, and then 
click Run Package. 
To open the Execute Package Utility at the Command Prompt 


e@ Inacommand prompt window, run dtexecui. 


The following sections describe pages of the Execute Package Utility dialog box. 


General Page 
Use the General page of the Execute Package Utility dialog box to specify a package name and location. 


The Execute Package utility (dtexecui.exe) always runs a package on the local computer, even if the package is 
saved on a remote server. If the remote package uses configuration files that also are saved on the remote 
server, then the Execute Package utility may not locate the configurations and the package fails. To avoid this 
problem, the configurations must be referenced by using a Universal Naming Convention (UNC) share name 
like \\myserver\myfile. 


Static Options 


Package source 
Specify the location of the package to run, using the following options: 


VALUE 


SQL Server 


File system 


SSIS Package Store 


Each of these selections has the following set of options. 


Execute 
Click to run the package. 


Close 
Click to close the Execute Package Utility dialog box. 


Dynamic Options 
Package Source = SQL Server 


Server 


DESCRIPTION 


Select this option when the package resides in Microsoft SQL 
Server. Specify an instance of SQL Server and provide a user 
name and password for SQL Server Authentication. Each 
user name and password adds the /USER username and 
/PASSWORD password options to the command prompt. 


Select this option when the package resides in the file 
system. 


Select this option when the package resides in the SSIS 
Package Store. 


Type the name of the server where the package resides, or select a server from the list. 


Log on to the server 


Specify whether the package should use Windows Authentication or SQL Server Authentication to connect to 


SQL Server. Windows Authentication is recommended for better security. With Windows Authentication you do 


not have to specify a user name and password. 


Use Windows Authentication 


Select this option to use Windows Authentication and log on using a Microsoft Windows user account. 


Use SQL Server Authentication 


Select this option to use SQL Server Authentication. When a user connects with a specified login name and 


password from a non-trusted connection, SQL Server performs the authentication by checking to see if a SQL 


Server login account has been set up and if the specified password matches the one previously recorded. If SQL 


Server cannot find the login account, authentication fails, and the user receives an error message. 





IMPORTANT 


When possible, use Windows Authentication. 





Package 


Type the name of the package, or click the ellipsis button (...) to locate a package using the Select an SSIS 


Package dialog box. 


Package Source = File System 


Package 


Type the name of the package, or click the ellipsis button (...) to locate a package using the Open dialog box. By 


default, the dialog box lists only files that have the .dtsx extension. 


Package Source = SSIS Package Store 


Server 


Type the name of the computer where the package resides, or select a computer from the list. 


Log on to the server 

Specify whether the package should use Microsoft Windows Authentication to connect to the package source. 
Windows Authentication is recommended for better security. With Windows Authentication you do not have to 
specify a user name and password. 


Use Windows Authentication 
Select this option to use Windows Authentication and log on using a Microsoft Windows user account. 


Use SQL Server Authentication 
This option is not available when you run a package stored in the SSIS Package Store. 


Package 
Type the name of the package, or click the ellipsis button (...) to locate a package using the Select an SSIS 
Package dialog box. 


Configurations Page 


Use the Configurations page of the Execute Package Utility dialog box to select the configuration files to 
load at run time, and to specify the order in which they load. 


Options 

Configuration files 

Lists the configurations that the package uses. Each configuration file adds a/CONFIGFILE filename option to 
the command prompt. 


Arrow keys 
Select a configuration file in the list, and use the arrow keys at right to change the loading order. Configurations 
load in order starting from the top of the list. 





NOTE 


If multiple configurations modify the same property, the configuration that loads last is used. 





Add 
Click to add configurations using the Open dialog box. By default, the dialog box lists only files that have the 


.dtsconfig extension. 


Remove 
Select a configuration file in the list and then click Remove. 


Execute 
Click to run the package. 


Close 
Click to close the Execute Package Utility dialog box. 


Command Files Page 


Use the Command Files page of the Execute Package Utility dialog box to select the command files to load 


at run time. 


Options 
Command files 
Lists the command files that the package uses. A package can use multiple files to set command-line options. 


Arrow keys 


Select a command file in the list, and use the arrow keys at right to change the loading order. Command files 


load in order, starting from the top of the list. 


Add 
Click to add a command file, using the Open dialog box. 


Remove 
Select a command file in the text box, and then remove it using the Remove button. 


Execute 
Click to run the package. 


Close 
Click to close the Execute Package Utility dialog box. 


Connection Managers Page 


Use the Connection Managers page of the Execute Package Utility dialog box to edit the connection strings 


of the connection managers that the package uses. 


Options 
Connection Manager 


Select its check box to make the Connection String column editable. 


Description 
View a description for each connection manager. Descriptions cannot be edited. 


Connection String 
Edit the connection string for a connection manager. This field is editable only when the Connection Manager 
check box is selected. 


Execute 
Click to run the package. 


Close 
Click to close the Execute Package Utility dialog box. 


Execution Options Page 


Use the Execution Options page of the Execute Package Utility dialog box to specify run-time options for 
the package. 


Options 
Fail package on validation warnings 
Indicate whether the package fails if a validation warning occurs. 


Validate package without executing 
Indicate whether the package is validated only. 


Maximum concurrent executables 
Indicate whether you want to specify the maximum number of executables that can run in the package at the 
same time. After you select this check box, use the spin box to specify the maximum number of executables. 


Enable package checkpoints 
Indicate whether to enable package checkpoints. 


Checkpoint file 
List the checkpoint file the package uses, if you enable package checkpoints. 


Browse 
Click the browse button (...) to locate the checkpoint file using the Open dialog box, if you enable package 
checkpoints. If a checkpoint file is already specified, it is replaced by the selected file. 


Override restart options 
Indicate whether to override restart options, if you enable package checkpoints. 


Restart option 
Select how to use checkpoints, if you override restart options. 


Execute 
Click to run the package. 


Close 
Click to close the Execute Package Utility dialog box. 


Reporting Page 


Use the Reporting page of the Execute Package Utility dialog box to specify the events and information 
about the package to log to the console when the package runs. 


Options 
Console events 
Indicate the events and types of messages to report. 


None 
Select for no reporting. 


Errors 
Select to report error messages. 


Warnings 
Select to report warning messages. 


Custom Events 
Select to report custom event messages. 


Pipeline Events 
Select to report data flow events messages. 


Information 
Select to report information messages. 


Verbose 
Select to use verbose reporting. 


Console logging 
Specify the information that you want written to the log when the selected event occurs. 


Name 
Select to report the name of the person who created the package. 


Computer 


Select to report the name of the computer the package is running on. 


Operator 
Select to report the name of the person who started the package. 


Source name 


Select to report the package name. 


Source GUID 
Select to report the package GUID. 


Execution GUID 
Select to report the GUID of the package execution instance. 


Message 
Select to report messages. 


Start time and end time 
Select to report when the package began and finished. 


Execute 
Click to run the package. 


Close 
Click to close the Execute Package Utility dialog box. 


Logging Page 


Use the Logging page of the Execute Package Utility dialog box to make log providers available to the 
package at run time. Provide the package log provider type and the connection string for connecting to the log. 
Each log provider entry adds a /LOGGER c/assid option to the command prompt. 


Options 
Log Provider 
Select a log provider from the list. 


Configuration String 
Select the name of the connection manager from the package that points to the log location, or type the 
connection string for connecting to the log provider. 


Remove 
Select a log provider and click to remove it. 


Execute 
Click to run the package. 


Close 
Click to close the Execute Package Utility dialog box. 


Set Values Page 


Use the Set Values page of the Execute Package Utility dialog box to set the property values of packages, 
executables, connections, variables, and log providers by typing the paths of properties and the property values. 
Each path entry adds a /SET propertypath,value option to the command prompt. 


Options 

Property Path 

Type the path of the property. The path syntax uses a backslash (\) to indicate that the following item is a 
container, the period (.) to indicate the following item is a property, and brackets to indicate a collection member. 
The member can be identified by its index or its name. For example, the property path of a package variable is 
\Package.Variables[MyVariable].Value. 


Value 
Type the value of the property. 


Remove 
Select a property path and click to remove it. 


Execute 
Click to run the package. 


Close 
Click to close the Execute Package Utility dialog box. 


Verification Page 


Use the Verification page of the Execute Package dialog box to set criteria for verifying the package. 


Options 
Execute only signed packages 
Select to execute only packages that have been signed. 


Verify package build 
Select to verify the package build. 


Build 
Specify the sequential Build number associated with the build. 


Verify package ID 
Select to verify the package ID. 


Package ID 
Specify the package identification number. 


Verify version ID 
Select to verify the version ID. 


Version ID 
Specify the version identification number. 


Execute 
Click to run the package. 


Close 
Click to close the Execute Package Utility dialog box. 


Command Line Page 


Use the Command Line node of the Execute Package Utility dialog box to edit the command line that has 
been generated by the options created by the various dialogs. 


Options 

Restore the original options 

Click to restore the command line to its original state. Use this option if you have made modifications using the 
Edit the command line manually option and want to restore the original command-line options. 


Edit the command line manually 
Click to edit the command line in the Command line text box. 


Command line 
Displays the current command line. Editable if you selected the option to edit the command line manually. 


Execute 
Click to run the package. 


Close 
Click to close the Execute Package Utility dialog box. 


See Also 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


The dtexec command prompt utility is used to configure and execute SQL Server Integration Services packages. 
The dtexec utility provides access to all the package configuration and execution features, such as parameters, 
connections, properties, variables, logging, and progress indicators. The dtexec utility lets you load packages 
from these sources: the Integration Services server, an .ispac project file, a Microsoft SQL Server database, the 
SSIS Package Store, and the file system. 


NOTE: When you use the current version of the dtexec utility to run a package created by an earlier version 
of Integration Services, the utility temporarily upgrades the package to the current package format. 
However, you cannot use the dtexec utility to save the upgraded package. For more information about how 
to permanently upgrade a package to the current version, see Upgrade Integration Services Packages. 


This topic includes the following sections: 

e Integration Services Server and Project File 

e Installation Considerations on 64-bit Computers 
e@ Considerations on Computers with Side-by-Side Installations 
e Phases of Execution 

e Exit Codes Returned 

e Syntax Rules 

e Using dtexec from the xp_cmdshell 

e Using dtexec from Bash 

e Syntax 

e Parameters 

e@ Remarks 


e Examples 


Integration Services Server and Project File 


When you use dtexec to run packages on the Integration Services server, dtexec calls the 
catalog.create_execution (SSISDB Database), catalog.set_execution_parameter_value (SSISDB Database) and 
catalog.start_execution (SSISDB Database) stored procedures to create an execution, set parameter values and 
start the execution. All execution logs can be seen from the server in the related views or by using standard 
reports available in SQL Server Management Studio. For more information about the reports, see Reports for 
the Integration Services Server. 


The following is an example of executing a package on the Integration Services server. 


DTExec /ISSERVER "\SSISDB\folderB\Integration Services Project17\Package.dtsx" /SERVER "." /Envreference 2 
/Par “$Project: :ProjectParameter(Int32)";1 /Par "Parameter(Int32)";21 /Par 
"CM.sqlcldb2.SSIS_repro.InitialCatalog";ssisdb /Par "$ServerOption: : SYNCHRONIZED(Boolean)"; True 


When you use dtexec to run a package from the .ispac project file, the related options are: /Proj[ect] and 
/Pack[age] that are used to specify the project path and package stream name. When you convert a project to 
the project deployment model by running the Integration Services Project Conversion Wizard from SQL 
Server Management Studio, the wizard generates an .ispac projec file. For more information, see Deploy 
Integration Services (SSIS) Projects and Packages. 


You can use dtexec with third-party scheduling tools to schedule packages that are deployed to the Integration 
Services server. 


Installation Considerations on 64-bit Computers 


On a 64-bit computer, Integration Services installs a 64-bit version of the dtexec utility (dtexec.exe). If you have 
to run certain packages in 32-bit mode, you will have to install the 32-bit version of the dtexec utility. To install 
the 32-bit version of the dtexec utility, you must select either Client Tools or SQL Server Data Tools (SSDT) 
during setup. 


By default, a 64-bit computer that has both the 64-bit and 32-bit versions of an Integration Services command 
prompt utility installed will run the 32-bit version at the command prompt. The 32-bit version runs because the 
directory path for the 32-bit version appears in the PATH environment variable before the directory path for the 
64-bit version. (Typically, the 32-bit directory path is <drive>\Program Files(x86)\Microsoft SQL 
Server\110\DTS\Binn, while the 64-bit directory path is <drive>:\Program Files\Microsoft SQL 
Server\110\DTS\Binn.) 


NOTE: If you use SQL Server Agent to run the utility, SQL Server Agent automatically uses the 64-bit 
version of the utility. SQL Server Agent uses the registry, not the PATH environment variable, to locate the 
correct executable for the utility. 


To ensure that you run the 64-bit version of the utility at the command prompt, you can take one of the 
following actions: 


e@ Open a Command Prompt window, change to the directory that contains the 64-bit version of the utility 
(<drive>\Program Files\Microsoft SQL Server\110\DTS\Binn), and then run the utility from that location. 


e At the command prompt, run the utility by entering the full path (<drive>:\Program Files\Microsoft SQL 
Server\110\DTS\Binn) to the 64-bit version of the utility. 


e Permanently change the order of the paths in the PATH environment variable by placing the 64-bit path 
(<drive>\Program Files\Microsoft SQL Server\110\DTS\Binn) before the 32-bit path (<drive>:\ Program 
Files(x86)\Microsoft SQL Server\110\DTS\Binn) in the variable. 


Considerations on Computers with Side-by-Side Installations 


When SQL Server 2019 Integration Services (SSIS) is installed on a machine that has SQL Server 2005 
Integration Services (SSIS) or SQL Server 2008 Integration Services (SSIS) installed, multiple versions of the 
dtexec utility are installed. 


To ensure that you run the correct version of the utility, at the command prompt run the utility by entering the 
full path (<drive>:\Program Files\Microsoft SQL Server\<version>\DTS\Binn). 


Phases of Execution 


The utility has four phases that it proceeds through as it executes. The phases are as follows: 


1. Command sourcing phase: The command prompt reads the list of options and arguments that have been 
specified. All subsequent phases are skipped if a /? or /HELP option is encountered. 


2. Package load phase: The package specified by the /SQL, /FILE, or /DTS option is loaded. 
3. Configuration phase: Options are processed in this order: 

e Options that set package flags, variables, and properties. 

e Options that verify the package version and build. 

e Options that configure the run-time behavior of the utility, such as reporting. 


4. Validation and execution phase: The package is run, or validated without running if the /VALIDATE 
option was specified. 


Exit Codes Returned 


Exit codes returned from dtexec utility 


When a package runs, dtexec can return an exit code. The exit code is used to populate the ERRORLEVEL 
variable, the value of which can then be tested in conditional statements or branching logic within a batch file. 
The following table lists the values that the dtexec utility can set when exiting. 


VALUE DESCRIPTION 

0 The package executed successfully. 

1 The package failed. 

3 The package was canceled by the user. 

4 The utility was unable to locate the requested package. The 


package could not be found. 


5 The utility was unable to load the requested package. The 
package could not be loaded. 


6 The utility encountered an internal error of syntactic or 
semantic errors in the command line. 


Syntax Rules 


Utility syntax rules 


All options must start with a slash (/) or a minus sign (-). The options that are shown here start with a slash (/), 
but the minus sign (-) can be substituted. 


An argument must be enclosed in quotation marks if it contains a space. If the argument is not enclosed in 


quotation marks, the argument cannot contain white space. 
Doubled quotation marks within quoted strings represent escaped single quotation marks. 


Options and arguments are not case-sensitive, except for passwords. 


Using dtexec from the xp_cmdshell 


Using dtexec from the xp_cmdshell 


You can run dtexec from the xp_cmdshell prompt. The following example shows how to run a package called 
UpsertData.dtsx and ignore the return code: 


EXEC xp_cmdshell ‘dtexec /f "C:\UpsertData.dtsx"' 
The following example shows how to run the same package and capture the return code: 


DECLARE @returncode int 
EXEC @returncode = xp_cmdshell ‘dtexec /f "C:\UpsertData.dtsx"" 


IMPORTANT!! In MicrosoftSQL Server, the xp_cmdshell option is disabled by default on new installations. 
The option can be enabled by running the sp_configure system stored procedure. For more information, 
see xp_cmdshell Server Configuration Option. 


Using dtexec from Bash 


The Bash shell is a popular shell for Linux. It can also be used on Windows. You can run dtexec from the Bash 
prompt. Notice that a semicolon ( ; ) is acommand delimiter operator in Bash. This is particularly important 
when passing in values to the package using the /conn[ection] Or /Par[arameter] or' /Set options since they 
use the semicolon to separate the name and the value of the item provided. The following example shows how 
to properly escape the semicolon and other items when using Bash and passing in values to a package: 


dtexec /F MyPackage.dtsx /CONN "MyConnection"\;"\"MyConnectionString\"" 


Syntax 


dtexec /option [value] [/option [value]]... 


Parameters 


e /? [option_name|: (Optional). Displays the command prompt options, or displays help for the specified 
option_name and then closes the utility. 


If you specify an option_name argument, dtexec starts SQL Server Books Online and displays the dtexec 
Utility topic. 


e /Ca[llerInfo]: (Optional). Specifies additional information for a package execution. When you run a 
package using SQL Server Agent, agent sets this argument to indicate that the package execution is 
invoked by SQL Server Agent. This parameter is ignored when the dtexec utility is run from the 


command line. 


e /CheckF[ile] fi/espec (Optional). Sets the CheckpointFileName property on the package to the path 
and file spemandcified in filespec. This file is used when the package restarts. If this option is specified 
and no value is supplied for the file name, the CheckpointFileName for the package is set to an empty 
string. If this option is not specified, the values in the package are retained. 


e /CheckP[ointing] fon\off}: (Optional). Sets a value that determines whether the package will use 
checkpoints during package execution. The value on specifies that a failed package is to be rerun. When 
the failed package is rerun, the run-time engine uses the checkpoint file to restart the package from the 


point of failure. 


The default value is on if the option is declared without a value. Package execution will fail if the value is 
set to on and the checkpoint file cannot be found. If this option is not specified, the value set in the 
package is retained. For more information, see Restart Packages by Using Checkpoints. 


The /CheckPointing on option of dtexec is equivalent to setting the SaveCheckpoints property of the 
package to True, and the CheckpointUsage property to Always. 


e /Com[mandFile] fi/espec (Optional). Specifies the command options that run with dtexec. The file 
specified in filespecis opened and options from the file are read until EOF is found in the file. fi/especis a 
text file. The fi/espec argument specifies the file name and path of the command file to associate with the 
execution of the package. 


e /Conf[igFile] fi/espec (Optional). Specifies a configuration file to extract values from. Using this option, 
you can set a run-time configuration that differs from the configuration that was specified at design time 
for the package. You can store different configuration settings in an XML configuration file and then load 
the settings before package execution by using the /ConfigFile option. 


You can use the /ConfigFile option to load additional configurations at run time that you did not specify 
at design time. However, you cannot use the /ConfigFile option to replace configured values that you 
also specified at design time. To understand how package configurations are applied, see Package 
Configurations. 


e /Conn[ection] /d_ornameconnection_string [[;id_or_nameconnection_stringj...}: (Optional). Specifies 
that the connection manager with the specified name or GUID is located in the package, and specifies a 
connection string. 


This option requires that both parameters be specified: the connection manager name or GUID must be 
provided in the /d_or_name argument, and a valid connection string must be specified in the 


connection_string argument. For more information, see Integration Services (SSIS) Connections. 


At run time, you can use the /Connection option to load package configurations from a location other 
than the location that you specified at design time. The values of these configurations then replace the 
values that were originally specified. However you can use the /Connection option only for 
configurations, such as SQL Server configurations, that use a connection manager. To understand how 
package configurations are applied, see Package Configurations and Behavior Changes to Integration 
Services Features in SQL Server 2016. 


e /Cons[oleLog] [[d/splayoptions];[list_options,src_name_or_guid\...): (Optional). Displays specified log 
entries to the console during package execution. If this option is omitted, no log entries are shown in the 
console. If the option is specified without parameters that limit the display, every log entry will display. To 
limit the entries that are displayed to the console, you can specify the columns to show by using the 
displayoptions parameter, and limit the log entry types by using the /ist_ options parameter. 


NOTE: When you run a package on the Integration Services server by using the /ISSERVER 
parameter, console output is limited and most of the /Cons[oleLog] options are not applicable. All 
execution logs can be seen from the server in the related views or by using standard reports available 
in SQL Server Management Studio. For more information about the reports, see Reports for the 
Integration Services Server. 


The displayoptions values are as follows: 
o N (Name) 


o C (Computer) 


o O (Operator) 

o S (Source Name) 
© G (Source GUID) 

o X (Execution GUID) 


o M (Message) 


° 


T (Time Start and End) 

The /ist_options values are as follows: 

o /- Specifies the inclusion list. Only the source names or GUIDs that are specified are logged. 
o E- Specifies the exclusion list. The source names or GUIDs that are specified are not logged. 


o The src_name_or_guid parameter specified for inclusion or exclusion is an event name, source 


name, or source GUID. 
If you use multiple /ConsoleLog options on the same command prompt, they interact as follows: 
o Their order of appearance has no effect. 


o If no inclusion lists are present on the command line, exclusion lists are applied against all kinds of 


log entries. 


o If any inclusion lists are present on the command line, exclusion lists are applied against the union 


of all inclusion lists. 
For several examples of the /ConsoleLog option, see the Remarks section. 


/D[ts] package_path: (Optional). Loads a package from the SSIS Package Store. Packages that are stored 
in the SSIS Package Store, are deployed using the legacy package deployment model. To run packages 
that are deployed to the Integration Services server using the project deployment model, use the 
/\SServer option. For more information about the package and project deployment models, see 
Deployment of Projects and Packages. 


The package_path argument specifies the relative path of the SSIS package, starting at the root of the 
SSIS Package Store, and includes the name of the SSIS package. If the path or file name specified in the 
package_path argument contains a space, you must put quotation marks around the package_path 


argument. 


The /DTS option cannot be used together with the /File or /SQL option. If multiple options are specified, 
dtexec fails. 


/De[crypt] password (Optional). Sets the decryption password that is used when you load a package 
with password encryption. 


(Optional) Creates the debug dump files, .mdmp and .tmp, when one or more specified events occur 
while the package is running. The error code argument specifies the type of event code-error, warning, or 
information-that will trigger the system to create the debug dump files. To specify multiple event codes, 
separate each error code argument by a semi-colon (;). Do not include quotes with the error code 


argument. 


The following example generates the debug dump files when the 
DTS_E_CANNOTACQUIRECONNECTIONFROMCONNECTIONMANAGER error occurs. 


/Dump @xC@20801C 


/Dump error code. By default, Integration Services stores the debug dump files in the folder, 
<drive>:\Program Files\Microsoft SQL Server\110\Shared\ErrorDumps. 


NOTE: Debug dump files may contain sensitive information. Use an access control list (ACL) to 
restrict access to the files, or copy the files to a folder with restricted access. For example, before you 
send your debug files to Microsoft support services, we recommended that you remove any sensitive 
or confidential information. 


To apply this option to all packages that the dtexec utility runs, add a DumpOnCodes REG_SZ value to 
the HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Microsoft SQL Server\110\SSIS\Setup\DtsPath 
registry key. The data value in DumpOnCodes specifies the error code or codes that will trigger the 
system to create debug dump files. Multiple error codes must be separated by a semi-colon ()). 


If you add aDumpOnCodes value to the registry key, and use the /Dump option, the system will create 
debug dump files that are based on both settings. 


For more information about debug dump files, see Generating Dump Files for Package Execution. 


e /DumpOnError: (Optional) Creates the debug dump files, .mdmp and .tmp, when any error occurs while 
the package is running. 


By default, Integration Services stores the debug dump files in the folder, <drive>\Program 
Files\Microsoft SQL Server\110\Shared\ErrorDumps folder. 


NOTE: Debug dump files may contain sensitive information. Use an access control list (ACL) to 
restrict access to the files, or copy the files to a folder with restricted access. For example, before you 
send your debug files to Microsoft support services, we recommended that you remove any sensitive 
or confidential information. 


To apply this option to all packages that the dtexec utility runs, add aDumpOnError REG_LDWORD 
value to the HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Microsoft SQL 
Server\110\SSIS\Setup\DtsPath registry key. The value of the DumpOnError REG_DWORD value 
determines whether the /DumpOnError option needs to be used with the dtexec utility: 


o Anon-zero data value indicates that the system will create debug dump files when any error 
occurs, regardless of whether you use the /DumpOnError option with the dtexec utility. 


o A zero data value indicates that the system will not create the debug dump files unless you use the 
/DumpOnError option with the dtexec utility. 


For more information about debug dump files, see Generating Dump Files for Package Execution 


e /Env[Reference] environment reference /D. (Optional). Specifies the environment reference (ID) that is 
used by the package execution, for a package that is deployed to the Integration Services server. The 
parameters configured to bind to variables will use the values of the variables that are contained in the 
environment. 


You use /Env[Reference] option together with the /ISServer and the /Server options. 


This parameter is used by SQL Server Agent. 

--/F[ile] filespec (Optional). Loads a package that is saved in the file system. Packages that are saved in 
the file system, are deployed using the legacy package deployment model. To run packages that are 
deployed to the Integration Services server using the project deployment model, use the /ISServer 
option. For more information about the package and project deployment models, see Deployment of 
Projects and Packages 


The filespec argument specifies the path and file name of the package. You can specify the path as either a 


Universal Naming Convention (UNC) path or a local path. If the path or file name specified in the filespec 
argument contains a space, you must put quotation marks around the fi/espec argument. 


e The/File option cannot be used together with the /DTS or /SQL option. If multiple options are specified, 
dtexec fails. 


e /H[elp] [option_name|: (Optional). Displays help for the options, or displays help for the specified 
option_name and closes the utility. 


If you specify an option_name argument, dtexec starts SQL Server Books Online and displays the dtexec 
Utility topic. 


e /\SServer packagepath. (Optional). Runs a package that is deployed to the Integration Services server. 
The PackagePath argument specifies the full path and file name of the package deployed to the 
Integration Services server. If the path or file name specified in the PackagePath argument contains a 
space, you must put quotation marks around the PackagePath argument. 


The package format is as follows: 
\<catalog name>\<folder name>\<project name>\package file name 


You use /Server option together with the /ISSERVER option. Only Windows Authentication can execute 
a package on the SSIS Server. The current Windows user is used to access the package. If the /Server 
option is omitted, the default local instance of SQL Server is assumed. 


The /ISSERVER option cannot be used together with the /DTS, /SQL or /File option. If multiple options 
are specified, dtexec fails. 


This parameter is used by SQL Server Agent. 


e /L[ogger] classid_orprogid;configstring. (Optional). Associates one or more log providers with the 
execution of an SSIS package. The classid_orprogid parameter specifies the log provider, and can be 
specified as a class GUID. The configstring is the string that is used to configure the log provider. 


The following list shows the available log providers: 
° Text file: 

o ProgID: DTS.LogProviderTextFile.1 

o ClassID: {59B2C6A5-663F-4C20-8863-C83F9B72E2EB} 
o SQL Server Profiler: 

o ProglID: DTS.LogProviderSQLProfiler.1 

o ClassID: {5COB8D21-E9AA-462E-BA34-30FF5F7A42A1} 
o SQL Server: 

o ProgID: DTS.LogProviderSQLServer.1 

°o ClassID: {6AA833A1-E4B2-4431-831B-DE695049DC61} 
o Windows Event Log: 

© ProgID: DTS.LogProviderEventLog.1 


o ClassID: {97634F75-1DC7-4F1F-8A4C-DAFOE1 3AAA22} 


° 


XML File: 


o ProglD: DTS.LogProviderXMLFile.1 
o ClassID: {AFED6884-619C-484F-9A09-F42D56E1A7EA} 


e /M[axConcurrent] concurrent_executables. (Optional). Specifies the number of executable files that the 
package can run concurrently. The value specified must be either a non-negative integer, or -1. A value of 
-1 means that SSIS will allow a maximum number of concurrently running executables that is equal to 
the total number of processors on the computer executing the package, plus two. 


e /Pack[age] PackageName. (Optional). Specifies the package that is executed. This parameter is used 
primarily when you execute the package from Visual Studio. 


e /P[assword] password (Optional). Allows the retrieval of a package that is protected by SQL Server 
Authentication. This option is used together with the /User option. If the /Password option is omitted 
and the /User option is used, a blank password is used. The password value may be quoted. 


IMPORTANT!! When possible, use Windows authentication. 


e /Par[ameter] [$Package:: | $Project: | $ServerOption:] parameter_name [(data_type)]; /itera/_value. 
(Optional). Specifies parameter values. Multiple /Parameter options can be specified. The data types are 
CLR TypeCodes as strings. For a non-string parameter, the data type is specified in parenthesis, following 
the parameter name. 


The /Parameter option can be used only with the /ISServer option. 


You use the $Package, $Project, and $ServerOption prefixes to indicate a package parameter, project 
parameter, and a server option parameter, respectively. The default parameter type is package. 


The following is an example of executing a package and providing myvalue for the project parameter 
(myparam) and the integer value 12 for the package parameter (anotherparam). 


Dtexec /isserver "SSISDB\MyFolder\MyProject\MyPackage.dtsx" /server "." /parameter 
$Project::myparam;myvalue /parameter anotherparam(int32) ;12 


You can also set connection manager properties by using parameters. You use the CM prefix to denote a 
connection manager parameter. 


In the following example, InitialCatalog property of the SourceServer connection manager is set to 
ssisdb . 


/parameter CM.SourceServer.InitialCatalog;ssisdb 


In the following example, ServerName property of the SourceServer connection manager is set to a 
period (.) to indicate the local server. 


/parameter CM.SourceServer.ServerName; . 


e /Proj[ect] ProjectFile (Optional). Specifies the project from which to retrieve the package that is 
executed. The ProjectFile argument specifies the .ispac file name. This parameter is used primarily when 
you execute the package from Visual Studio. 


e /Rem comment (Optional). Includes comments on the command prompt or in command files. The 
argument is optional. The value of commentis a string that must be enclosed in quotation marks, or 
contain no white space. If no argument is specified, a blank line is inserted. comment values are discarded 
during the command sourcing phase. 


e /Rep[orting] /eve/ [;event_guid_or_namel;event_guid_or_namét...]]: (Optional). Specifies what types of 


messages to report. The available reporting options for /eve/are as follows: 
N No reporting. 

E Errors are reported. 

W Warnings are reported. 

| Informational messages are reported. 

C Custom events are reported. 

D Data Flow task events are reported. 

P Progress is reported. 

V Verbose reporting. 


The arguments of V and N are mutually exclusive to all other arguments; they must be specified alone. If 
the /Reporting option is not specified then the default level is E (errors), W (warnings), and P (progress). 


All events are preceded with a timestamp in the format "YY/MM/DD HH:MM:SS", and a GUID or friendly 
name if available. 


The optional parameter event_guid_or_nameis a list of exceptions to the log providers. The exception 
specifies the events that are not logged that otherwise might have been logged. 


You do not have to exclude an event if the event is not ordinarily logged by default 


/Res[tart] {deny / force | ifPossible}: (Optional). Specifies a new value for the CheckpointUsage property 
on the package. The meaning of the parameters are as follows: 


Deny Sets CheckpointUsage property to DISCU_NEVER. 
Force Sets CheckpointUsage property to DISCU_ALWAYS. 
ifPossible Sets CheckpointUsage property to DISCU_IFEXISTS. 
The default value of force is used if no value is specified. 


/Set [$Sensitive:] proper tyPath,value. (Optional). Overrides the configuration of a parameter, variable, 
property, container, log provider, Foreach enumerator, or connection within a package. When this option 
is used, /Set changes the propertyPath argument to the value specified. Multiple /Set options can be 
specified. 


In addition to using the /Set option with the /F[ile] option, you can also use the /Set option with the 
/\SServer option or the /Project option. When you use /Set with /Project, /Set sets parameter values. 
When you use /Set with /ISServer, /Set sets property overrides. In addition, when you use /Set with 
/\SServer, you can use the optional $Sensitive prefix to indicate that the property should be treated as 
sensitive on the Integration Services server. 


You can determine the value of propertyPath by running the Package Configuration Wizard. The paths for 
items that you select are displayed on the final Completing the Wizard page, and can be copied and 
pasted. If you have used the wizard only for this purpose, you can cancel the wizard after you copy the 
paths. 


The following is an example of executing a package that is saved in the file system and providing a new 


value for a variable: 
dtexec /f mypackage.dtsx /set \package.variables[myvariable].Value;myvalue 


The following example of running a package from the .ispac project file and setting package and project 


parameters. 


/Project c:\project.ispac /Package Packagel.dtsx /SET \Package.Variables[$Package: :Parameter];1 /SET 
\Package.Variables[$Project: :Parameter];1 


You can use the /Set option to change the location from which package configurations are loaded. 
However, you cannot use the /Set option to override a value that was specified by a configuration at 
design time. To understand how package configurations are applied, see Package Configurations and 
Behavior Changes to Integration Services Features in SQL Server 2016. 


/Ser[ver] server. (Optional). When the /SQL or /DTS option is specified, this option specifies the name 
of the server from which to retrieve the package. If you omit the /Server option and the /SQL or /DTS 
option is specified, package execution is tried against the local server. The server_instance value may be 
quoted. 


The /Ser[ver] option is required when the /ISServer option is specified. 


/SQ{[L] package_path: Loads a package that is stored in SQL Server, in msdb database. Packages that are 
stored in the msdb database, are deployed using the package deployment model. To run packages that 
are deployed to the Integration Services server using the project deployment model, use the /ISServer 
option. For more information about the package and project deployment models, see Deployment of 
Projects and Packages. 


The package_path argument specifies the name of the package to retrieve. If folders are included in the 
path, they are terminated with backslashes ("\"). The package_path value can be quoted. If the path or file 
name specified in the package_path argument contains a space, you must put quotation marks around 
the package_path argument. 


You can use the /User, /Password, and /Server options together with the /SQL option. 


If you omit the /User option, Windows Authentication is used to access the package. If you use the /User 
option, the /User login name specified is associated with SQL Server Authentication. 


The /Password option is used only together with the /User option. If you use the /Password option, the 
package is accessed with the user name and password information provided. If you omit the /Password 
option, a blank password is used. 


IMPORTANT!! When possible, use Windows authentication. 


If the /Server option is omitted, the default local instance of SQL Server is assumed. 


The /SQL option cannot be used together with the /DTS or /File option. If multiple options are specified, 
dtexec fails. 


/Su[m]: (Optional). Shows an incremental counter that contains the number of rows that will be received 
by the next component. 


/U[ser] user_name (Optional). Allows the retrieval of a package that is protected by SQL Server 
Authentication. This option is used only when the /SQL option is specified. The user_name value can be 
quoted. 


IMPORTANT!! When possible, use Windows authentication. 


/Va[lidate]: (Optional). Stops the execution of the package after the validatation phase, without actually 
running the package. During validation, use of the /WarnAsError option causes dtexec to treat a 


warning as an error; therefore the package fails if a warning occurs during validation. 


/VerifyB[uild] major;minor;build\}: (Optional). Verifies the build number of a package against the build 


numbers that were specified during the verification phase in the major, minor, and build arguments. If a 
mismatch occurs, the package will not execute. 


The values are long integers. The argument can have one of three forms, with a value for major always 
required: 


° major 
° majorminor 


° major, minor, build 


/VerifyP[ackagelD] package/D. (Optional). Verifies the GUID of the package to be executed by 
comparing it to the value specified in the package_id argument. 


/VerifyS[igned]: (Optional). Causes Integration Services to check the digital signature of the package. If 
the package is not signed or the signature is not valid, the package fails. For more information, see 
Identify the Source of Packages with Digital Signatures. 


IMPORTANT!! When configured to check the signature of the package, Integration Services only 
checks whether the digital signature is present, is valid, and is from a trusted source. Integration 
Services does not check whether the package has been changed. 


NOTE: The optional BlockedSignatureStates registry value can specify a setting that is more 
restrictive than the digital signature option set in SQL Server Data Tools (SSDT) or at the dtexec 
command line. In this situation, the more restrictive registry setting overrides the other settings. 


/VerifyV[ersion|D] version/D. (Optional). Verifies the version GUID of a package to be executed by 
comparing it to the value specified in the version_id argument during package Validation Phase. 


/VLog /Filespecj: (Optional). Writes all Integration Services package events to the log providers that were 
enabled when the package was designed. To have Integration Services enable a log provider for text files 
and write log events to a specified text file, include a path and file name as the Fi/espec parameter. 


If you do not include the Fi/espec parameter, Integration Services will not enable a log provider for text 
files. Integration Services will only write log events to the log providers that were enabled when the 
package was designed. 


e /W[arnAsError]: (Optional). Causes the package to consider a warning as an error; therefore, the 
package will fail if a warning occurs during validation. If no warnings occur during validation and the 


/Validate option is not specified, the package is executed. 


e /X86: (Optional). Causes SQL Server Agent to run the package in 32-bit mode on a 64-bit computer. This 
option is set by SQL Server Agent when the following conditions are true: 


o The job step type is SQL Server Integration Services package. 


o The Use 32 bit runtime option on the Execution options tab of the New Job Step dialog box 
is selected. 


You can also set this option for a SQL Server Agent job step by using stored procedures or SQL Server 
Management Objects (SMO) to programmatically create the job. 


This option is only used by SQL Server Agent. This option is ignored if you run the dtexec utility at the 
command prompt. 


Remarks 


The order in which you specify command options can influence the way in which the package executes: 


@ Options are processed in the order they are encountered on the command line. Command files are read 
in as they are encountered on the command line. The commands in the command file are also processed 
in the order they are encountered. 


e Ifthe same option, parameter, or variable appears in the same command line statement more than one 
time, the last instance of the option takes precedence. 


e /Set and/ConfigFile options are processed in the order they are encountered. 


Examples 


The following examples demonstrate how to use the dtexec command prompt utility to configure and execute 
SQL Server Integration Services packages. 


Running Packages 


To execute an SSIS package saved to SQL Server using Windows Authentication, use the following code: 
dtexec /sq pkgOne /ser productionServer 

To execute an SSIS package saved to the File System folder in the SSIS Package Store, use the following code: 
dtexec /dts "\File System\MyPackage" 


To validate a package that uses Windows Authentication and is saved in SQL Server without executing the 
package, use the following code: 


dtexec /sq pkgOne /ser productionServer /va 

To execute an SSIS package that is saved in the file system, use the following code: 
dtexec /f "c:\pkgOne.dtsx" 

To execute an SSIS package that is saved in the file system, and specify logging options, use the following code: 
dtexec /f "c:\pkgOne.dtsx" /1 "DTS.LogProviderTextFile;c:\log.txt” 


To execute a package that uses Windows Authentication and is saved to the default local instance of SQL Server, 
and verify the version before it is executed, use the following code: 


dtexec /sq pkgOne /verifyv {c200e360-38c5-11c5-11ce-ae62-08002b2b79eF } 
To execute an SSIS package that is saved in the file system and configured externally, use the following code: 


dtexec /f "c:\pkgOne.dtsx" /conf "c:\pkgOneConfig.cfg" 


NOTE: The package_path or filespec arguments of the /SQL, /DTS, or /FILE options must be enclosed in 
quotation marks if the path or file name contains a space. If the argument is not enclosed in quotation 
marks, the argument cannot contain white space. 


Logging Option 


If there are three log entry types of A, B, and C, the following ConsoleLog option without a parameter displays 
all three log types with all fields: 


/CONSOLELOG 


The following option displays all log types, but with the Name and Message columns only: 


/CONSOLELOG NM 


The following option displays all columns, but only for log entry type A: 


/CONSOLELOG I;LogEntryTypeA 


The following option displays only log entry type A, with Name and Message columns: 


/CONSOLELOG NM;1I;LogEntryTypeA 


The following option displays log entries for log entry types A and B: 


/CONSOLELOG I;LogEntryTypeA; LogEntryTypeB 


You can achieve the same results by using multiple ConsoleLog options: 


/CONSOLELOG I;LogEntryTypeA /CONSOLELOG I;LogEntryTypeB 


If the ConsoleLog option is used without parameters, all fields are displayed. The inclusion of a /ist_options 
parameter causes the following to displays only log entry type A, with all fields: 


/CONSOLELOG NM;I;LogEntryTypeA /CONSOLELOG 


The following displays all log entries except log entry type A: that is, it displays log entry types B and C: 


/CONSOLELOG E;LogEntryTypeA 


The following example achieves the same results by using multiple ConsoleLog options and a single exclusion: 


/CONSOLELOG E;LogEntryTypeA /CONSOLELOG 
/CONSOLELOG E;LogEntryTypeA /CONSOLELOG E;LogEntryTypeA 
/CONSOLELOG E;LogEntryTypeA;LogEntryTypeA 


The following example displays no log messages, because when a log file type is found in both the included and 
excluded lists, it will be excluded. 


/CONSOLELOG E;LogEntryTypeA /CONSOLELOG I;LogEntryTypeA 


SET Option 


The following example shows how to use the /SET option, which lets you change the value of any package 
property or variable when you start the package from the command line. 


/SET \package\DataFlowTask.Variables[User: :MyVariable].Value;newValue 


Project Option 


The following example shows how to use the /Project and the /Package option. 


/Project c:\project.ispac /Package Packagel.dtsx 


The following example shows how to use the /Project and /Package options, and set package and project 
parameters. 


/Project c:\project.ispac /Package Packagel.dtsx /SET \Package.Variables[$Package: :Parameter];1 /SET 
\Package.Variables[$Project: :Parameter];1 


ISServer Option 


The following example shows how to use the /ISServer option. 


dtexec /isserver "\SSISDB\MyFolder\MyProject\MyPackage.dtsx" /server "." 


The following example shows how to use the /ISServer option and set project and connection manager 
parameters. 


/Server localhost /ISServer "\SSISDB\MyFolder\Integration Services Project1\Package.dtsx" /Par 
“¢Project: :ProjectParameter(Int32)";1 /Par "CM.SourceServer.InitialCatalog" ;SourceDB 


Related Content 


Blog entry, Exit Codes, DTEXEC, and SSIS Catalog, on www.mattmasson.com. 


Restart Packages by Using Checkpoints 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Integration Services can restart failed packages from the point of failure, instead of rerunning the whole 
package. If a package is configured to use checkpoints, information about package execution is written to a 
checkpoint file. When the failed package is rerun, the checkpoint file is used to restart the package from the 
point of failure. If the package runs successfully, the checkpoint file is deleted, and then re-created the next time 
the package is run. 


Using checkpoints in a package can provide the following benefits. 


e Avoid repeating the downloading and uploading of large files. For example, a package that downloads 
multiple large files by using an FTP task for each download can be restarted after the downloading of a 
single file fails and then download only that file. 


e Avoid repeating the loading of large amounts of data. For example, a package that performs bulk inserts 
into dimension tables in a data warehouse using a different Bulk Insert task for each dimension can be 
restarted if the insertion fails for one dimension table, and only that dimension will be reloaded. 


e Avoid repeating the aggregation of values. For example, a package that computes many aggregates, such 
as averages and sums, using a separate Data Flow task to perform each aggregation, can be restarted 
after computing an aggregation fails and only that aggregation will be recomputed. 


If a package is configured to use checkpoints, Integration Services captures the restart point in the checkpoint 
file. The type of container that fails and the implementation of features such as transactions affect the restart 
point that is recorded in the checkpoint file. The current values of variables are also captured in the checkpoint 
file. However, the values of variables that have the Object data type are not saved in checkpoint files. 


Defining Restart Points 


The task host container, which encapsulates a single task, is the smallest atomic unit of work that can be 
restarted. The Foreach Loop container and a transacted container are also treated as atomic units of work. 


If a package is stopped while a transacted container is running, the transaction ends and any work performed by 
the container is rolled back. When the package is restarted, the container that failed is rerun. The completion of 
any child containers of transacted container is not recorded in the checkpoint file. Therefore, when the package 
is restarted, the transacted container and its child containers run again. 





NOTE 


Using checkpoints and transactions in the same package could cause unexpected results. For example, when a package 
fails and restarts from a checkpoint, the package might repeat a transaction that has already been successfully committed. 





Checkpoint data is not saved for For Loop and Foreach Loop containers. When a package is restarted, the For 
Loop and Foreach Loop containers and the child containers are run again. If a child container in the loop runs 
successfully, it is not recorded in the checkpoint file, instead it is rerun. For more information and a workaround, 


see SSIS Checkpoints are not honored for For Loop or Foreach Loop container items. 


If the package is restarted the package configurations are not reloaded, instead the package uses the 
configuration information written to the checkpoint file. This ensures that the package uses the same 





configurations when it is rerun as the time it failed. 


A package can be restarted only at the control flow level. You cannot restart a package in the middle of a data 
flow. To avoid rerunning the whole data flow, the package might be designed to include multiple data flows, each 
one using a different Data Flow task. This way the package can be restarted, rerunning only one Data Flow task. 


Configuring a Package to Restart 


The checkpoint file includes the execution results of all completed containers, the current values of system and 
user-defined variables, and package configuration information. The file also includes the unique identifier of the 
package. To successfully restart a package, the package identifier in the checkpoint file and the package must 
match; otherwise the restart fails. This prevents a package from using a checkpoint file written by a different 
package version. If the package runs successfully, after it is restarted the checkpoint file is deleted. 


The following table lists the package properties that you set to implement checkpoints. 


PROPERTY DESCRIPTION 

CheckpointFileName Specifies the name of the checkpoint file. 
CheckpointUsage Specifies whether checkpoints are used. 
SaveCheckpoints Indicates whether the package saves checkpoints. This 


property must be set to True to restart a package from a 
point of failure. 


Additionally, you must set the FailPackageOnFailure property to true for all the containers in the package that 
you want to identify as restart points. 


You can use the ForceExecutionResult property to test the use of checkpoints in a package. By setting 
ForceExecutionResult of a task or container to Failure, you can imitate real-time failure. When you rerun the 
package, the failed task and containers will be rerun. 


Checkpoint Usage 


The CheckpointUsage property can be set to the following values: 
VALUE DESCRIPTION 


Never Specifies that the checkpoint file is not used and that the 
package runs from the start of the package workflow. 


Always Specifies that the checkpoint file is always used and that the 
package restarts from the point of the previous execution 
failure. If the checkpoint file is not found, the package fails. 


IfExists Specifies that the checkpoint file is used if it exists. If the 
checkpoint file exists, the package restarts from the point of 
the previous execution failure; otherwise, it runs from the 
start of the package workflow. 





NOTE 


The /CheckPointing on option of dtexec is equivalent to setting the SaveCheckpoints property of the package to 
True, and the CheckpointUsage property to Always. For more information, see dtexec Utility. 











Securing Checkpoint Files 


Package level protection does not include protection of checkpoint files and you must secure these files 
separately. Checkpoint data can be stored only in the file system and you should use an operating system access 
control list (ACL) to secure the location or folder where you store the file. It is important to secure checkpoint 
files because they contain information about the package state, including the current values of variables. For 
example, a variable may contain a recordset with many rows of private data such as telephone numbers. For 
more information, see Access to Files Used by Packages. 


Configure Checkpoints for Restarting a Failed Package 


You configure Integration Services packages to restart from a point of failure, instead of rerunning the entire 
package, by setting the properties that apply to checkpoints. 


To configure a package to restart 


1. In SQL Server Data Tools (SSDT), open the Integration Services project that contains the package you 
want to configure. 


2. InSolution Explorer, double-click the package to open it. 

3. Click the Control Flow tab. 

4. Right-click anywhere in the background of the control flow design surface, and then click Properties. 
5. Set the SaveCheckpoints property to True. 

6. Type the name of the checkpoint file in the CheckpointFileName property. 

7. Set the CheckpointUsage property to one of two values: 


e Select Always to always restart the package from the checkpoint. 





IMPORTANT 


An error occurs if the checkpoint file is not available. 





e Select IfExists to restart the package only if the checkpoint file is available. 
8. Configure the tasks and containers from which the package can restart. 
e Right-click a task or container and click Properties. 


e Set the FailPackageOnFailure property to True for each selected task and container. 


External Resources 


e Technical article, Automatic Restart of SSIS packages after Failover or Failure, on 
social.technet.microsoft.com 


e Support article, SSIS Checkpoints are not honored for For Loop or Foreach Loop container items, on 
support.microsoft.com. 


SQL Server Agent Jobs for Packages 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


You can automate and schedule the execution of SQL Server Integration Services packages by using SQL Server 
Agent. You can schedule packages that are deployed to the Integration Services server, and are stored in SQL 
Server, the SSIS Package Store, and the file system. 


NOTE 


This article describes how to schedule SSIS packages in general, and how to schedule packages on premises. You can also 
run and schedule SSIS packages on the following platforms: 


e The Microsoft Azure cloud. For more info, see Lift and shift SQL Server Integration Services workloads to the cloud 
and Schedule the execution of an SSIS package in Azure. 
e Linux. For more info, see Extract, transform, and load data on Linux with SSIS and Schedule SQL Server Integration 


Services package execution on Linux with cron. 











Sections in This Topic 


This topic contains the following sections: 
e Scheduling jobs in SQL Server Agent 
e Scheduling Integration Services packages 


e Troubleshooting scheduled packages 


Scheduling Jobs in SQL Server Agent 


SQL Server Agent is the service installed by SQL Server that lets you automate and schedule tasks by running 
SQL Server Agent jobs. The SQL Server Agent service must be running before jobs can run automatically. For 
more information, see Configure SQL Server Agent. 


The SQL Server Agent node appears in Object Explorer in SQL Server Management Studio when you connect 
to an instance of the SQL Server Database Engine. 


To automate a recurring task, you create a job by using the New Job dialog box. For more information, see 
Implement Jobs. 


After you create the job, you must add at least one step. A job can include multiple steps, and each step can 
perform a different task. For more information, see Manage Job Steps. 


After you create the job and the job steps, you can create a schedule for running the job. However you can also 
create an unscheduled job that you run manually. For more information, see Create and Attach Schedules to 
Jobs. 


You can enhance the job by setting notification options, such as specifying an operator to send an e-mail 
message to when the job finishes, or adding alerts. For more information, see Alerts. 


Scheduling Integration Services Packages 


When you create a SQL Server Agent job to schedule Integration Services packages, you must add at least one 
step and set the type of the step to SQL Server Integration Services Package. A job can include multiple 
steps, and each step can run a different package. 


Running an Integration Services package from a job step is like running a package by using the dtexec 
(dtexec.exe) and DTExecUI (dtexecui.exe) utilities. Instead of setting the run-time options for a package by using 
command-line options or the Execute Package Utility dialog box, you set the run-time options in the New 
Job Step dialog box. For more information about the options for running a package, see dtexec Utility. 


For more information, see Schedule a Package by using SQL Server Agent. 


For a video that demonstrates how to use SQL Server Agent to run a package, see the video home page, How to: 
Automate Package Execution by Using the SQL Server Agent (SQL Server Video), in the MSDN Library. 


Troubleshooting 


A SQL Server Agent job step may fail to start a package even though the package runs successfully in SQL 
Server Data Tools (SSDT) and from the command line. There are some common reasons for this issue and 
several recommended solutions. For more information, see the following resources. 


e Microsoft Knowledge Base article, An SSIS package does not run when you call the SSIS package from a 
SQL Server Agent job step 


e Video, Troubleshooting: Package Execution Using SQL Server Agent (SQL Server Video), in the MSDN 
Library. 


After a SQL Server Agent job step starts a package, the package execution may fail or the package may run 
successfully but with unexpected results. You can use the following tools to troubleshoot these issues. 


e For packages that are stored in the SQL Server MSDB database, the SSIS Package Store, or in a folder on 
your local machine, you can use the Log File Viewer as well as any logs and debug dump files that were 
generated during the execution of the package. 


To use the Log File Viewer, do the following. 
1. Right-click the SQL Server Agent job in Object Explorer and then click View History. 


2. Locate the job execution in the Log file summary box with the job failed message in the 


Message column. 


3. Expand the job node, and click the job step to view the details of the message in the area below the 
Log file summary box. 


e For packages that are stored in the SSISDB database, you can also use the Log File Viewer as well as 
any logs and debug dump files that were generated during the execution of the package. In addition, you 
can use the reports for the Integration Services server. 


To find information in the reports for the package execution associated with a job execution, 
do the following. 


1. Follow the steps above to view the details of the message for the job step. 

2. Locate the Execution ID listed in the message. 

3. Expand the Integration Services Catalog node in Object Explorer. 

4. Right-click SSISDB, point to Reports, then Standard Reports, and then click All Executions. 


5. In the All Executions report, locate the Execution ID in the ID column. Click Overview, All 
Messages, or Execution Performance to view information about this package execution. 


For more information about the Overview, All Messages, and Execution Performance reports, see Reports 
for the Integration Services Server. 


Schedule a Package by using SQL Server Agent 


The following procedure provides steps to automate the execution of a package by using a SQL Server Agent 
job step to run the package. 


To automate package execution by using SQL Server Agent 


1. In SQL Server Management Studio, connect to the instance of SQL Server on which you want to create a 
job, or the instance that contains the job to which you want to add a step. 


2. Expand the SQL Server Agent node in Object Explorer and perform one of the following tasks: 
@ To create a new job, right-click Jobs and then click New Job. 
e To add a step to an existing job, expand Jobs, right-click the job, and then click Properties. 


3. On the General page, if you are creating a new job, provide a job name, select an owner and job 
category, and, optionally, provide a job description. 


4. To make the job available for scheduling, select Enabled. 
5. To create a job step for the package you want to schedule, click Steps, and then click New. 
6. Select Integration Services Package for the job step type. 


7. Inthe Run as list, select SQL Server Agent Service Account or select a proxy account that has the 
credentials that the job step will use. For information about creating a proxy account, see Create a SQL 
Server Agent Proxy. 


Using a proxy account instead of the SQL Server Agent Service Account may resolve common issues 
that can occur when executing a package using the SQL Server Agent. For more information about these 
issues, see the Microsoft Knowledge Base article, An SSIS package does not run when you call the SSIS 
package from a SQL Server Agent job step. 


e When running job with a Proxy, one has to have the following security items in place for the job to 
successfuly run. 


Credential Login used by the Proxy, the account running the SQL Server Agent and the account 
running the SQL Server Service require the following permissions: 


o Local Security Policy Attribue: Replace a Process Level Token 
9° Full control over %SYSTEMROOT%\Temp 


Failure to put in the security items will result in the job failing and an error message similar to the 
following: The job failed. A required privilege is not held by the client. 


NOTE: If the password changes for the credential that the proxy account uses, you need to 
update the credential password. Otherwise, the job step will fail. 


For information about configuring the SQL Server Agent service account, see Set the Service 
Startup Account for SQL Server Agent (SQL Server Configuration Manager). 


8. In the Package Source list box, click the source of the package and then configure the options for the 
job step. 


The following table describes the possible package sources. 


PACKAGE SOURCE 


SSIS Catalog 


SQL Server 


SSIS Package Store 


File System 


DESCRIPTION 


Packages that are stored in the SSISDB database. The 
packages are contained in Integration Services projects 
that are deployed to the Integration Services server. 


Packages that are stored in the MSDB database. You use 
the Integration Services service to manage these 
packages. 


Packages that are stored in the default folder on your 
computer. The default folder is <drive>:\Program 
Files\Microsoft SQL Server\110\DTS\Packages. You use 
the Integration Services service to manage these 
packages. 


Note: You can specify a different folder or specify 
additional folders in the file system to be managed by 
the Integration Services service, by modifying the 
configuration file for Integration Services. For more 
information, see Integration Services Service (SSIS 
Service). 


Packages that are stored in any folder on your local 
machine. 


The following tables describe the configuration options that are available for the job step 


depending on the package source you select. 


IMPORTANT: If the package is password-protected, when you click any of the tabs on the General 


page of the New Job Step dialog box, with the exception of the Package tab, you need to enter the 


password in the Package Password dialog box that appears. Otherwise the SQL Server Agent job 


will fail to run the package. 


Package Source: SSIS Catalog 


TAB 


Package 


OPTIONS 


Server 


Type or select the name of the database server instance 
that hosts the SSISDB catalog. 


When SSIS Catalog is the package source, you can log 


on to the server using only a Microsoft Windows user 
account. SQL Server authentication is not available. 


Package 
Click the ellipsis button and select a package. 
You are selecting a package in a folder under the 


Integration Services Catalogs node in Object 
Explorer. 


TAB 


Parameters 


Located on the Configuration tab. 


OPTIONS 


The Integration Services Project Conversion 
Wizard enables you to replace package configurations 
with parameters. 


The Parameters tab displays parameters that you 
added when you designed the package, for example by 
using SQL Server Data Tools (SSDT). The tab also displays 
parameters that were added to the package when you 
converted the Integration Services project from the 
package deployment model to the project deployment 
model. Enter new values for parameters that are 
contained in the package. You can enter a literal value or 
use the value contained in a server environment variable 
that you have already mapped to the parameter. 


To enter the literal value, click the ellipsis button next to a 
parameter. The Edit Literal Value for Execution 
dialog box appears. 


To use an environment variable, click Environment and 
then select the environment that contains the variable 
you want to use. 


** Important ** If you have mapped multiple 
parameters and/or connection manager properties to 
variables contained in multiple environments, SQL Server 
Agent displays an error message. For a given execution, 
a package can execute only with the values contained in 
a single server environment. 


For information on how to create a server environment 
and map a variable to a parameter, see Deploy 
Integration Services (SSIS) Projects and Packages. 


TAB 


Connection Managers 


Located on the Configuration tab. 


Advanced 


Located on the Configuration tab. 


OPTIONS 


Change values for connection manager properties. For 
example, you can change the server name. Parameters 
are automatically generated on the SSIS server for the 
connection manager properties. To change a property 
value, you can enter a literal value or use the value 
contained in a server environment variable that you 
have already mapped to the connection manager 


property. 


To enter the literal value, click the ellipsis button next to a 
parameter. The Edit Literal Value for Execution 
dialog box appears. 


To use an environment variable, click Environment and 
then select the environment that contains the variable 
you want to use. 


** Important ** If you have mapped multiple 
parameters and/or connection manager properties to 
variables contained in multiple environments, SQL Server 
Agent displays an error message. For a given execution, 
a package can execute only with the values contained in 
a single server environment. 


For information on how to create a server environment 
and map a variable to a connection manager property, 
see Deploy Integration Services (SSIS) Projects and 
Packages. 


Configure the following additional settings for the 
package execution: 


TAB 


OPTIONS 


Property overrides: 


Click Add to enter a new value for a package property, 
specify the property path, and indicate whether the 
property value is sensitive. The Integration Services 
server encrypts sensitive data. To edit or remove the 
settings for a property, click a row in the Property 
overrides box and then click Edit or Remove. You can 
find the property path by doing one of the following: 


-Copy the property path from the XML configuration file 
(*.dtsconfig) file. The path is listed in the Configuration 
section of the file, as a value of the Path attribute. The 
following is an example of the path for the 
MaximumErrorCount property: 
\Package.Properties[MaximumErrorCount] 


-Run the Package Configuration Wizard and copy 
the property paths from the final Completing the 
Wizard page. You can then cancel the wizard. 


Note: The Property overrides option is intended for 
packages with configurations that you upgraded from a 
previous release of Integration Services. Packages that 
you create using SQL Server 2019 Integration Services 
(SSIS) and deploy to the Integration Services server use 
parameters instead of configurations. 


Logging level 


Select one of the following logging levels for the package 
execution. Note that selecting the Performance or 
Verbose logging level may impact the performance of 
the package execution. 


None: 
Logging is turned off. Only the package execution status 
is logged. 


Basic: 
All events are logged, except custom and diagnostic 
events. This is the default value for the logging level. 


Performance: 
Only performance statistics, and OnError and 
OnWarning events, are logged. 


Verbose: 
All events are logged, including custom and diagnostic 
events. 


The logging level you select determines what information 
is displayed in SSISDB views and in reports for the 
Integration Services server. For more information, see 
Integration Services (SSIS) Logging. 


TAB 


OPTIONS 


Dump on errors 


Specify whether debug dump files are generated when 
any error occurs during the execution of the package. 
The files contain information about the execution of the 
package that can help you troubleshoot issues. When 
you select this option, and an error occurs during 
execution, Integration Services creates a .mdmp file 
(binary file) and a tmp file (text file). By default, 
Integration Services stores the files in the 
<drive>\Program Files\Microsoft SQL 
Server\110\Shared\ErrorDumps folder. 


32-bit runtime 


Indicate whether to run the package using the 32-bit 
version of the dtexec utility on a 64-bit computer that 
has the 64-bit version of SQL Server and SQL Server 
Agent installed. 


You may need to run the package using the 32-bit 
version of dtexec if for example your package uses a 
native OLE DB provider that is not available in a 64-bit 
version. For more information, see 64 bit Considerations 
for Integration Services. 


By default, when you select the SQL Server 
Integration Services Package job step type, SQL 
Server Agent runs the package using the version of the 
dtexec utility that is automatically invoked by the system. 
The system invokes either the 32-bit or 64-bit version of 
the utility depending on the computer processor, and 
the version of SQL Server and SQL Server Agent that is 
running on the computer. 


Package Source: SQL Server, SSIS Package Store, or File System 


Many of the options that you can set for packages stored in SQL Server, the SSIS Package Store, or the file 


system, correspond to command-line options for the dtexec command prompt utility. For more 


information about the utility and command-line options, see dtexec Utility. 


TAB 


Package 


These are the tab options for packages that are stored in 
SQL Server or the SSIS Package Store. 


OPTIONS 


Server 


Type or select the name of the database server instance 
for SQL Server or the Integration Services service. 


Use Windows Authentication 


Select this option to log on to the server using a 
Microsoft Windows user account. 


TAB 


Package 


These are the tab options for packages that are stored in 
the file system. 


Configurations 


Command files 


OPTIONS 


Use SQL Server Authentication 


When a user connects with a specified login name and 
password from a non-trusted connection, SQL Server 
performs the authentication by checking to see if a SQL 
Server login account has been set up and if the specified 
password matches the one previously recorded. If SQL 
Server cannot find the login account, authentication fails, 
and the user receives an error message. 


User Name 


Password 


Package 
Click the ellipsis button and select the package. 


You are selecting a package in a folder under the Stored 
Packages node in Object Explorer. 


Package 


Type the full path for the package file, or click the ellipsis 
button to select the package. 


Add an XML configuration file to run the package with a 
specific configuration. You use a package configuration to 
update the values of package properties at runtime. 


This option corresponds to the /ConfigFile option for 
dtexec. 


To understand how package configurations are applied, 
see Package Configurations. For information on how to 
create a package configuration, see Create Package 
Configurations. 


Specify additional options you want to run with dtexec, 
in a separate file. 


For example, you can include a file that contains the 
/Dump errorcode option, to generate debug dump files 
when one or more specified events occur while the 
package is running. 


You can run a package with different sets of options by 
creating multiple files and then specifying the 
appropriate file by using the Command files option. 


The Command files option corresponds to the 
/CommandFile option for dtexec. 


TAB 


Data Sources 


OPTIONS 


View the connection managers contained in the package. 
To modify a connection string, click the connection 
manager and then click the connection string. 


This option corresponds to the /Connection option for 
dtexec. 


TAB 


Execution Options 


OPTIONS 


Fail the package on validation warnings 

Indicates whether a warning message is consider an 
error. If you select this option and a warning occurs 
during validation, the package will fail during validation. 
This option corresponds to the /WarnAsError option 
for dtexec. 


Validate package without executing 

Indicates whether the package execution is stopped after 
the validation phase without actually running the 
package. This option corresponds to the /Validate 
option for dtexec. 


Override MacConcurrentExecutables property 
Specifies the number of executable files that the package 
can run concurrently. A value of -1 means that the 
package can run a maximum number of executable files 
equal to the total number of processors on the 
computer executing the package, plus two. This option 
corresponds to the /MaxConcurrent option for 
dtexec. 


Enable package checkpoints 

Indicates whether the package will use checkpoints 
during package execution. For more information, see 
Restart Packages by Using Checkpoints. 


This options corresponds to the /CheckPointing option 
for dtexec. 


Override restart options 

Indicates whether a new value is set for the 
CheckpointUsage property on the package. Select a 
value from the Restart option list box. 


This option corresponds to the /Restart option for 
dtexec. 


Use 32 bit runtime 

Indicate whether to run the package using the 32-bit 
version of the dtexec utility on a 64-bit computer that 
has the 64-bit version of SQL Server and SQL Server 
Agent installed. 


You may need to run the package using the 32-bit 
version of dtexec if for example your package uses a 
native OLE DB provider that is not available in a 64-bit 
version. For more information, see 64 bit Considerations 
for Integration Services. 


By default, when you select the SQL Server 
Integration Services Package job step type, SQL 
Server Agent runs the package using the version of the 
dtexec utility that is automatically invoked by the system. 
The system invokes either the 32-bit or 64-bit version of 
the utility depending on the computer processor, and 
the version of SQL Server and SQL Server Agent that is 
running on the computer. 


TAB 


Logging 


Set values 


OPTIONS 


Associate a log provider with the execution of the 
package. 


SSIS log provider for Text files 
Writes log entries to ASCII text files 


SSIS log provider for SQL Server 
Writes log entries to the sysssislog table in the MSDB 
database. 


SSIS log provider for SQL Server Profiler 
Writes traces that you can view using SQL Server Profiler. 


SSIS log provider for Windows Event Log 
Writes log entries to the Application log in the Windows 
Event log. 


SSIS log provider for XML files 
Writes log files to an XML file. 


For the text file, XML file, and the SQL Server Profiler log 
providers, you are selecting file connection managers 
that are contained in the package. For the SQL Server 
log provider, you are selecting an OLE DB connection 
manager that is contained in the package. 


This option corresponds to the /Logger option for 
dtexec. 


Override a package property setting. In the Properties 
box, enter values in the Property Path and Value 
columns. After you enter values for one property, an 
empty row appears in the Properties box to enable you 
to enter values for another property. 


To remove a property from the Properties box, click the 
row and then click Remove. 


You can find the property path by doing one of the 
following: 


-Copy the property path from the XML configuration file 
(*.dtsconfig) file. The path is listed in the Configuration 
section of the file, as a value of the Path attribute. The 
following is an example of the path for the 
MaximumErrorCount property: 
\Package.Properties[MaximumErrorCount] 


-Run the Package Configuration Wizard and copy 
the property paths from the final Completing the 
Wizard page. You can then cancel the wizard. 


TAB OPTIONS 


Verification Execute only signed packages 
Indicates whether the package signature is checked. If 
the package is not signed or the signature is not valid, 
the package fails. This option corresponds to the 
/NerifySigned option for dtexec. 


Verify Package build 

Indicates whether the build number of the package is 
verified against the build number that is entered in the 
Build box next to this option. If a mismatch occurs, the 
package will not execute. This option corresponds to the 
/NerifyBuild option for dtexec. 


Verify package ID 

Indicates whether the GUID of the package is verified, by 
comparing it to the package ID that is entered in the 
Package ID box next to this option. This option 
corresponds to the /VerifyPackagelD option for 
dtexec. 


Verify version ID 

Indicates whether the version GUID of the package is 
verified, by comparing it version ID that is entered in the 
Version ID box next to this option. This option 
corresponds to the /VerifyVersionID option for 
dtexec. 


Command line Modify the command line options for dtexec. For more 
information about the options, see dtexec Utility. 


Restore the original options 

Use the command-line options that you have set in the 
Package, Configurations, Command files, Data 
sources, Execution options, Logging, Set values, 
and Verification tabs of the Job Set Properties 
dialog box. 


Edit the command manually 
Type additional command-line options in the Command 
line box. 


Before you click OK to save your changes to the job 
step, you can remove all of the additional options that 
you've typed in the Command line box by clicking 
Restore the original options. 


** Tip ** You can copy the command line to a 
Command Prompt window, add dtexec , and run the 


package from the command line. This is an easy way to 
generate the command line text. 


9. Click OK to save the settings and close the New Job Step dialog box. 


10. 





NOTE 


For packages that are stored in the SSIS Catalog, the OK button is disabled when there is an unresolved 
parameter or connection manager property setting. An unresolved setting occurs when you are using a value 
contained in a server environment variable to set the parameter or property and one of the following conditions 


is met.: 
The Environment checkbox on the Configuration tab is not selected. 


The server environment that contains the variable is not selected in the list box on the Configuration tab. 








To create a schedule for a job step, click Schedules in the Select a page pane. For information on how 
to configure a schedule, see Schedule a Job. 





TIP 


When you name the schedule, consider using a name that is unique and descriptive so you can more easily 


distinguish the schedule from other SQL Server Agent schedules. 








See Also 


Execution of Projects and Packages 


External Resources 


Knowledge Base article, An SSIS package does not run when you call the SSIS package from a SQL Server 
Agent job step, on the Microsoft Web site 


Video, Troubleshooting: Package Execution Using SQL Server Agent (SQL Server Video), in the MSDN 
Library 


Video, How to: Automate Package Execution by Using the SQL Server Agent (SQL Server Video), in the 
MSDN Library 


Technical article, Checking SQL Server Agent jobs using Windows PowerShell, on mssqltips.com 
Technical article, Auto alert for SQL Agent jobs when they are enabled or disabled, on mssqltips.com 


Blog entry, Configuring SQL Agent Jobs to Write to Windows Event Log, on mssq|Itips.com. 


Load-Balancing Packages on Remote Servers by 


Using SQL Server Agent 
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Applies to: Q sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


When many packages have to be run, it is convenient to use other servers that are available. This method of 
using other servers to run packages when the packages are all under the control of one parent package is called 
load balancing. In SQL Server Integration Services, load balancing is a manual procedure that must be 
architected by the owners of the packages. Load balancing is not performed automatically by the servers. Also, 
the packages that are run on the remote servers must be whole packages, not individual tasks in other 
packages. 


Load balancing is useful in the following scenarios: 
e@ Packages can run at the same time. 
e Packages are large and, if run sequentially, can run longer than the time allowed for processing. 


Administrators and architects can determine whether using additional servers for processing would benefit their 
processes. 


Illustration of Load-Balancing 


The following diagram shows a parent package on a server. The parent package contains multiple Execute SQL 
Job Agent tasks. Each task in the parent package calls a SQL Server Agent on a remote server. Those remote 
servers contain SQL Server Agent jobs that include a step that calls a package on that server. 


SSIS Parent 
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calls child packages ) 

using multiple 
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Agent Job tasks ) 

All packages log to one 


server to allow operations 
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The steps required for load balancing in this architecture are not new concepts. Instead, load balancing is 
achieved by using existing concepts and common SSIS objects in a new way. 


Execution of Packages on a Remote Instance by using SQL Server 
Agent 


In the basic architecture for remote package execution, a central package resides on the instance of SQL Server 
that controls the other remote packages. The diagram shows this central package, named the SSIS Parent. The 
instance where this parent package resides controls execution of the SQL Server Agent jobs that run the child 
packages. The child packages are not run according to a fixed schedule controlled by the SQL Server Agent on 
the remote server. Instead, the child packages are started by the SQL Server Agent when called by the parent 


package and are run on the same instance of SQL Server on which the SQL Server Agent resides. 


Before you can run a remote package by using SQL Server Agent, you must configure the parent and child 
packages and set up the SQL Server Agent jobs that control the child packages. The following sections provide 
more information about how to create, configure, run, and maintain packages that run on remote servers. There 


are several steps to this process: 

e Creating the child packages and installing them on remote servers. 

e Creating the SQL Server Agent jobs on the remote instances that will run the packages. 
e Creating the parent package. 


e Determine the logging scenario for the child packages. 


Implementation of Child Packages 


When you implement load balancing using Integration Services, child packages are installed on other servers to 
take advantage of the available CPU or server time. To create and run the child packages requires the following 
steps: 


e Designing the child packages. 

e Moving the packages to the remote server. 

e Creating a SQL Server Agent Job on the remote server that contains a step that runs the child package. 
e Testing and debugging the SQL Server Agent Job and child packages. 


When you design the child packages, the packages have no limitations in their design, and you can put in any 
functionality you desire. However, if the package accesses data, you must ensure that the server that runs the 
package has access to the data. 


To identify the parent package that executes child packages, in SQL Server Data Tools (SSDT) right click the 
package in Solution Explorer and then click Entry-point Package. 


After the child packages have been designed, the next step is to deploy them on the remote servers. 


Moving the Child Package to the Remote Instance 


There are multiple ways to move packages to other servers. The two suggested methods are: 
e Exporting packages by using SQL Server Management Studio. 


e Deploying packages by building a deployment utility for the project that contains the packages you want 
to deploy, and then running the Package Installation Wizard to install the packages to the file system or to 
an instance of SQL Server. For more information, see Legacy Package Deployment (SSIS). 


You must repeat the deployment to each remote server you want to use. 


Creating the SQL Server Agent Jobs 


After the child packages have been deployed to the various servers, create a SQL Server Agent job on each 
server that contains a child package. The SQL Server Agent job contains a step that runs the child package when 
the job agent is called. The SQL Server Agent jobs are not scheduled jobs; they run the child packages only when 
they are called by the parent package. Notification of success or failure of the job back to the parent package 
reflects the success or failure of the SQL Server Agent job and whether it was called successfully, not the success 
or failure of the child package or whether it was executed. 


Debugging the SQL Server Agent Jobs and Child Packages 
You can test the SQL Server Agent jobs and their child packages by using one of the following methods: 


e Running each child package in SSIS Designer, by clicking Debug / Start Without Debugging. 


e Running the individual SQL Server Agent job on the remote computer by using SQL Server Management 
Studio, to make sure that the package runs. 


For information about how to troubleshoot packages that you run from SQL Server Agent jobs, see An SSIS 
package does not run when you call the SSIS package from a SQL Server Agent job step in the Microsoft 
Support Knowledge Base. 


The SQL Server Agent checks subsystem access for a proxy and gives access to the proxy every time the job 
step runs. 


You can create a proxy in SQL Server Management Studio. 


Implementation of the Parent Package 


When load balancing SSIS packages across various servers, the next step after the child packages have been 
created, deployed, and remote SQL Server Agent Jobs created to run them, is to create the parent package. The 
parent package will contain many Execute SQL Server Agent Job tasks, each task responsible for calling a 
different SQL Server Agent job that runs one of the child packages. The Execute SQL Server Agent Job tasks in 
the parent package in turn run the various SQL Server Agent jobs. Each task in the parent package contains 
information such as how to connect to the remote server and what job to run on that server. For more 
information, see Execute SQL Server Agent Job Task. 


To identify the parent package that executes child packages, in SQL Server Data Tools (SSDT) right click the 
package in Solution Explorer and then click Entry-point Package. 


Listing Child Packages 


If you deploy your project that contains a parent package and child package(s) to the Integration Services server, 
you can view a list of the child packages that are executed by the parent package. When you run the parent 
package, an Overview report for the parent package is automatically generated in SQL Server Management 
Studio. The report lists the child packages that were executed by the Execute Package task contained in the 
parent package, as shown in the following image. 











Execution Information 
Operation ID 250144 
Package Package\SSIS Packages\PackageWithParameters.dtsx 
Environment \PackageWithParametersEnvironment2 
Status Succeeded 
Execution Overview 
Filter: Result: All; (3more) 
Result > Duration > PackageName  ~ Task Name > Execution Path 
(sec) 
Succeeded 4.649 ChildPackage.dtsx ChildPackage \PackageWithParameters 
\Execute Package Task 
\ChildPackage 
Succeeded 2.293 ChildPackage.dtsx Web \PackageWithParameters 
Service_ConvertAccerati \Execute Package Task 
on \ChildPackage\Web 
Service ConvertAcceration 
Succeeded 2.356 ChildPackage.dtsx Web \PackageWithParameters 
Service_StockQuote \Execute Package Task 
\ChildPackage\Web 
Service StockQuote 
Succeeded 1237 PackageWithParameterPackageWithParameters \PackageWithParameters 
s/dtsx 
Succeeded 7.504 PackageWithParameter Data Flow Task \PackageWithParameters\Data 
s.dtsx Flow Task 
Succeeded 4836 PackageWithParameter Execute Package Task \PackageWithParameters 
s.dtsx \Execute Package Task 





For information about accessing the Overview report, see Reports for the Integration Services Server. 


Precedence Constraints in the Parent Package 


When you create precedence constraints between the Execute SQL Server Agent Job tasks in the parent 
package, these precedence constraints control only the time that the SQL Server Agent jobs on the remote 
servers are started. Precedence constraints cannot receive information regarding the success or failure of the 


child packages that are run from the steps of the SQL Server Agent jobs. 


This means that success or failure of a child package does not propagate to the parent, because the sole function 
of the Execute SQL Server Agent job in the parent package is to request the SQL Server Agent job to run the 
child package. After the SQL Server Agent job is called successfully, the parent package receives a result of 
Success. 


Failure in this scenario means only that there has been a failure in calling the remote SQL Server Agent Job task. 
One situation where this can occur is when the remote server is down and the agent does not respond. 


However, as long as the agent fires, the parent package has successfully completed its task. 


NOTE 


You can use an Execute SQL Task that contains a Transact-SQL statement of sp_start_job N'package_name’. For more 


information, see sp_start_job (Transact-SQL). 





Debugging Environment 


When testing the parent package, use the debugging environment of the designer by running it using Debug / 
Start Debugging (F5). Alternatively, you can use the command prompt utility, dtexec. For more information, see 
dtexec Utility. 


Logging for Load Balanced Packages on Remote Servers 


It is easier for an administrator to manage the logs for all the child packages that are running on various servers 
when all the child packages use the same log provider and they all write to the same destination. One way that 
you can create a common log file for all child packages is to configure the child packages to log their events to a 
SQL Server log provider. You can configure all the packages to use the same database, the same server, and the 


same instance of the server. 


To view the log files, the administrator only has to log on to a single server to view the log files for all child 
packages. 


For information about how to enable logging in a package, see Integration Services (SSIS) Logging. 


Related Tasks 


SQL Server Agent Jobs for Packages 


Integration Services (SSIS) Scale Out 
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Applies to: Q sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 
SQL Server Integration Services (SSIS) Scale Out provides high-performance execution of SSIS packages by 
distributing package executions across multiple computers. After you set up Scale Out, you can run multiple 
package executions in parallel, in scale-out mode, from SQL Server Management Studio (SSMS). 
Components 


SSIS Scale Out consists of an SSIS Scale Out Master and one or more SSIS Scale Out Workers. 


e The Scale Out Master is responsible for Scale Out management and receives package execution requests 
from users. For more info, see Scale Out Master. 


@ The Scale Out Workers pull execution tasks from the Scale Out Master and run the packages. For more 
info, see Scale Out Worker. 


Configuration options 


You can set up Scale Out in the following configurations: 


e Ona single computer, where a Scale Out Master and a Scale Out Worker run side by side on the same 
computer. 


© On multiple computers, where each Scale Out Worker is on a different computer. 


What you can do 


After you set up Scale Out, you can do the following things: 


e Run multiple packages deployed to the SSISDB catalog in parallel. For more info, see Run packages in 
Scale Out. 


e Manage the Scale Out topology in the Scale Out Manager app. For more info, see Integration Services 
Scale Out Manager. 


Next steps 
e Get started with Integration Services (SSIS) Scale Out on a single computer 


e Walkthrough: Set up Integration Services Scale Out 


Get started with Integration Services (SSIS) Scale 


Out on a single computer 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


This section provides guidance for setting up Integration Services Scale Out in a single-computer environment 


with the default settings. 


1. Install SQL Server features 


In the SQL Server installation wizard, on the Feature Selection page, select the following items: 


e Database Engine Services 


e Integration Services 
°o Scale Out Master 


o Scale Out Worker 


Feature Selection 


Select the Enterprise features to install. 





Product Key 

License Terms 
Global Rules 
Microsoft Update 
Product Updates 
Install Setup Files 
Install Rules 

Feature Selection 
Feature Rules 
Instance Configuration 
Server Configuration 


Database Engine Configuration 


Integration Services Scale Out... 
Integration Services Scale Out... 


Feature Configuration Rules 
Ready to Install 
Installation Progress 


Complete 





e Looking for Reporting Services? 








Download it from the web 























Instance root directory: 


C:\Program Files\Microsoft SOL Server\ 


Features: Feature description: 
The configuration and operation of each a 
| Database Engine Services instance feature of a SOL Server instance is 
(J SQL Server Replication na 
(J Machine Learning Services (In-Database) Prerequisites for selected features: 
OR : 
L Python pays ‘Shell 3.0 or high ; 
(1) Full-Text and Semantic Extractions for Sez vo ein cows Toweronen 22 or maner 
(1 Data Quality Services a ; 
L] PolyBase Query Service for External Data ek ce ene 
L] Analysis Services Drive C: 1233 MB required, 116079 MB 
. eee rs available 
Select All Unselect All 








Shared feature directory: 


C:\Program Files\Microsoft SOL Server\ 








Shared feature directory (x86): C:\Program Files (x86)\Microsoft SOL Server\ 














Feature Selection 


Select the Enterprise features to install. 


Product Key 

License Terms 

Global Rules 

Microsoft Update 

Product Updates 

Install Setup Files 

Install Rules 

Feature Selection 

Feature Rules 

Instance Configuration 

Server Configuration 

Database Engine Configuration 
Integration Services Scale Out ... 
Integration Services Scale Out... 
Feature Configuration Rules 
Ready to Install 

Installation Progress 

Complete 


e Looking for Reporting Services? Download it from the web 


Features: 





L] Python 
(Data Quality Client 
(J Client Tools Connectivity 
Integration Services 
| Scale Out Master 
Scale Out Worker 
(J Client Tools Backwards Compatibility 
(J Client Tools SDK 
(J Documentation Components 
(1 Distributed Replay Controller 


La te ed a ed le 





Feature description: 





The configuration and operation of each 
instance feature of a SOL Server instance is 





Prerequisites for selected features: 





Already installed: 


‘.» Windows PowerShell 3.0 or hiaher 
< 


< 





Disk Space Requirements 











Drive C: 1233 MB required, 116079 MB 
available 





Select All || Unselect All | 





Instance root directory: 


C:\Program Files\Microsoft SOL Server\ 





Shared feature directory: 


C:\Program Files\Microsoft SQL Server\ 





Shared feature directory (x86): 





C:\Program Files (x86)\Microsoft SOL Server\ 











< Back Next > Cancel 


On the Server Configuration page, click Next to accept the default service accounts and startup types. 


On the Database Engine Configuration page, select Mixed Mode and click Add Current User. 


Database Engine Configuration 


Specify Database Engine authentication security mode, administrators, data directories and TempDB settings. 


Product Key 

License Terms 

Global Rules 

Microsoft Update 

Product Updates 

Install Setup Files 

Install Rules 

Feature Selection 

Feature Rules 

Instance Configuration 

Server Configuration 

Database Engine Configuration 
Integration Services Scale Out... 
Feature Configuration Rules 
Ready to Install 

Installation Progress 

Complete 





Server Configuration Data Directories TempDB FILESTREAM 


Specify the authentication mode and administrators for the Database Engine. 





Authentication Mode 
O Windows authentication mode 


@ Mixed Mode (SQL Server authentication and Windows authentication) 


Specify the password for the SQL Server system administrator (sa) account. 








Enter password: 








Confirm password: | eeccceee 
































Specify SQL Server administrators 
MASTERMACHINE\testadmin (testadmin) SOL Server administrators 
have unrestricted access 
to the Database Engine. 
Add Current User Add... || Remove 
< Back Next > Cancel 





On the Integration Services Scale Out Configuration - Master Node and Integration Services Scale 


Out Configuration - Worker Node pages, click Next to accept the default settings for the port and 


certificates. 





Finish the SQL Server installation Wizard. 


2. Install SQL Server Management Studio 


Download and install SQL Server Management Studio (SSMS). 


3. Enable Scale Out 


Open SSMS and connect to the local Sql Server instance. In Object Explorer, right-click Integration Services 
Catalogs and select Create Catalog. 


In the Create Catalog dialog, the option Enable this server as SSIS scale out master is selected by 
default. 


4. Enable a Scale Out Worker 


In SSMS, right-click SSISDB and select Manage Scale Out. 


&) © Integration Services Catalogs 
Es) 


8 SQLS Active Operations 








Create Folder... 





Customized Logging Level 





Start PowerShell 
Database Upgrade 
Execute in Scale Out... 
Manage Scale Out... 





Reports > 





Delete 





Refresh 
Properties 








The Integration Services Scale Out Manager app opens. For more info, see Scale Out Manager. 


To enable a Scale Out Worker, switch to Worker Manager and select the worker you want to enable. The 
workers are disabled by default. Click Enable Worker to enable the selected worker. 


5. Run packages in Scale Out 


Now you're ready to run SSIS packages in Scale Out. For more info, see Run Packages in Integration Services 
(SSIS) Scale Out. 


Next steps 


e Adda Scale Out Worker with Scale Out Manager. 


Walkthrough: Set up Integration Services (SSIS) 


Scale Out 
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Applies to: Q sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Set up Integration Services (SSIS) Scale Out by completing the following tasks. 





TIP 


If you are installing Scale Out on a single computer, install the Scale Out Master and Scale Out Worker features at the 
same time. When you install the features at the same time, the endpoint is automatically generated to connect to Scale 
Out Master. 











e Install Scale Out Master 

e Install Scale Out Worker 

@ Install Scale Out Worker client certificate 

@ Open firewall port 

e Start SQL Server Scale Out Master and Worker service 
e@ Enable Scale Out Master 

e Enable SQL Server Authentication mode 


e Enable Scale Out Worker 


Install Scale Out Master 


To set up Scale Out Master, you have to install Database Engine Services, Integration Services, and the Scale Out 
Master feature of SSIS when you set up SQL Server. 


For info about how to set up Database Engine and Integration Services, see Install SQL Server Database Engine, 
and Install Integration Services. 





NOTE 


To use the default SQL Server authentication account for Scale Out logging, select Mixed Mode for authentication mode 
on the Database Engine Configuration page during Database Engine installation. See Change the account for Scale 


Out logging for more information. 











To install the Scale Out Master feature, use the SQL Server installation wizard or the command prompt. 


Install Scale Out Master with the SQL Server installation wizard 


1. On the Feature Selection page, select Scale Out Master, which is listed under Integration Services. 


Feature Selection 


Select the Evaluation features to install. 
































































































































Product Key Features: Feature description: 
seaprdh ies Shared Features “|| Includes Scale Out Master for Integration 
Global Rules R Server (Standalone) Services Scale Out. 
Microsoft Update (_] Data Quality Client 
Product Updates |_| Client —_ ay — ba 
‘V] Integration Services Prerequisites for selected features: 
ete Scale Out Master al Al Serer 
Install Rules ; ready in: A 
fe ccebetasuail a | “Windows PowerShell 3.0 or higher 

Feature Selection _| Client Tools Backwards Compatibility = | tT z a v 
SORES ["] Client Tools SDK <} i > 

= Documentation Components = 2 

Disk Space Requirements 
rasa errl opal rae Distributed Replay Controller eee 
Server Configuration _] Distributed Replay Client Drive C: 1231 MB required, 111577 MB A 
Database Engine Configuration SQL Client Connectivity SDK v || available 
Integration Services Scale Out... <] = [ [> 
Feature Configuration Rules 
Select All Unselect All 

Ready to Install 
Installation Progress Instance root directory: [C:\Program Files\Microsoft SQL Server\ 
— Shared feature directory: [C:\Program Files\Microsoft SQL Server\ 








Shared feature directory (x86): C:\Program Files (x86)\Microsoft SQL Server\ 











2. On the Server Configuration page, select the account to run SQL Server Integration Services 
Scale Out Master service and select the Startup Type. 


Server Configuration 





















































Specify the service accounts and collation configuration. 
Product Key Service Accounts | Collation 
License Terms 
‘Gigual Raikes Microsoft recommends that you use a separate account for each SQL Server service. 
Microsoft Update Service Account Name Password Startup Type 
Product Updates SQL Server Agent NT Service\SQLSERVERAGE... 
Install Setup Files SQL Server Database Engine NT Service\ MSSQLSERVER 
Install Rules SQL Server Integration Services 14.0 NT Service\MsDtsServer140 
eS aes SQL Server Integration Servi ste.) NT Service\SSISScaleOutMa... 
Feature Rules SQL Server Browser NT AUTHORITY\LOCAL SER... 
Instance Configuration a — — eS 7 
Ss. Coubicneatt [_] Grant Perform Volume Maintenance Task privilege to SQL Server Database Engine Service 
Database Engine Configuration This privilege enables instant file initialization by avoiding zeroing of data pages. This may lead 
iniegiaticnn Services Scale Out to information disclosure by allowing deleted content to be accessed. 
Feature Configuration Rules Click here for details 
Ready to Install 
Installation Progress 
Complete 























3. On the Integration Services Scale Out Master Configuration page, specify the port number that 
Scale Out Master uses to communicate with Scale Out Worker. The default port number is 8391. 


Integration Services Scale Out Configuration - Master Node 


Specify the port number and security certificate for the Scale Out Master node. 


Product Key 

License Terms 

Global Rules 

Product Updates 

Install Setup Files 

Install Rules 

Feature Selection 

Feature Rules 

Server Configuration 
Integration Services Scale Ou... 
Integration Services Scale Out ... 
Feature Configuration Rules 
Ready to Install 

Installation Progress 


Complete 


Specify a port number that the master node uses to communicate with the worker nodes. 





Port Number: 8391 











Select a SSL certificate that is used for the communication between the master node and worker 
nodes in the scale out topology. A default self-signed certificate is created if you choose to create a 
new SSL certificate. 


@ Create a new SSL certificate 


(Ns in the certificate: 


CN=MasterMachine; CN=10.172.4.171| 


O Use an existing SSL certificate 


< Back Next > Cancel 


4. Specify the TLS/SSL certificate used to protect the communication between Scale Out Master and Scale 


Out Worker by doing one of the following. 


e Let the setup process create a default, self-signed TLS/SSL certificate by clicking Create a new SSL 


certificate. The default certificate is installed under Trusted Root Certification Authorities, Local 


Computer. You can specify the CNs in this certificate. The host name of master endpoint should be 


included in CNs. By default, the machine name and ip of Master Node are included. 


e Select an existing TLS/SSL Certificate on the local computer by clicking Use an existing SSL 


certificate and then clicking Browse to select a certificate. The thumbprint of the certificate appears 


in the text box. Clicking Browse displays certificates that are stored in Trusted Root Certification 


Authorities, Local Computer. The certificate you select must be stored here. 


Integration Services Scale Out Configuration - Master Node 


Specify the port number and security certificate for the Scale Out Master node. 














Product Key Specify a port number that the master node uses to communicate with the worker nodes. 
License Terms 

Global Rules Dat hhinbes 9391 

Product Updates 

Install Setup Files 

Install Rules Select a SSL certificate that is used for the communication between the master node and worker 


nodes in the scale out topology. A default self-signed certificate is created if you choose to create a 


SEDGE SEED new SSL certificate. 


Feature Rules 

Server Configuration 

Integration Services Scale Ou... O Create a new SSL certificate 
Integration Services Scale Out... CNs in the certificate: 


Feature Configuration Rules 
CN=MasterMachine; CN=10.172.4.171 














Ready to Install 
Installation Progress @ Use an existing SSL certificate 
Complete 
E12DFB4B41D7D9C32B30514BAC1D81D8385E2D46 Browse... 
< Back Next > Cancel 





5. Finish the SQL Server installation wizard. 


Install Scale Out Master from the command prompt 


Follow the instructions in Install SQL Server from the Command Prompt. Set the parameters for Scale Out 
Master by doing the following things: 


1. Add Is_Master tothe parameter /FEATURES 


2. Configure Scale Out Master by specifying the following parameters and their values: 


@ /ISMASTERSVCACCOUNT 

@ /ISMASTERSVCPASSWORD 

@ /ISMASTERSVCSTARTUPTYPE 
@ /ISMASTERSVCPORT 


@ /ISMasterSvcssLCertcn (optional) 


@ /ISMASTERSVCTHUMBPRINT (optional) 





NOTE 


If Scale Out Master is not installed together with Database Engine, and the Database Engine instance is a named 
instance, you have to configure SqlServerName in the Scale Out Master service configuration file after 


installation. For more info, see Scale Out Master. 








Install Scale Out Worker 


To set up Scale Out Worker, you have to install Integration Services and its Scale Out Worker feature in SQL 
Server setup. 


To install the Scale Out Worker feature, use the SQL Server installation wizard or the command prompt. 


Install Scale Out Worker with the SQL Server installation wizard 


1. On the Feature Selection page, select Scale Out Worker, which is listed under Integration Services. 


Feature Selection 


Select the Evaluation features to install. 









































































































































Product Key Features: Feature description: 
eagSa Shared Features * || Includes Scale Out Worker for Integration A 
Global Rules R Server (Standalone) Services Scale Out. 
Microsoft Update Data Quality Client 
Product Updates Client Tools Connectivity — ha 
[¥| Integration Services Prerequisites for selected features: 
Install Setup Files 
Scale Out Master = 
Install Rules one unin a : 
([eee Ss — ‘» Microsoft NET Framework 4.5 
Feature Selection Client Tools Backwards Compatibility =/|7 is is v 
Feature Rules Client Tools SDK < mM > 
: Documentation Components . . 
Disk Space Requirements 
— aa aN Distributed Replay Controller i 
Integration Services Scale Out ... Distributed Replay Client Drive C: 307 MB required, 111567 MB available | 
Feature Configuration Rules SQL Client Connectivity SDK v 
Ready to Install <| Mm > v 
Installation Progress 
Select All Unselect All 

Complete 

Instance root directory: C:\Program Files\Microsoft SQL Server\ 

Shared feature directory: C:\Program Files\Microsoft SQL Server\ a] 

Shared feature directory (x86): C:\Program Files (x86)\Microsoft SQL Server\ el 














< Back Next > Cancel 





2. On the Server Configuration page, select the account to run SQL Server Integration Services 
Scale Out Worker service and select the Startup Type. 


Server Configuration 


Specify the service accounts and collation configuration. 





Product Key Service Accounts 
License Terms ; 
Global Rules Microsoft recommends that you use a separate account for each SQL Server service. 











Microsoft Update Service Account Name Passw... Startup Type 
Product Updates SQL Server Integration Services 14.0 NT Service\MsDtsServer140 |Automatic |v 
Install Setup Files SOM alee ee] ee NT Service\SSISScaleOutWor... [Automatic || 
Install Rules 

Feature Selection 

Feature Rules 

Server Configuration 
Integration Services Scale Out... 
Feature Configuration Rules 
Ready to Install 

Installation Progress 














Complete 

















3. On the Integration Services Scale Out Worker Configuration page, specify the endpoint to connect 
to Scale Out Master. 


e For asingle-computer environment, the endpoint is automatically generated when Scale Out 
Master and Scale Out Worker are installed at the same time. 


e Fora multiple-computer environment, the endpoint consists of the name or IP of the computer 


with Scale Out Master installed and the port number specified during the Scale Out Master 
installation. 


Integration Services Scale Out Configuration - Worker Node 


Specify the master node endpoint and security certificate used by the Scale Out Worker node. 





Product Key Provide the master node endpoint which the worker node needs to connect to (e.g. https:// 
(Roses [MasterNodeMachineName]:[Port]): 
Global Rules 
Product Updates https://MasterMachine:8391| 
Install Setup Files 
Install Rules 

- Configure the SSL certificate of master node to trust in this machine. The master's SSL certificate 
Feature Selection needs to be trusted on this worker node for establishing the connection between worker and master. 
Feature Rules This is optional if your master certificate has already been trusted, i.e. it's issued by a trusted CA 
Server Configuration (Certification Authority) on this machine, or the master is installed on the same machine. Otherwise, 

; E please provide the master’s client SSL certificate, i.e. the certificate is created and self-signed by 

Integration Services Scale Out... yourself and the master is not on the same machine. 
Integration Services Scale Ou... 
Feature Configuration Rules 
Ready to Install Browse... 











Installation Progress 
Complete 


< Back Next > Cancel 


NOTE 


You can also skip Worker configuration at this point and associate the Scale Out Worker with the Scale Out 


Master by using Scale Out Manager after installation. 





4. For amultiple-computer environment, specify the client TLS/SSL certificate that is used to validate 
Scale Out Master. For a single-computer environment, you don't have to specify a client TLS/SSL 


certificate. 


Click Browse to find the certificate file (*.cer). To use the default TLS/SSL certificate, select the 
ssISScaleOutMaster.cer file located under \<drive\>:\Program Files\Microsoft SQL Server\140\DTS\Binn 


on the computer on which Scale Out Master is installed. 


Integration Services Scale Out Configuration - Worker Node 


Specify the master node endpoint and security certificate used by the Scale Out Worker node. 














Product Key Provide the master node endpoint which the worker node needs to connect to (e.g. https:// 
License Terms [MasterNodeMachineName];[Port]): 

Global Rules 

Product Updates https://MasterMachine:8391 

Install Setup Files 

Install Rules 


Configure the SSL certificate of master node to trust in this machine. The master’s SSL certificate 
needs to be trusted on this worker node for establishing the connection between worker and master. 
Feature Rules This is optional if your master certificate has already been trusted, i.e. it’s issued by a trusted CA 
(Certification Authority) on this machine, or the master is installed on the same machine. Otherwise, 


Feature Selection 


Server Configuration : 5 z z = = : 

; ‘ please provide the master's client SSL certificate, i.e. the certificate is created and self-signed by 
Integration Services Scale Out... yourself and the master is not on the same machine. 
Integration Services Scale Ou... 


Feature Configuration Rules 


Ready to Install C:\folder\SSISScaleOutMaster.cer Browse... 


Installation Progress 


Complete 


< Back Next > Cancel 


NOTE 


When the TLS/SSL certificate used by Scale Out Master is self-signed, a corresponding client TLS/SSL certificate has 
to be installed on the computer with Scale Out Worker. If you provide the file path for the client TLS/SSL 
Certificate on the Integration Services Scale Out Worker Configuration page, the certificate will be 


installed automatically; otherwise, you have to install the certificate manually later. 








5. Finish the SQL Server installation wizard. 


Install Scale Out Worker from the command prompt 


Follow the instructions in Install SQL Server from the Command Prompt. Set the parameters for Scale Out 
Worker by doing the following things: 


1. Add IS_Worker to the parameter /FEATURES . 
2. Configure Scale Out Worker specifying the following parameters and their values: 


@ /ISWORKERSVCACCOUNT 
@ /ISWORKERSVCPASSWORD 

@ /ISWORKERSVCSTARTUPTYPE 

@ /ISWORKERSVCMASTER (optional) 


@ /ISWORKERSVCCERT (optional) 


Install Scale Out Worker client certificate 


During the installation of Scale Out Worker, a worker certificate is automatically created and installed on the 
computer. Also, a corresponding client certificate, SSISScaleOutWorker.cer, is installed under 

\<drive\>:\Program Files\Microsoft SQL Server\14@\DTS\Binn . For Scale Out Master to authenticate the Scale Out 
Worker, you have to add this client certificate to the Root store of the local computer with Scale Out Master. 


To add the client certificate to the Root store, double-click the .cer file and then click Install Certificate in the 


Certificate dialog box. The Certificate Import Wizard opens. 


Open firewall port 


On the Scale Out Master computer, open the port specified during the Scale Out Master installation and the port 
for SQL Server (1433, by default) in the Windows Firewall. 





NOTE 


After you open the firewall port, you also have to restart the Scale Out Worker service. 





Start SQL Server Scale Out Master and Worker services 
If you didn't set the startup type of the services to Automatic during installation, start the following services: 
e SQL Server Integration Services Scale Out Master 14.0 (SSISScaleOutMaster140) 


e SQL Server Integration Services Scale Out Worker 14.0 (SSISScaleOutWorker140) 


Enable Scale Out Master 


When you create the SSISDB catalog in SQL Server Management Studio, select Enable this server as SSIS 
scale out master in the Create Catalog dialog box. 


After the catalog is created, you can enable Scale Out Master with Scale Out Manager. 


Enable SQL Server Authentication mode 


If you didn't enable SQL Server authentication during the Database Engine installation, enable SQL Server 
authentication mode on the SQL Server instance that hosts the SSISDB catalog. 


Package execution is not blocked when SQL Server authentication is disabled. However, the execution log cannot 
write to the SSISDB database. 


Enable Scale Out Worker 


You can enable Scale Out Worker with Scale Out Manager, which provides a graphical user interface, or with a 
stored procedure. 


To enable a Scale Out Worker with a stored procedure, execute the [catalog]. [enable_worker_agent] stored 
procedure with WorkerAgentld as the parameter. 


Get the WorkerAgentld value from the [catalog].[worker_agents] view in SSISDB, after Scale Out Worker 
registers with Scale Out Master. Registration takes several minutes after the Scale Out Master and Worker 


services are started. 


Example 


The following example enables the Scale Out Worker on computerA . 


SELECT WorkerAgentId, MachineName FROM [catalog].[worker_agents] 
GO 

=  RESUI tices 

-- WorkerAgentId MachineName -- 

-- 6583054A-E915-4C2A-80E4-C765E79EF61D computerA == 


EXEC [catalog].[enable_worker_agent] '6583054A-E£915-4C2A-80E4-C765E79EF61D' 
GO 


Next steps 


e Run Packages in Integration Services (SSIS) Scale Out. 


Run packages in Integration Services (SSIS) Scale 


Out 


SV ey ACP acme aalialeicstsmcona-t-le mm sfelim@)al lars) 





Applies to: Q sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


After you deploy packages to the Integration Services server, you can run them in Scale Out by using one of the 
following methods: 


e Execute Package in Scale Out dialog box 
e Stored procedures 


e SQL Server Agent jobs 


Run packages with the Execute Package in Scale Out dialog box 


1. Open the Execute Package In Scale Out dialog box. 


In SQL Server Management Studio, connect to the Integration Services server. In Object Explorer, expand 
the tree to display the nodes under Integration Services Catalogs. Right-click the SSISDB node or the 
project or the package you want to run, and then click Execute in Scale Out. 


2. Select packages and set the options. 


On the Package Selection page, select one or more packages to run. Set the environment, parameters, 
connection managers, and advanced options for each package. Click a package to set these options. 


On the Advanced tab, set a Scale Out option called Retry count to specify the number of times a 
package execution will retry if it fails. 





NOTE 


The Dump on errors option only works when the account running Scale Out Worker service is an administrator 
on the local computer. 








3. Select worker computers. 


On the Machine Selection page, select the Scale Out Worker computers to run the packages. By default, 
any computer is allowed to run the packages. 





NOTE 


The packages are executed with the credentials of the user accounts of the Scale Out Worker services. Review 
these credentials on the Machine Selection page. By default, the account is 
NT Service\SSISScaleOutWorker14@ . 








WARNING 


Package executions triggered by different users on the same worker run with the same credentials. There is no 
security boundary between or among them. 








4. Run the packages and view reports. 


Click OK to start the package executions. To view the execution report for a package, right-click the 
package in Object Explorer, click Reports, click All Executions, and find the execution. 


Run packages with stored procedures 


il; 


Create executions. 


Call [catalog].[create_execution] for each package. Set the parameter @runinscaleout to True . If not 
all Scale Out Worker computers are allowed to run the package, set the parameter @useanyworker to 

False . For more info about this stored procedure and the @useanyworker parameter, see 
catalog.create_execution. 


. Set execution parameters. 


Call [catalog].[set_execution_parameter_value] for each execution. 


. Set the Scale Out Workers. 


Call [catalog]. [add_execution_worker] . If all computers are allowed to run the package, you don't have to 
call this stored procedure. 


4. Start the executions. 
Call [catalog]. [start_execution] . Set the parameter @retry_count to set the number of times a 
package execution will retry if it fails. 

Example 


The following example runs two packages, packagel.dtsx and package2.dtsx , in Scale Out with one Scale Out 
Worker. 


Declare @execution_id bigint 

EXEC [SSISDB].[catalog].[create_execution] @package_name=N'packagel.dtsx', @execution_id=@execution_id 
OUTPUT, @folder_name=N'folder1i', @project_name=N'project1', @use32bitruntime=False, @reference_id=Null, 
@useanyworker=False, @runinscaleout=True 

Select @execution_id 

DECLARE @var@ smallint = 1 

EXEC [SSISDB].[catalog].[set_execution_parameter_value] @execution_id, @object_type=50, 
@parameter_name=N'LOGGING_LEVEL', @parameter_value=@vara@ 

EXEC [SSISDB].[catalog].[add_execution_worker] @execution_id, @workeragent_id=N'64c@20e2-f819-4c2d-a22Ff - 
efb31a91e70a' 

EXEC [SSISDB].[catalog].[start_execution] @execution_id, @retry_count=0 

GO 


Declare @execution_id bigint 

EXEC [SSISDB].[catalog].[create_execution] @package_name=N'package2.dtsx', @execution_id=@execution_id 
OUTPUT, @folder_name=N'folder2', @project_name=N'project2', @use32bitruntime=False, @reference_id=Null, 
@useanyworker=False, @runinscaleout=True 

Select @execution_id 

DECLARE @var@ smallint = 1 

EXEC [SSISDB].[catalog].[set_execution_parameter_value] @execution_id, @object_type=50, 
@parameter_name=N'LOGGING_LEVEL', @parameter_value=@var@ 

EXEC [SSISDB].[catalog].[add_execution_worker] @execution_id, @workeragent_id=N'64c@20e2-f819-4c2d-a22Ff - 
efb31a91e70a' 

EXEC [SSISDB].[catalog].[start_execution] @execution_id, @retry_count=0 

GO 


Permissions 


To run packages in Scale Out, you have to have one the following permissions: 


e Membership in the ssis_admin database role 
e Membership in the ssis_cluster_executor database role 


e Membership in the sysadmin server role 


Set default execution mode 


To set the default execution mode for packages to Scale Out, do the following things: 
1. In SSMS, in Object Explorer, right-click the SSISDB node and select Properties. 


2. In the Catalog Properties dialog box, set Server-wide Default execution mode to Scale Out. 


After you set this default execution mode, you no longer have to specify the @runinscaleout parameter when 
you call the [catalog].[create_execution] stored procedure. Packages are run in Scale Out automatically. 


{J Script ~ | @ Help 





SSISDB 
True 
Scale Out 
5 
Schema Build 14.0.800.36 
Encryption Algorithm Name AES_256 
Connection Operations Log 
git, CSVM43935342TA Goan Loge Pestodically 


[REDMOND\salci01] Current Number of Records 
Current Size of Operation Log (KB) 


Retention Period (days) 
Server-wide Default Logging Level 
View connection properties 4 Project Versions 


a a eS ee ee ee eee sale 
Progress Server-wide Default execution mode 
The default server-wide execution mode. When the value is Server, package is executed in server. 
When the value is Scale Out, package is executed in Scale Out Worker Agent. 














To switch the default execution mode back so that packages no longer run by default in Scale Out mode, set 
Server-wide Default execution mode to Server. 


Run package in SQL Server Agent job 


In a SQL Server Agent job, you can run an SSIS package as one step of the job. To run the package in Scale Out, 
set the default execution mode to Scale Out. After you set the default execution mode to Scale Out, packages 
in SQL Server Agent jobs run in Scale Out mode. 


NOTE 


You can't stop Scale Out package execution by canceling the SQL Server Agent job. To stop Scale Out execution, we 


recommend that you use the catalog.stop_operation stored procedure or use the Active Operations pane. 





Next steps 


e Troubleshoot Scale Out 


Add a Scale Out Worker with Scale Out Manager 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Integration Services Scale Out Manager simplifies the process of adding a Scale Out Worker to your existing 
Scale Out environment. 


Follow these steps to add a Scale Out Worker to your Scale Out topology: 


1. Install Scale Out Worker 


In the SQL Server installation wizard, select Integration Services and Scale Out Worker on the Feature 
Selection page. 


Feature Selection 


Select the Evaluation features to install. 





















































Product Key Features: Feature description: 
Exesee toe Shared Features * || Includes Scale Out Worker for Integration A 
Global Rules __| R Server (Standalone) Services Scale Out. 
Microsoft Update LU Data Quality Client = 
Product Updates |_| Client Tools Connectivity — 
Vv) Integration Services Prerequisites for selected features: 
Install Setup Files (1 Scale Out Master 
Install Rules fd] Scale Out Work Already installed: A 
_, Rea lad = ‘.- Microsoft NET Framework 4,5 
Feature Selection |_| Client Tools Backwards Compatibility =||t : ai v 
Fentiwe Rules |] Client Tools SDK < m > 
E Documentation Components : : 
= Disk Space Requirements 
meatal a |__| Distributed Replay Controller Ld Pua 
Integration Services Scale Out ... (J Distributed Replay Client Drive C: 307 MB required, 111567 MB available 
Feature Configuration Rules |] SQL Client Connectivity SDK v 
Ready to Install <| = 7 a 








Sera 
Complete 








Instance root directory: (C:\Program Files\Microsoft SQL Server\ 
Shared feature directory: C:\Program Files\Microsoft SOL Server\ eal 
Shared feature directory (x86): [C:\Program Files (x86)\Microsoft SQL Server\ | = 














On the Integration Services Scale Out Configuration - Worker Node page, you can click Next to skip 
configuration at this time and use Scale Out Manager to do the configuration after installation. 


Finish the installation wizard. 


2. Open the firewall on the Scale Out Master computer 


Open the port specified during the Scale Out Master installation (8391, by default), and the port for SQL Server 
(1433, by default), in the Windows Firewall on the Scale Out Master computer. 


3. Add a Scale Out Worker with Scale Out Manager 


Run SQL Server Management Studio as administrator and connect to the SQL Server instance of Scale Out 


Master. 
In Object Explorer, right-click SSISDB and select Manage Scale Out. 
&) © Integration Services Catalogs 


Active Operations 





Create Folder... 





Customized Logging Level 





Start PowerShell 
Database Upgrade 
Execute in Scale Out... 
Manage Scale Out... 











Properties 





In the Scale Out Manager dialog box, switch to Worker Manager. Select + and follow the instructions in the 
Connect Worker dialog box. 


Next steps 


For more info, see Scale Out Manager. 


Integration Services (SSIS) Scale Out Master 
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Applies to: Q@ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


The Scale Out Master manages the Scale Out system through the SSISDB Catalog and the Scale Out Master 
service. 


The SSISDB Catalog stores all the information for Scale Out Workers, packages, and executions. It provides the 
interface to enable a Scale Out Worker and execute packages in Scale Out. For more information, see 
Walkthrough: Set up Integration Services Scale Out and Run Packages in Integration Services. 


The Scale Out Master service is a Windows service that is responsible for the communication with Scale Out 
Workers. It returns the status of package executions on Scale Out Workers over HTTPS and operates on the data 
in SSISDB. 


Scale Out views and stored procedures in SSISDB 


Views 
e [catalog].[master_properties] 


e [catalog].[worker_agents] 


Stored procedures 
e For managing Scale Out Workers: 
o [catalog].[disable_worker_agent] 


o [catalog].[enable_worker_agent] 


e For running packages in Scale Out: 


o [catalog].[create_execution] 
o [catalog].[add_execution_worker] 


o [catalog].[start_execution] 


Configure the Scale Out Master service 


You configure the Scale Out Master service by using the 
<drive>:\Program Files\Microsoft SQL Server\140\DTS\Binn\MasterSettings. config file. You have to restart the 


service after updating the configuration file. 
CONFIGURATION DESCRIPTION DEFAULT VALUE 


PortNumber The network port number used to 8391 
communicate with a Scale Out Worker. 


SSLCertThumbprint The thumbprint of the TLS/SSL The thumbprint of the TLS/SSL 
certificate used to protect the certificate specified during the Scale 
communication with a Scale Out Out Master installation 


Worker. 


CONFIGURATION 


SqlServerName 


CleanupCompletedJobsIntervallnMs 


DealWithExpiredTasksIntervallnMs 


MasterHeartbeatIntervallnMs 


SqlConnectionTimeoutlnSecs 


DESCRIPTION 


The name of the SQL Server that 
contains the SSISDB catalog. For 
example, ServerName\InstanceName. 


The interval for cleaning up completed 
execution jobs, in milliseconds. 


The interval for dealing with expired 
execution jobs, in milliseconds. 


The interval for the Scale Out Master 
heartbeat, in milliseconds. This 
property specifies the interval at which 
Scale Out Master updates its online 
status in the SSISDB catalog. 


The SQL connection timeout in 
seconds when connecting to SSISDB. 


View the Scale Out Master service log 


The Scale Out Master service log file is located in the 


<drive>: \Users\[account ]\AppData\Local\SSIS\ScaleOut\Master folder. 


DEFAULT VALUE 


The name of the SQL Server that is 


installed with the Scale Out Master. 


43200000 


300000 


30000 


15 


The /account] parameter refers to the account running the Scale Out Master service. By default, this account is 


ssTISScaleOutMaster14®@ . 


Next steps 


Integration Services (SSIS) Scale Out Worker 


Integration Services (SSIS) Scale Out Worker 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


The Scale Out Worker runs the Scale Out Worker service to pull execution tasks from Scale Out Master. Then the 


worker runs the packages locally with IsserverExec.exe . 


Configure the Scale Out Worker service 


You can configure the Scale Out Worker service by using the 


\<drive\>:\Program Files\Microsoft SQL Server\140\DTS\Binn\WorkerSettings. config file. You have to restart the 


service after updating the configuration file. 


CONFIGURATION 


DisplayName 


Description 


MasterEndpoint 


MasterHttpsCertThumbprint 


WorkerHttpsCertThumbprint 


StoreLocation 


StoreName 


AgentHeartbeatinterval 


TaskHeartbeatInterval 


HeartbeatErrorTolerance 


DESCRIPTION 


The display name of the Scale Out 
Worker. NOT in use in SQL Server 
2017. 


The description of the Scale Out 
Worker. NOT in use in SQL Server 
2017. 


The endpoint to connect to Scale Out 
Master. 


The thumbprint of the client TLS/SSL 
certificate used to authenticate Scale 
Out Master 


The thumbprint of the certificate for 
Scale Out Master used to authenticate 
the Scale Out Worker. 


The store location of worker certificate. 


The store name that worker certificate 
is in. 


The interval of the Scale Out Worker 
heartbeat. 


The interval of the Scale Out Worker 
reporting task state. 


After this time period from last 
successful task heartbeat, the task is 
terminated if error response of 
heartbeat is received. 


DEFAULT VALUE 


Machine name 


Empty 


The endpoint set during the Scale Out 
Worker installation 


The thumbprint of the client certificate 
specified during the Scale Out Worker 
installation. 


The thumbprint of a certificate created 
and installed automatically during the 
Scale Out Worker installation 


LocalMachine 


My 


00:01:00 


00:00:10 


00:10:00 


CONFIGURATION 


TaskRequestMaxCPU 


TaskRequestMinMemory 


MaxTaskCount 


Leaselnterval 


TasksRootFolder 


TaskLogLevel 


TaskLogSegment 


TaskLogEnabled 


ExecutionLogCacheFolder 


ExecutionLogMaxBufferLogCount 


ExecutionLogMaxlInMemoryBufferCou 
nt 


ExecutionLogRetryCount 


ExecutionLogRetryTimeout 


DESCRIPTION 


The upper limit of CPU for Scale Out 
Worker to request tasks. 


The lower limit of memory in MB for 
Scale Out Worker to request tasks. 


The max number of tasks the Scale 
Out Worker can hold. 


The lease interval of a task holding by 
the Scale Out Worker. 


The folder of task logs. If the value is 
empty, the 
\<drive\>:\Users\ 


DEFAULT VALUE 


70.0 


100.0 


10 


00:01:00 


Empty 


[account ]\AppData\Local\SSIS\Cluster\Tasks 


folder path is used. [account] is the 
account running Scale Out Worker 
service. By default, the account is 
SSISScaleOutWorker140. 


The task log level of the Scale Out 
Worker. (Verbose 0x01, Information 
0x02, Warning 0x04, Error 0x08, 
Progress 0x10, CriticalError 0x20, Audit 
0x40) 


The time span of a task log file. 


Specifies whether the task log is 
enabled. 


The folder used to cache package 
execution log. If the value is empty, the 
\<drive\>:\Users\ 


126 (Information, Warning, Error, 
Progress, CriticalError, Audit) 


00:00:00 


true 


Empty 


[account ]\AppData\Local\SSIS\Cluster\Agent\ELogCache 


folder path is used. [account] is the 
account running Scale Out Worker 
service. By default, the account is 
SSISScaleOutWorker140. 


The max number of execution logs 
cached, in one execution log buffer in 
memory. 


The max number of execution log 
buffers in memory for execution logs. 


The retry count if execution logging 
fails. 


The retry timeout if execution logging 
fails. i\lf ExecutionLogRetryTimeout is 
reached, ExecutionLogRetryCount is 
ignored. 


10000 


10 


7.00:00:00 (7 days) 


CONFIGURATION DESCRIPTION DEFAULT VALUE 


Agentid Worker agent ID of the Scale Out Generated automatically 
Worker 


View the Scale Out Worker log 


The log file of the Scale Out Worker service is in the 
\<drive\>:\Users\\[account ]\AppData\Local\SSIS\ScaleOut\Agent folder. 


The log location of each individual task is configured in the wWorkerSettings.config file in the TasksRootFolder . If 


a value is not specified, the log is in the \<drive\>:\Users\\[account ]\AppData\Local\SSIS\ScaleOut\Tasks folder. 
The /account] parameter is the account running the Scale Out Worker service. By default, the account is 


SsTSScaleOutWorker14®@ . 


Next steps 


Integration Services (SSIS) Scale Out Master 


Integration Services Scale Out Manager 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Scale Out Manager is a management tool that lets you manage your entire SSIS Scale Out topology from a 
single app. It removes the burden of doing management tasks and running Transact-SQL commands on multiple 
computers. 


Open Scale Out Manager 
There are two ways to open Scale Out Manager. 


1. Open Scale Out Manager from SQL Server Management Studio 
Open SQL Server Management Studio (SSMS) and connect to the SQL Server instance of Scale Out Master. 


In Object Explorer, right-click SSISDB, and select Manage Scale Out. 





=| © Integration Services Catalogs 

















Active Operations 





Create Folder... 





Customized Logging Level 





Start PowerShell 
Database Upgrade 
Execute in Scale Out... 
Manage Scale Out... 





Reports » 





Delete 





Refresh 


Properties 








NOTE 


We recommend running SSMS as an administrator, since some Scale Out management operations, such as adding a Scale 


Out Worker, require administrative privilege. 





2. Open Scale Out Manager by running ManagementTool.exe 
Locate ManagementTool.exe under 
*SystemDrivez%\Program Files (x86)\Microsoft SQL Server\15@\DTS\Binn\Management . Right-click 


ManagementtTool.exe and select Run as administrator. 


After Scale Out Manager opens, enter the SQL Server instance name of Scale Out Master and connect to it to 
manage your Scale Out environment. 





(5 SOL Server Integration Services x 


Connect to Scale Out Master 


Severna: 
M] Encryption Connection 
(J Trust Server Certificate 


Connect 








Tasks available in Scale Out Manager 


In Scale Out Manager, you can do the following things: 


Enable Scale Out 


After connecting to SQL Server, if Scale Out is not enabled, you can select Enable to enable it. 


Dashboard 


Dashboard ———_ 
Scale Out has not been enabled. Enable 


Workers 





View Scale Out Master status 


The status of Scale Out Master is shown on the Dashboard page. 


Dashboard 


Dashboard Ovewmiew 


Endpoint: https://aevm2388701-gu.sys-sqlsvr.local:8391 


Workers 


Machine IP: 10.217.208.136 
Last online time: 5/24/2018 12:55:22 AM -07:00 


Workers 


Online: 1 





View Scale Out Worker status 


The status of Scale Out Worker is shown on the Worker Manager page. You can select each worker to see the 
individual status. 

















Details 
ROPE .112200701.c0 SS 
Machine Name: [AEVM2388701-GU Last online time: [5/24/2018 1:20:28 AM -07.00 
Workers Account: [NT Service\SSISScaleOutWorker150 Enable status: [Enabled 
4 | 
Running Packages 
Execution ID Package Path Start time 














Add a Scale Out Worker 
To add a Scale Out Worker, select + at the bottom of the Scale Out Worker list. 
Enter the computer name of the Scale Out Worker you want to add and click Validate. The Scale Out Manager 


checks whether the current user has access to the certificate stores on the Scale Out Master and Scale Out 
Worker computers 


Connect worker node to the current master 
Worker name: | 











If validation succeeds, Scale Out Manager tries to read the worker server configuration file and get the 
certificate thumbprint of the worker. For more info, see Scale Out Worker. If Scale Out Manager can't read the 
worker service configuration file, there are two alternative ways for you to provide the worker certificate. 


e You can enter the thumbprint of worker certificate directly. 


Connect worker node to the current master 
Worker name: 

Validation Waming: 

Failed to read worker setting from path ‘C:\Program Files\Microsoft SQL 


Server\150\DTS\Binn\WorkerSettings.config’ on the worker node. Please 
choose an altemative way to provide worker certificate. 


Provide worker certificate thumbprint: 
@ Thumbprint of worker certificate 
© File path of worker cert 





@ Or, you can provide the certificate file. 


Connect worker node to the current master 
Worker name: 

Validation Waming: 

Failed to read worker setting from path ‘C:\Program Files\Microsoft SQL 


Server\150\DTS\Binn\WorkerSettings.config’ on the worker node. Please 
choose an altemative way to provide worker certificate. 


Provide worker certificate thumbprint: 


© Thumbprint of worker certificate 
@) File path of worker cert 





After gathering information, Scale Out Manager describes the actions to be performed. Typically, these actions 
include installing the certificate, updating the worker service configuration file, and restarting the worker 


service. 


Connect worker node to the current master 
Worker name: 127.0.0.1 


The following actions will be performed to connect the worker 
node to the master. Please click "OK" to proceed. 


* Master service public certificate will be installed in the trust certificate 
store of worker machine. 
* Worker service public certificate will be installed in the trust certificate 


store of master machine. 

* Update the Endpoint of worker setting with 

value ‘https://aevm2388701-gu.sys-sqlsvrlocal:8391 

« Update the HttpsCert Thumbpnrint of worker setting with value: 
99BC5B41D3887749C101ESA674F7B41217B95CD0 

* Restart Scale Out Worker service. 


{_] Confirm to perform all the actions. 





In case the worker setting is not accessible, you have to update it manually and restart the worker service. 


Connect worker node to the current master 
Worker name: abvm2723930-gu 


Add Worker has not finished because of the following error(s) 
or waming{(s)- 


* Master service public certificate is installed in the trust certificate store 
of worker machine. 

* Worker service public certificate is installed in the trust certificate store 
of master machine. 

* We cannot access the worker setting file. You may need to update 
manually with new values and then restart worker service. 





Select the Confirm checkbox and then select OK to start adding a Scale Out Worker. 


Delete a Scale Out Worker 

To delete a Scale Out Worker, select the Scale Out Worker and then select - at the bottom of the Scale Out 
Worker list. 

Enable or disable a Scale Out Worker 


To enable or disable a Scale Out Worker, select the Scale Out Worker and then select Enable Worker or 
Disable Worker. If the worker is not offline, the status of the worker displayed in Scale Out Manager changes 
accordingly. 


Edit a Scale Out Worker description 


To edit the description of a Scale Out Worker, select the Scale Out Worker and then select Edit. After you finish 
editing the description, select Save. 


Details 

















ROE 12206701.00 
Machine Name: fAEvMz3e8701GU—s Last online time: [5/24/2018 1:2028AM-07:00 | 
Workers Account: [NT Service\SSISScaleOutWorker150 Enable status: Enabled 
a 
Running Packages 
Execution ID Package Path Start time 














Next steps 


For more info, see the following articles: 


e Integration Services (SSIS) Scale Out Master 


e Integration Services (SSIS) Scale Out Worker 
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When you run SSIS packages in Scale Out, the event messages are logged in the SSISDB database with an auto- 
created user account named ##MS_SSISLogDBWorkerAgentLogin##. The login for this user uses SQL 
Server authentication. 


If you want to change the account used for Scale Out logging, do the following things: 





NOTE 


If you use a Windows user account for logging, use the same account as the account that runs the Scale Out Worker 
service. Otherwise, the login to SQL Server fails. 





1. Create a user for SSISDB 


For instructions about how to create a database user, see Create a Database User. 


2. Add the user to the database role ssis_cluster_worker 


For instructions about how to join a database role, see Join a Role. 


3. Update the logging information in SSISDB 


Call the stored procedure [catalog]. [update_logdb_info] with the SQL Server name and connection string as 


parameters, as shown in the following example: 


SET @serverName = CONVERT(sysname, SERVERPROPERTY( 'servername' ) ) 

SET @connectionString = ‘Data Source=' + @serverName + ';Initial Catalog=SSISDB; Integrated Security=SSPT; ' 
EXEC [internal].[update_logdb_info] @serverName, @connectionString 

GO 


4. Restart the Scale Out Worker service 


Restart the Scale Out Worker service to make the change effective. 


Next steps 


e Integration Services Scale Out Manager 





Manage certificates for SQL Server Integration 


Services Scale Out 
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To secure the communication between Scale Out Master and Scale Out Workers, SSIS Scale Out uses two 
certificates - one for the Master and one for the Workers. 


Scale Out Master certificate 
In most cases, the Scale Out Master certificate is configured during the installation of Scale Out Master. 


In the Integration Services Scale Out Configuration - Master Node page of the SQL Server Installation 
wizard, you can choose to create a new self-signed TLS/SSL certificate or use an existing TLS/SSL certificate. 


Integration Services Scale Out Configuration - Master Node 


Specify the port number and security certificate for the Scale Out Master node. 





Product Key Specify a port number that the master node uses to communicate with the worker nodes. 

License Terms 

Global Rules Port Number: 8391 

Product Updates 

Install Setup Files 

Install Rules Select a SSL certificate that is used for the communication between the master node and worker 

F Selecti nodes in the scale out topology. A default self-signed certificate is created if you choose to create a 
seen aca new SSL certificate. 

Feature Rules 

Server Configuration 

Integration Services Scale Ou. @ Create 2 new SSL certificate 

Integration Services Scale Out... CNs in the certificate: 


Feature Configuration Rules 


CN=MasterMachine; CN=10.172.4.171| 
Ready to Install 


Installation Progress O Use an existing SSL certificate 
Complete 





< Back | Next> Cancel 








New certificate. If you don't have special requirements for certificates, you can choose to create a new self- 
signed TLS/SSL certificate. You can further specify the CNs in the certificate. Make sure the host name of the 
master endpoint to be used later by Scale Out Workers is included in the CNs. By default, the computer name 
and IP address of the master node are included. 


Existing certificate. If you choose to use an existing certificate, click Browse to select a TLS/SSL certificate 
from the Root certificate store of the local computer. 
Change the Scale Out Master certificate 


You may want to change your Scale Out Master certificate due to certificate expiration or for other reasons. To 
change the Scale Out Master certificate, do the following things: 


1. Create a TLS/SSL certificate. 


Create and install a new TLS/SSL certificate on the Master node with the following command: 


MakeCert.exe -n CN={master endpoint host} SSISScaleOutMaster.cer -r -ss Root -sr LocalMachine -a shal 
For example: 


MakeCert.exe -n CN=MasterMachine SSISScaleOutMaster.cer -r -ss Root -sr LocalMachine -a shal 


2. Bind the certificate to the Master port 


Check the original binding with the following command: 
netsh http show sslcert ipport=0.0.0.0:{Master port} 
For example: 
netsh http show sslcert ipport=0.0.0.0:8391 
Delete the original binding and set up the new binding with the following commands: 


netsh http delete sslcert ipport=0.0.0.0:{Master port} 
netsh http add sslcert ipport=0.0.0.0:{Master port} certhash={TLS/SSL Certificate Thumbprint} 
certstorename=Root appid={original appid} 


For example: 


netsh http delete sslcert ipport=0.0.0.0:8391 
netsh http add sslcert ipport=0.0.0.0:8391 certhash=01d207b300ca662f479beb884efeb6ce328F77d53 
certstorename=Root appid={a1f96506-93e0-4c91-9171-05a2f6739e13} 


3. Update the Scale Out Master service configuration file 
Update the Scale Out Master service configuration file, 

\<drive\>:\Program Files\Microsoft SQL Server\140\DTS\Binn\MasterSettings.config , on the Master node. Update 
SSLCertThumbprint to the thumbprint of the new TLS/SSL certificate. 


4. Restart the Scale Out Master service 


5. Reconnect Scale Out Workers to Scale Out Master 


For each Scale Out Worker, either delete the Worker and then add it back with Scale Out Manager, or do the 
following things: 


a. Install the client TLS/SSL certificate to the Root store of the local computer on the Worker node. 
b. Update the Scale Out Worker service configuration file. 


Update the Scale Out Worker service configuration file, 
\<drive\>:\Program Files\Microsoft SQL Server\140\DTS\Binn\WorkerSettings. config ,on the Worker node. Update 
MasterHttpsCertThumbprint to the thumbprint of the new TLS/SSL certificate. 


c. Restart the Scale Out Worker service. 


Scale Out Worker certificate 


Scale Out Worker certificate is generated automatically during the installation of Scale Out Worker. 


Change the Scale Out Worker certificate 
If you want to change Scale Out Worker certificate, do the following things: 


1. Create a certificate 


Create and install a certificate with the following command: 


MakeCert.exe -n CN={worker machine name};CN={worker machine ip} SSISScaleOutWorker.cer -r -ss My -sr 
LocalMachine 


For example: 


MakeCert.exe -n CN=WorkerMachine;CN=10.0.2.8 SSISScaleOutWorker.cer -r -ss My -sr LocalMachine 


2. Install the client certificate to the Root store of the local computer on the Worker node 


3. Grant service access to the certificate 


Delete the old certificate and grant Scale Out Worker service access to the new certificate with following 
command: 


certmgr.exe /del /c /s /r localmachine My /n {CN of the old certificate} 


winhttpcertcfg.exe -g -c LOCAL_MACHINE\My -s {CN of the new certificate} -a {the account running Scale Out 
Worker service} 


For example: 


certmgr.exe /del /c /s /r localmachine My /n WorkerMachine 
winhttpcertcfg.exe -g -c LOCAL_MACHINE\My -s WorkerMachine -a SSISScaleOutWorker140 


4. Update the Scale Out Worker service configuration file 
Update the Scale Out Worker service configuration file, 


\<drive\>:\Program Files\Microsoft SQL Server\140\DTS\Binn\WorkerSettings. config ,on the Worker node. Update 
WorkerHttpsCertThumbprint to the thumbprint of the new certificate. 


5. Install the client certificate to the Root store of the local computer on the Master node 
6. Restart the Scale Out Worker service 


Next steps 


For more info, see the following articles: 


e Integration Services (SSIS) Scale Out Master 


e Integration Services (SSIS) Scale Out Worker 
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In SSIS Scale Out, high availability on the Scale Out Worker side is provided by executing packages with multiple 
Scale Out Workers. 


High availability on the Scale Out Master side is achieved with Always On for SSIS Catalog and Windows 
failover clustering. In this solution, multiple instances of Scale Out Master are hosted in a Windows failover 
cluster. When the Scale Out Master service or SSISDB is down on the primary node, the service or SSISDB on 
the secondary node continues to accept user requests and communicate with Scale Out Workers. 


Alternatively, high availability on the Scale Out Master side can be achieved with SQL Server failover cluster 
instance. See Scale Out support for high availability via SQL Server failover cluster instance. 


To set up high availability on the Scale Out Master side with always on for SSIS catalog, do the following things: 


1. Prerequisites 


Set up a Windows failover cluster. See the blog post Installing the Failover Cluster Feature and Tools for 
Windows Server 2012 for instructions. Install the feature and tools on all cluster nodes. 


2. Install Scale Out Master on the primary node 


Install SQL Server Database Engine Services, Integration Services, and Scale Out Master on the primary node 
for Scale Out Master. 


During the installation, do the following things: 


2.1 Set the account running Scale Out Master service to a domain account 


This account must be able to access SSISDB on the secondary node in the Windows failover cluster in the future. 
As the Scale Out Master service and SSISDB can fail over separately, they may not be on the same node after 
failover. 


Server Configuration 


Specify the service accounts and collation configuration. 


Product Key 

License Terms 

Global Rules 

Microsoft Update 

Product Updates 

Install Setup Files 

Install Rules 

Feature Selection 

Feature Rules 

Instance Configuration 

Server Configuration 
Database Engine Configuration 
Integration Services Scale Out ... 
Integration Services Scale Out... 
Feature Configuration Rules 
Ready to Install 

Installation Progress 


Complete 





" Service Accounts | Collation 





Microsoft recommends that you use a separate account for each SQL Server service. 











Service Account Name __ Passw... Startup Type 

SQL Server Agent | NT Service\SQL... | Manual fv 
: : ~ 

SQL Server Database Engine ad Service\MS... I - ‘Automatic |v 

SQL Server Integration Services 14.0 NT Service\Ms... | ‘Automatic |v 





SQL Server Integration Services Scale Out Master 14.0 |[EeIntntiteid v| [Automatic |v 


SQL Server Integration Services Scale Out Worker 14.0 | NT Service\SSIS... | 


| Disabled | v| 


NT AUTHORTT... 
[_] Grant Perform Volume Maintenance Task privilege to SQL Server Database Engine Service 








SQL Server Browser 








This privilege enables instant file initialization by avoiding zeroing of data pages. This may lead 
to information disclosure by allowing deleted content to be accessed. 


a ; 








< Back 


Next > Cancel 


2.2 Include the DNS host name for the Scale Out Master service in the CNs of the Scale Out Master 


certificate 


This host name is the Scale Out Master endpoint, which is created as a clustered Generic Service in the failover 


cluster (see Step 7). (Be sure to provide a DNS host name and not a server name.) 


Integration Services Scale Out Configuration - Master Node 


Specify the port number and security certificate for the Scale Out Master node. 


Product Key 

License Terms 

Global Rules 

Microsoft Update 

Product Updates 

Install Setup Files 

Install Rules 

Feature Selection 

Feature Rules 

Instance Configuration 

Server Configuration 

Database Engine Configuration 
Integration Services Scale Ou... 
Integration Services Scale Out... 
Feature Configuration Rules 
Ready to Install 

Installation Progress 

Complete 


Specify a port number that the master node uses to communicate with the worker nodes. 


Port Number: 


Select a SSL certificate that is used for the communication between the master node and worker 
nodes in the scale out topology. A default self-signed certificate is created if you choose to create a 
new SSL certificate. 


© Create a new SSL certificate 


CNs in the certificate: 





CN=master.sys-sqlsvr.locall 


© Use an existing SSL certificate 


< Back 


Cancel 


Next > 


3. Install Scale Out Master on the secondary node 





Install SQL Server Database Engine Services, Integration Services, and Scale Out Master on the secondary node 
for Scale Out Master. 


Use the same Scale Out Master certificate that you used on the primary node. Export the Scale Out Master 
TLS/SSL certificate on the primary node with a private key and install it to the Root certificate store of the local 
computer on the secondary node. Select this certificate when installing Scale Out Master on the secondary 
node. 


Integration Services Scale Out Configuration - Master Node 


Specify the port number and security certificate for the Scale Out Master node. 


Product Key Specify a port number that the master node uses to communicate with the worker nodes. 

License Terms 

Global Rules Port Number: 3391 

Microsoft Update 

Product Updates 

Install Setup Files Select a SSL certificate that is used for the communication between the master node and worker 
Install Rules nodes in the scale out topology. A default self-signed certificate is created if you choose to create a 


new SSL certificate. 
Feature Selection 


Feature Rules 

Server Configuration _) Create a new SSL certificate 
Integration Services Scale Ou... CNs in the certificate: 
Feature Configuration Rules 


Ready to Install 


CN=csvm3126951 Ita.sys-sqlsvr.local; CN=10,225.195.165 


Installation Progress @ Use an existing SSL certificate 
Complete 
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NOTE 


You can set up multiple backup Scale Out Masters by repeating these operations for Scale Out Master on other 


secondary nodes. 





4. Set up and configure SSISDB support for Always On 


Follow the instructions to set up and configure SSISDB support for Always On in Always On for SSIS Catalog 
(SSISDB). 


In addition, you have to create an availability group listener for the availability group to which you add SSISDB. 
See Create or Configure an Availability Group Listener. 


5. Update the Scale Out Master service configuration file 


Update the Scale Out Master service configuration file, 
\<drive\>:\Program Files\Microsoft SQL Server\140\DTS\Binn\MasterSettings.config , on the primary and 


secondary nodes. Update SqiServerName to Availability Group Listener DNS name],[Port. 


6. Enable package execution logging 


Logging in SSISDB is done by the login ##MS_SSISLogDBWorkerAgentLogin##, for which the password is 


auto generated. To make logging work for all replicas of SSISDB, do the following things 
6.1 Change the password of ##MS_SSISLogDBWorkerAgentLogin## on the primary Sql Server 
6.2 Add the login to the secondary Sql Server 


6.3 Update the connection string used for logging. 


Call the stored procedure [catalog].[update_logdb_info] with the following parameter values: 
@® @server_name = '[Availability Group Listener DNS name], [Port]' 


@connection_string = ‘Data Source=[Availability Group Listener DNS name], [Port];Initial 
@® Catalog=SSISDB;User Id=##MS_SSISLogDBWorkerAgentLogin##; Password=[Password]];' 


7. Configure the Scale Out Master service role of the Windows Server 
failover cluster 


1. In Failover Cluster Manager, connect to the cluster for Scale Out. Select the cluster. Select Action in the 
menu and then select Configure Role. 


2. In the High Availability Wizard dialog box, select Generic Service on the Select Role page. Select 
SQL Server Integration Services Scale Out Master 14.0 on the Select Service page. 


3. On the Client Access Point page, enter the DNS host name of the Scale Out Master service. 


Ft Client Access Point 
Lh 


Before You Begin Type the name that clients will use when accessing this clustered role: 


Select Role 
Name: 


Select Service 
Client Access Point @™ NetBIOS name is limited to 15 characters. One or more DHCP IPv4 addresses were configured 
Select Storage automatically. All networks were configured automatically. 


Replicate Registry 
Settings 


Confirmation 


Configure High 
Availability 


Summary 





4. Finish the wizard. 


On Azure virtual machines, this configuration step requires additional steps. A full explanation of these concepts 
and these steps is beyond the scope of this article. 


1. You have to set up an Azure domain. Windows Server Failover Clustering requires all computers in the 
cluster to be members of the same domain. For more info, see Enable Azure Active Directory Domain 
Services using the Azure portal. 


2. You have to set up an Azure load balancer. This is a requirement for the availability group listener. For 
more info, see Tutorial: Load balance internal traffic with Basic Load Balancer to VMs using the Azure 
portal. 


8. Update the Scale Out Master address in SSISDB 


On the primary SQL Server, run the stored procedure [catalog].[update_master_address] with the parameter 


value @MasterAddress = N'https://[Scale Out Master service DNS host name]:[Master Port]' . 


9. Add the Scale Out Workers 


Now, you can add Scale Out Workers with the help of Integration Services Scale Out Manager. Enter 
[SQL Server Availability Group Listener DNS name],[Port] on the connection page. 


Upgrade Scale Out in high availability environment 


To upgrade Scale Out in high availability environment, follow the upgrade steps of Always On for SSIS catalog, 
upgrade Scale Out Master and Scale Out Worker on each machine, and recreate Windows Server failover cluster 
role in above step 7 with new version of Scale Out Master service. 


Next steps 


For more info, see the following articles: 


@ Integration Services (SSIS) Scale Out Master 


e Integration Services (SSIS) Scale Out Worker 
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To set up high availability on the Scale Out Master side with SQL Server failover cluster instance, do the 
following things: 


1. Prerequisites 


Set up a Windows failover cluster. See the blog post Installing the Failover Cluster Feature and Tools for 
Windows Server 2012 for instructions. Install the feature and tools on all cluster nodes. 


2. Install SQL Server failover cluster 


Install a SQL Server failover cluster. See SQL Server Failover Cluster Installation for instructions. During the 
installation, select Database Engine Services on Feature Selection page. Log the SQL Server network name for 
future configuration. 





Specify a network name for the new SQL Server failover cluster. This will be the name used to identify 
your failover cluster on the network. 


SQL Server Network Name: |sqlcluster| 








Add secondary node to the SQL Server failover cluster. 


3. Install Scale Out Master on the primary node 


Install Integration Services and Scale Out Master on the primary node with the setup wizard for nonclustered 
installation. 


During installation, include the SQL Server network name in the CNs of the Scale Out Master certificate. 





NOTE 


If you want to failover SSISDB and Scale Out Master service separately, follow 2. Install Scale Out Master on the primary 
node for Scale Out Master configuration. 











4. Install Scale Out Master on the secondary node 


Follow 3. Install Scale Out Master on the secondary node 


5. Update the Scale Out Master service configuration file 


Update the Scale Out Master service configuration file, <drive>:\Program Files\Microsoft SQL 
Server\140\DTS\Binn\MasterSettings.config, on the primary and secondary nodes. Update SqlServerName to 
[SQL Server network name]//[Instance name] or [SQL Server network name] for default instance. 


6. Add Scale Out Master service to SQL Server role in Windows 


failover cluster 


In Failover Cluster Manager, connect to the cluster for Scale Out. Select Roles in the explorer, right-click the SQL 


Server role, and select Add Resource, Generic Service. 














Name Status Type Owner Node Priority Information 
(Fei DTC Group @ Running Other VCSPOD410V-0737 Medium 
[FA SQL Server (MSSQLSERVER) (®) Running — ae wsnomnat tty 0837 Medium 

%% Start Role 

& Stop Role 

id Add File Share 

Hi Move » 





@) Change Startup Priority » 
a Information Details... 
£8] Show Critical Events 


























ce Add Storage 
@} Add Resource » Client Access Point 
3) More Actions > Generic Application 
Generic Script 
x Remove 
B = More Resources » 











In the New Resource Wizard, select Scale Out Master service and finish the wizard. 


Bring the Scale Out Master service online. 


7 re SQL Server (MSSQLSERVER) 





























Name Status Information 
Storage 
&A Cluster Disk 1 @® Oniine 
8 Name: salcluster @ Online % Take Offline 
Other Resources a Information Details... 
4] SQL Server @®) Online #8] Show Critical Events 
4] SQL Server Agent @® Online 3) More Actions > 
Rates XX Remove 
(4 SQL Server CEIP (MSSQLSERVER) (@) Online Propestieg 
(=) SQL Server Integration Services Scale Out Master 14.0 (® Offline 
NOTE 
If you want to failover SSISDB and Scale Out Master service separately, follow 7. Configure the Scale Out Master service 
role of the Windows failover cluster 





7. Install Scale Out Workers 


Install Scale Out Worker on worker nodes. During the installation, specify https://[Sql Server network name]: 
[master port] for master endpoint. 








NOTE 


If you want to failover SSISDB and Scale Out Master service separately, specify Scale Out Master service DNS host name 
instead of Sql Server network name. 











8. Install Scale Out Worker client certificate 


Install the worker certificate on all nodes in the SQL Server failover cluster. See Install Scale Out Worker client 
certificate. 


NOTE 


Scale Out Manager has not supported SQL Server failover cluster. If you use Scale Out Manager to add Scale Out Worker, 
you still need to install worker certificate to all master nodes manually. 











Next steps 
For more info, see the following articles: 


e Integration Services (SSIS) Scale Out Master 


e Integration Services (SSIS) Scale Out Worker 


Troubleshoot Scale Out 
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SSIS Scale Out involves communication among the SSIS Catalog database ssispB , the Scale Out Master 
service, and the Scale Out Worker service. Sometimes this communication breaks due to configuration 
mistakes, lack of access permissions, and other reasons. This article helps you to troubleshoot issues with your 
Scale Out configuration. 


To investigate the symptoms you encounter, follow the steps below one by one until your problem is resolved. 


Scale Out Master fails 


Symptoms 


e Scale Out Master cannot connect to SSISDB. 
e Master properties cannot show in Scale Out Manager. 
e Master properties are not populated in the view [catalog].[master_properties] . 


Solution 


1. Check whether Scale Out is enabled. 


In SSMS, in Object Explorer, right-click SSISDB and check Scale Out feature is enabled. 





| {J Script ~ @ Help 





SSISDB 

True 
Server-wide Default execution mode Server 
Schema Version 5 
Schema Build 14.0.800.36 
Encryption Algorithm Name AES_256 
Connection | Operations Log 

yi CSVM43935342TA Goon Lous Petodicaly 

[REDMOND \salcl01] Current Number of Records 

Current Size of Operation Log (KB) 
Retention Period (days) 
Server-wide Default Logging Level 
View connection properties 4 Project Versions 











Progress Scale Out feature is enabled 
When the value is TRUE, Scale Out feature is enabled in this Catalog. 














If the property value is False, enable Scale Out by calling the stored procedure 


[catalog].[enable_scaleout] . 


2. Check whether the SQL Server name specified in the Scale Out Master configuration file is correct, and 
restart the Scale Out Master service. 


Scale Out Worker fails 


Symptoms 


e Scale Out Worker cannot connect to Scale Out Master. 

e Scale Out Worker does not show after adding it in Scale Out Manager. 

e Scale Out Worker does not show in the view [catalog]. [worker_agents] . 

e The Scale Out Worker service is running, but the Scale Out Worker is offline. 


Solution 


Check the error messages in the Scale Out Worker service log under 


\<drive\>:\Users\\*[account running worker service]*\AppData\Local\SSIS\Cluster\Agent . 


No endpoint listening 


Symptoms 
“System.ServiceModel. EndpointNotFoundException: There was no endpoint listening at httos/AMachineName]: 
[Port]/ClusterManagemeny that could accept the message.” 


Solution 


1. Check whether the port number specified in the Scale Out Master service configuration file is correct, and 
restart the Scale Out Master service. 


2. Check whether the master endpoint specified in the Scale Out Worker service configuration is correct, 
and restart the Scale Out Worker service. 


3. Check whether the firewall port is open on the Scale Out Master node. 


4. Resolve any other connection issues between the Scale Out Master node and the Scale Out Worker node. 


Could not establish trust relationship 


Symptoms 
"System.ServiceModel.Security.SecurityNegotiationException: Could not establish trust relationship for the 
SSL/TLS secure channel with authority ‘[Machine Namej]-[Port]’." 


"System.Net. WebException: The underlying connection was closed: Could not establish trust relationship for the 
SSL/TLS secure channel.” 


“System.SecurityAuthentication.AuthenticationException: The remote certificate is invalid according to the 
validation procedure.” 


Solution 


1. Install the Scale Out Master certificate to the Root certificate store of the local computer on the Scale Out 
Worker node, if the certificate is not yet installed, and restart the Scale Out Worker service. 


2. Check whether the host name in the master endpoint is included in the CNs of the Scale Out Master 
certificate. If not, reset the master endpoint in the Scale Out Worker configuration file, and restart the 
Scale Out Worker service. 


NOTE 


If it's not possible to change the host name of the master endpoint due to DNS settings, you have to change the 


Scale Out Master certificate. See Manage certificates for SSIS Scale Out. 





3. Check whether the master thumbprint specified in the Scale Out Worker configuration matches the 
thumbprint of the Scale Out Master certificate. 


Could not establish secure channel 


Symptoms 
"System.ServiceModel Security.SecurityNegotiationException: Could not establish secure channel for SSL/TLS 
with authority '[Machine Name].[Port]’." 


“System.Net. WebException: The request was aborted: Could not create SSL/TLS secure channel." 


Solution 


Check whether the account running the Scale Out Worker service has access to the Scale Out Worker certificate 


by running the following command: 
winhttpcertcfg.exe -1 -c LOCAL_MACHINE\MY -s {CN of the worker certificate} 


If the account does not have access, grant access by running the following command, and restart Scale Out 
Worker service. 


winhttpcertcfg.exe -g -c LOCAL_MACHINE\My -s {CN of the worker certificate} -a {the account running Scale 
Out Worker service} 


HTTP request forbidden 


Symptoms 
"System.ServiceModel Security. MessageSecurityException: The HTTP request was forbidden with client 


authentication scheme ‘Anonymous'." 
“System.Net.WebException: The remote server returned an error: (403) Forbidden.” 


Solution 


1. Install the Scale Out Worker certificate to the Root certificate store of the local computer on the Scale Out 
Master node, if the certificate is not yet installed, and restart the Scale Out Worker service. 


2. Clean up useless certificates in the Root certificate store of the local computer on the Scale Out Master 
node. 


3. Configure Schannel to no longer send the list of trusted root certification authorities during the TLS/SSL 
handshake process by adding the following registry entry on the Scale Out Master node. 


HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL 
Value name: SendTrustedlssuerList 

Value type: REG_DWORD 

Value data: 0 (False) 


4. If it is not possible to clean up all non-self-signed certificates as described in step 2, set the value of the 
following registry key to 2. 


HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL 


Value name: ClientAuthTrustMode 


Value type: REG_DWORD 


Value data: 2 





NOTE 


If you have non-self-signed certificates in the Root certificate store, client certificate authentication fails. For more 


info, see Internet Information Services (IIS) 8 may reject client certificate requests with HTTP 403.7 or 403.16 


errors. 








HTTP request error 


Symptoms 

“System.ServiceModel.CommunicationException: An error occurred while making the HTTP request to 
https//[Machine Namej][Port]/ClusterManagement/. This could be due to the fact that the server certificate is 
not contigured properly with HTTPSYS in the HTTPS case. This could also be caused by a mismatch of the 
security binding between the client and the server." 


Solution 


1. Check whether the Scale Out Master certificate is bound to the port in the master endpoint correctly on 


the master node by running the following command: 
netsh http show sslcert ipport=0.0.0.0:{Master port} 


Check whether the certificate hash displayed matches the Scale Out Master certificate thumbprint. If the 
binding is not correct, reset the binding by running the following commands, and restart Scale Out 
Worker service. 


netsh http delete sslcert ipport=0.0.0.0:{Master port} 
netsh http add sslcert ipport=0.0.0.0:{Master port} certhash={Master certificate thumbprint} 
certstorename=Root appid={random guid} 


Cannot open certificate store 


Symptoms 
Validation fails when connecting a Scale Out Worker to the Scale Out Master in Scale Out Manager with the 
error message, “Cannot open certificate store on the machine." 


Solution 


1. Run Scale Out Manager as administrator. If you open Scale Out Manager with SSMS, you have to run 
SSMS as administrator. 


2. Start the Remote Registry service on the computer if it is not running. 


Execution doesn't start 


Symptoms 


Execution in Scale Out does not start. 


Solution 


Check the status of the computers you selected to run the package in the view [catalog].[worker_agents] . At 


least one worker must be online and enabled. 


No log 
Symptoms 
Packages run successfully, but there no messages are logged. 


Solution 


Check whether SQL Server Authentication is allowed by the SQL Server instance that hosts SSISDB. 





NOTE 
If you have changed the account for Scale Out logging, see Change the Account for Scale Out Logging and verify the 


connection string used for logging. 











Error messages aren't helpful 


Symptoms 


The error messages in the package execution report are not sufficient for troubleshooting. 


Solution 


More execution logs can be found under the TasksRootFolder configured in workerSettings.config . By default, 
this folder is \<drive\>:\Users\\[account]\AppData\Local\SSIS\ScaleOut\Tasks . The /account/ is the account 
running the Scale Out Worker service, with default value ssisscaleOutWorker14@ . 


To locate the log for the package execution with /execution /Dj, execute the following Transact-SQL command to 
get the /task /D]. Then, find the subfolder name that contains /task /D] under TasksRootFolder . 


SELECT [TaskId] 
FROM [SSISDB].[internal].[tasks] tasks, [SSISDB].[internal].[executions] executions 
WHERE executions.execution_id = *Your Execution Id* AND tasks.JobId = executions. job_id 





WARNING 


This query is for troubleshooting purpose only. The internal views referenced in the query are to change in the future. 





Next steps 
For more info, see the following articles about setting up and configuring SSIS Scale Out: 


e Get started with Integration Services (SSIS) Scale Out on a single computer 


e Walkthrough: Set up Integration Services (SSIS) Scale Out 


Integration Services (SSIS) Server and Catalog 


11/23/2021 * 2 minutes to read « Edit Online 





Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


After you design and test packages in SQL Server Data Tools, you can deploy the projects that contain the 
packages to the Integration Services server. 


The Integration Services server is an instance of the SQL Server Database Engine that hosts the SSISDB 
database. The database stores the following objects: packages, projects, parameters, permissions, server 
properties, and operational history. 


The SSISDB database exposes the object information in public views that you can query. The database also 
provides stored procedures that you can call to manage the objects. 


Before you can deploy the projects to the Integration Services server, you need to create the SSISDB catalog. 


For an overview of the SSISDB catalog functionality, see SSIS Catalog. 


High Availability 


Like other user databases, the SSISDB database supports database mirroring and replication. For more 
information about mirroring and replication, see Database Mirroring (SQL Server). 


You can also provide high-availability of SSISDB and its contents by making use of SSIS and Always On 
Availability Groups. For more information, see Always On for SSIS Catalog (SSISDB. Also see this blog post by 
Matt Masson, SSIS with Always On, at blogs.msdn.com. 


Integration Services Server in SQL Server Management Studio 


When you connect to an instance of the SQL Server Database Engine that hosts the SSISDB database, you see 
the following objects in Object Explorer: 


e SSISDB Database 


The SSISDB database appears under the Databases node in Object Explore. You can query the views 
and call the stored procedures that manage the Integration Services server and the objects that are 
stored on the server. 


e Integration Services Catalogs 


Under the Integration Services Catalogs node there are folders for Integration Services projects and 
environments. 


Related Tasks 


e View the List of Packages on the Integration Services Server 
e@ Deploy Integration Services (SSIS) Projects and Packages 


e Run Integration Services (SSIS) Packages 


Related Content 


Blog entry, SSIS with Always On, at blogs.msdn.com. 


SSIS Catalog 


11/23/2021 * 29 minutes to read « Edit Online 





Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


The SSISDB catalog is the central point for working with Integration Services (SSIS) projects that you've 
deployed to the Integration Services server. For example, you set project and package parameters, configure 
environments to specify runtime values for packages, execute and troubleshoot packages, and manage 
Integration Services server operations. 





NOTE 


This article describes the SSIS Catalog in general, and the SSIS Catalog running on premises. You can also create the SSIS 
Catalog in Azure SQL Database, and deploy and run SSIS packages in Azure. For more info, see Lift and shift SQL Server 
Integration Services workloads to the cloud. 


Although you can also run SSIS packages on Linux, the SSIS Catalog is not supported on Linux. For more info, see Extract, 
transform, and load data on Linux with SSIS. 











The objects that are stored in the SSISDB catalog include projects, packages, parameters, environments, and 
operational history. 


You inspect objects, settings, and operational data that are stored in the SSISDB catalog, by querying the views 
in the SSISDB database. You manage the objects by calling stored procedures in the SSISDB database or by 
using the UI of the SSISDB catalog. In many cases, the same task can be performed in the UI or by calling a 
stored procedure. 


To maintain the SSISDB database, it is recommended that you apply standard enterprise policies for managing 
user databases. For information about creating maintenance plans, see Maintenance Plans. 


The SSISDB catalog and the SSISDB database support Windows PowerShell. For more information about using 
SQL Server with Windows PowerShell, see SQL Server PowerShell. For examples of how to use Windows 
PowerShell to complete tasks such as deploying a project, see the blog entry, SSIS and PowerShell in SQL Server 
2012, on blogs.msdn.com. 


For more information about viewing operations data, see Monitor Running Package and Other Operations. 


You access the SSISDB catalog in SQL Server Management Studio by connecting to the SQL Server Database 
Engine and then expanding the Integration Services Catalogs node in Object Explorer. You access the 
SSISDB database in SQL Server Management Studio by expanding the Databases node in Object Explorer. 





NOTE 


You cannot rename the SSISDB database. 














NOTE 
If the SQL Server instance that the SSISDB database is attached to, stops or does not respond, the ISServerExec.exe 


process ends. A message is written to a Windows Event log. 


If the SQL Server resources fail over as part of a cluster failover, the running packages do not restart. You can use 


checkpoints to restart packages. For more information, see Restart Packages by Using Checkpoints. 











Features and capabilities 


@ Catalog Object Identifiers 

e Catalog Configuration 

e Permissions 

e Folders 

@ Projects and Packages 

e Parameters 

e Server Environments, Server Variables, and Server Environment References 


e Executions and Validations 


Catalog Object Identifiers 


When you create a new object in the catalog, assign a name to the object. The object name is an identifier. SQL 
Server defines rules for which characters can be used in an identifier. Names for the following objects must 
follow identifier rules. 


e Folder 

@ Project 

e@ Environment 

e Parameter 

@ Environment Variable 


Folder, Project, Environment 


Consider the following rules when renaming a folder, project, or environment. 


e Invalid characters include ASCII/Unicode characters 1 through 31, quote ("), less than (<), greater than 
(>), pipe (|), backspace (\b), null (\O), and tab (\t). 


e The name might not contain leading or trailing spaces. 
@ @ is not allowed as the first character, but subsequent characters might use @. 
e The length of the name must be greater than 0 and less than or equal to 128. 


Parameter 


Consider the following rules when naming a parameter. 


e The first character of the name must be a letter as defined in the Unicode Standard 2.0, or an underscore 


(). 


e Subsequent characters can be letters or numbers as defined in the Unicode Standard 2.0, or an 


underscore (_). 


Environment Variable 


Consider the following rules when naming an environment variable. 


@ Invalid characters include ASCII/Unicode characters 1 through 31, quote ("), less than (<), greater than 
(>), pipe (|), backspace (\b), null (\O), and tab (\t). 


e The name might not contain leading or trailing spaces. 
@ @ is not allowed as the first character, but subsequent characters might use @. 
e The length of the name must be greater than 0 and less than or equal to 128. 


e The first character of the name must be a letter as defined in the Unicode Standard 2.0, or an underscore 


(). 


e Subsequent characters can be letters or numbers as defined in the Unicode Standard 2.0, or an 


underscore (_). 


Catalog Configuration 


You fine-tune how the catalog behaves by adjusting the catalog properties. Catalog properties define how 
sensitive data is encrypted, and how operations and project versioning data is retained. To set catalog 
properties, use the Catalog Properties dialog box or call the catalog.configure_catalog (SSISDB Database) 
stored procedure. To view the properties, use the dialog box or query catalog.catalog_properties (SSISDB 
Database). You access the dialog box by right-clicking SSISDB in Object Explorer. 


Operations and Project Version Cleanup 


Status data for many of the operations in the catalog is stored in internal database tables. For example, the 
catalog tracks the status of package executions and project deployments. To maintain the size of the operations 
data, the SSIS Server Maintenance Job in SQL Server Management Studio is used to remove old data. This 
SQL Server Agent job is created when Integration Services is installed. 


You can update or redeploy an Integration Services project by deploying it with the same name to the same 
folder in the catalog. By default, each time you redeploy a project, the SSISDB catalog retains the previous 
version of the project. To maintain the size of the operations data, the SSIS Server Maintenance Job is used 
to remove old versions of projects. 


To run the SSIS Server Maintenance Job, SSIS creates the SQL Server login 
##MS_SSISServerCleanupJobLogin##. This login is only for internal use by SSIS. 


The following SSISDB catalog properties define how this SQL Server Agent job behaves. You can view and 
modify the properties by using the Catalog Properties dialog box or by using catalog.catalog_properties 
(SSISDB Database) and catalog.configure_catalog (SSISDB Database). 


Clean Logs Periodically 
The job step for operations cleanup runs when this property is set to True. 


Retention Period (days) 
Defines the maximum age of allowable operations data (in days). Older data are removed. 


The minimum value is one day. The maximum value is limited only by the maximum value of the SQL Server int 
data. For information about this data type, see int, bigint, smallint, and tinyint (Transact-SQL). 


Periodically Remove Old Versions 
The job step for project version cleanup runs when this property is set to True. 


Maximum Number of Versions per Project 


Defines how many versions of a project are stored in the catalog. Older versions of projects are removed. 


Encryption Algorithm 


The Encryption Algorithm property specifies the type of encryption that is used to encrypt sensitive 
parameter values. You can choose from the following types of encryption. 


e@ AES 256 (default) 
e AES_192 

e AES_128 

e DESX 

e TRIPLE_DES_3KEY 
e TRIPLE_DES 

e DES 


When you deploy an Integration Services project to the Integration Services server, the catalog automatically 
encrypts the package data and sensitive values. The catalog also automatically decrypts the data when you 
retrieve it. The SSISDB catalog uses the ServerStorage protection level. For more information, see Access 
Control for Sensitive Data in Packages. 


Changing the encryption algorithm is a time-intensive operation. First, the server has to use the previously 
specified algorithm to decrypt all configuration values. Then, the server has to use the new algorithm to re- 
encrypt the values. During this time, there cannot be other Integration Services operations on the server. Thus, 
to enable Integration Services operations to continue uninterrupted, the encryption algorithm is a read-only 
value in the dialog box in Management Studio. 


To change the Encryption Algorithm property setting, set the SSISDB database to the single-user mode and 
then call the catalog.configure_catalog stored procedure. Use ENCRYPTION_ALGORITHM for the property_name 
argument. For the supported property values, see catalog.catalog_properties (SSISDB Database). For more 
information about the stored procedure, see catalog.configure_catalog (SSISDB Database). 


For more information about single-user mode, see Set a Database to Single-user Mode. For information about 
encryption and encryption algorithms in SQL Server, see the topics in the section, SQL Server Encryption. 


A database master key is used for the encryption. The key is created when you create the catalog. 


The following table lists the property names shown in the Catalog Properties dialog box and the 
corresponding properties in the database view. 


PROPERTY NAME (CATALOG PROPERTIES DIALOG BOX) PROPERTY NAME (DATABASE VIEW) 
Encryption Algorithm Name ENCRYPTION_ALGORITHM 

Clean Logs Periodically OPERATION_CLEANUP_ENABLED&€€< 
Retention Period (days) RETENTION_WINDOW 

Periodically Remove Old Versions VERSION_CLEANUP_ENABLED 
Maximum Number of Versions per Project MAX_PROJECT_VERSIONS 


Server-wide Default Logging Level SERVER_LOGGING_LEVEL 


Permissions 


Projects, environments, and packages are contained in folders that are securable objects. You can grant 
permissions to a folder, including the MANAGE_OBJECT_PERMISSIONS permission. 
MANAGE_OBJECT_PERMISSIONS enables you to delegate the administration of folder contents to a user 
without having to grant the user membership to the ssis_admin role. You can also grant permissions to projects, 
environments, and operations. Operations include initializing Integration Services, deploying projects, creating 
and starting executions, validating projects and packages, and configuring the SSISDB catalog. 


For more information about database roles, see Database-Level Roles. 


The SSISDB catalog uses a DDL trigger, ddl_cleanup_object_permissions, to enforce the integrity of permissions 
information for SSIS securables. The trigger fires when a database principal, such as a database user, database 
role, or a database application role, is removed from the SSISDB database. 


If the principal has granted or denied permissions to other principals, revoke the permissions given by the 
grantor, before the principal can be removed. Otherwise, an error message is returned when the system tries to 
remove the principal. The trigger removes all permission records where the database principal is a grantee. 


It is recommended that the trigger is not disabled because it ensures that are no orphaned permission records 
after a database principal is dropped from the SSISDB database. 


Managing Permissions 


You can manage permissions by using the SQL Server Management Studio UI, stored procedures, and the 
Microsoft.SqlServer.Management.IntegrationServices namespace. 


To manage permissions using the SQL Server Management Studio UI, use the following dialog boxes: 
e Fora folder, use the Permissions page of the Folder Properties Dialog Box. 
e For a project, use the Permissions page in the Project Properties Dialog Box. 


To manage permissions using Transact-SQL, call catalog.grant_permission (SSISDB Database), 
catalog.deny_permission (SSISDB Database), and catalog.revoke_permission (SSISDB Database). To view 
effective permissions for the current principal for all objects, query catalog.effective_object_permissions (SSISDB 
Database). This topic provides descriptions of the different types of permissions. To view permissions that have 
been explicitly assigned to the user, query catalog.explicit_object_permissions (SSISDB Database). 


Folders 


A folder contains one or more projects and environments in the SSISDB catalog. You can use the catalog.folders 
(SSISDB Database) view to access information about folders in the catalog. You can use the following stored 
procedures to manage folders: 


e catalog.create_folder (SSISDB Database) 
e catalog.delete_folder (SSISDB Database) 
e catalog.rename_folder (SSISDB Database) 


e catalog.set_folder_description (SSISDB Database) 


Projects and Packages 


Each project can contain multiple packages. Both projects and packages can contain parameters and references 
to environments. You can access the parameters and environment references by using the Configure Dialog Box. 


You can carry out other project tasks by calling the following stored procedures: 


e catalog.delete_project (SSISDB Database) 

e catalog.deploy_project (SSISDB Database) 

e catalog.get_project (SSISDB Database) 

e@ catalog.move_project ((SSISDB Database) 

e catalog.restore_project (SSISDB Database) 

These views provide details about packages, projects, and project versions. 
e catalog.projects (SSISDB Database) 

e catalog.packages (SSISDB Database) 


e catalog.object_versions (SSISDB Database) 


Parameters 


You use parameters to assign values to package properties at the time of package execution. To set the value of a 
package or project parameter and to clear the value, call catalog.set_object_parameter_value (SSISDB Database) 
and catalog.clear_object_parameter_value (SSISDB Database). To set the value of a parameter for an instance of 
execution, call catalog.set_execution_parameter_value (SSISDB Database). You can retrieve default parameter 
values by calling catalog.get_parameter_values (SSISDB Database). 


These views show the parameters for all packages and projects, and parameter values that are used for an 
instance of execution. 


e catalog.object_parameters (SSISDB Database) 


e catalog.execution_parameter_values (SSISDB Database) 


Server Environments, Server Variables, and Server Environment 
References 


Server environments contain server variables. The variable values can be used when a package is executed or 
validated on the Integration Services server. 


The following stored procedures enable you to perform many other management tasks for environments and 
variables. 


e catalog.create_environment (SSISDB Database) 

e catalog.delete_environment (SSISDB Database) 

e@ catalog.move_environment (SSISDB Database) 

e catalog.rename_environment (SSISDB Database) 

e catalog.set_environment_property (SSISDB Database) 

© catalog.create_environment_variable (SSISDB Database) 

e catalog.delete_environment_variable (SSISDB Database) 

e catalog.set_environment_variable_property (SSISDB Database) 
e catalog.set_environment_variable_value (SSISDB Database) 


By calling the catalog.set_environment_variable_protection (SSISDB Database) stored procedure, you can set the 
sensitivity bit for a variable. 


To use the value of a server variable, specify the reference between the project and the server environment. You 
can use the following stored procedures to create and delete references. You can also indicate whether the 
environment can be located in the same folder as the project or in a different folder. 


e catalog.create_environment_reference (SSISDB Database) 

e catalog.delete_environment_reference (SSISDB Database) 

e catalog.set_environment_reference_type (SSISDB Database) 

For more details about environments and variables, query these views. 
e catalog.environments (SSISDB Database) 

e catalog.environment_variables (SSISDB Database) 


e catalog.environment_references (SSISDB Database) 


Executions and Validations 


An execution is an instance of a package execution. Call catalog.create_execution (SSISDB Database) and 
catalog.start_execution (SSISDB Database) to create and start an execution. To stop an execution or a 
package/project validation, call catalog.stop_operation (SSISDB Database). 


To cause a running package to pause and create a dump file, call the catalog.create_execution_dump stored 
procedure. A dump file provides information about the execution of a package that can help you troubleshoot 
execution issues. For more information about generating and configuring dump files, see Generating Dump 
Files for Package Execution. 


For details about executions, validations, messages that are logged during operations, and contextual 
information related to errors, query these views. 


e catalog.executions (SSISDB Database) 

e catalog.operations (SSISDB Database) 

e catalog.operation_messages (SSISDB Database) 

e catalog.extended_operation_info (SSISDB Database) 
e catalog.event_messages 

e catalog.event_message_context 


You can validate projects and packages by calling the catalog.validate_project (SSISDB Database) and 
catalog.validate_package (SSISDB Database) stored procedures. The catalog.validations (SSISDB Database) view 
provides details about validations such as the server environment references that are considered in the 
validation, whether it is a dependency validation or a full validation, and whether the 32-bit runtime or the 64- 
bit runtime is used to run the package. 


Create the SSIS Catalog 


After you design and test packages in SQL Server Data Tools, you can deploy the projects that contain the 
packages to an Integration Services server. Before you can deploy the projects to the Integration Services server, 
the server must contain the SSISDB catalog. The installation program for SQL Server 2012 (11.x) does not 
automatically create the catalog; you need to manually create the catalog by using the following instructions. 


You can create the SSISDB catalog in SQL Server Management Studio. You also create the catalog 
programmatically by using Windows PowerShell. 


To create the SSISDB catalog in SQL Server Management Studio 
1. Open SQL Server Management Studio. 


2. Connect to the SQL Server Database Engine. 


3. In Object Explorer, expand the server node, right-click the Integration Services Catalogs node, and 
then click Create Catalog. 


4. Click Enable CLR Integration. 
The catalog uses CLR stored procedures. 


5. Click Enable automatic execution of Integration Services stored procedure at SQL Server 
startup to enable the catalog.startup stored procedure to run each time the SSIS server instance is 
restarted. 


The stored procedure performs maintenance of the state of operations for the SSISDB catalog. It fixes the 


status of any packages there were running if the SSIS server instance goes down. 
6. Enter a password, and then click Ok. 


The password protects the database master key that is used for encrypting the catalog data. Save the 
password in a secure location. It is recommended that you also back up the database master key. For 
more information, see Back Up a Database Master Key. 


To create the SSISDB catalog programmatically 


1. Execute the following PowerShell script: 


# Load the IntegrationServices Assembly 
[Reflection.Assembly]::LoadWithPartialName("Microsoft.SqlServer.Management.IntegrationServices") 


# Store the IntegrationServices Assembly namespace to avoid typing it every time 
$ISNamespace = "Microsoft.SqlServer.Management .IntegrationServices" 


Write-Host "Connecting to server ..." 


# Create a connection to the server 
$sqlConnectionString = "Data Source=localhost;Initial Catalog=master;Integrated Security=SSPI;" 
$sqlConnection = New-Object System.Data.SqlClient.SqlConnection $sqlConnectionString 


# Create the Integration Services object 
$integrationServices = New-Object $ISNamespace".IntegrationServices" $sqlConnection 


# Provision a new SSIS Catalog 
$catalog = New-Object $ISNamespace".Catalog" ($integrationServices, "SSISDB", “P@assword1") 
$catalog.Create() 


For more examples of how to use Windows PowerShell and the 
Microsoft.SqlServer.Management.IntegrationServices namespace, see the blog entry, SSIS and 
PowerShell in SQL Server 2012, on blogs.msdn.com. For an overview of the namespace and code 
examples, see the blog entry, A Glimpse of the SSIS Catalog Managed Object Model, on blogs.msdn.com. 


Catalog Properties Dialog Box 


Use the Catalog Properties dialog box to configure the SSISDB catalog. Catalog properties define how sensitive 
data is encrypted, how operations and project versioning data is retained, and when validation operations time 
out. The SSISDB catalog is a central storage and administration point for Integration Services projects, packages, 
parameters, and environments. 


You can also view catalog properties in the catalog.catalog_ properties view, and set the properties by using the 
catalog.configure_catalog stored procedure. For more information, see catalog.catalog_properties (SSISDB 
Database) and catalog.configure_catalog (SSISDB Database). 


What do you want to do? 
e Open the Catalog Properties Dialog Box 
e Configure the Options 


Open the Catalog Properties Dialog Box 
1. Open SQL ServerManagement Studio. 


2. Connect Microsoft SQL Server Database Engine. 


3. In Object Explorer, expand the Integration Services node, right-click SSISDB, and then click 
Properties. 


Configure the Options 
Options 
The following table describes certain properties in the dialog box and the corresponding properties in the 


catalog.catalog properties view. 


PROPERTY NAME 
PROPERTY NAME (CATALOG (CATALOG.CATALOG_PROPERTIES 
PROPERTIES DIALOG BOX) VIEW) DESCRIPTION 


Encryption Algorithm Name ENCRYPTION_ALGORITHM Specifies the type of encryption that is 
used to encrypt the sensitive 
parameter values in the catalog. The 
following are the possible values: 


DES 

TRIPLE_DES 
TRIPLE_DES_3KEY 
DESPX 

AES_128 
AES_192 


AES 256 (default) 


Maximum Number of Versions per MAX_PROJECT_VERSIONS Specify how many versions of a project 

Project are stored in the catalog. Older 
versions of projects that exceed the 
maximum are removed when the 
project version cleanup job runs. 


Clean Logs Periodically OPERATION_CLEANUP_ENABLED Set the property to True to indicate 
that the SQL Server Agent job, 
operations cleanup, runs. Otherwise, 
set the property to False. 


PROPERTY NAME 


PROPERTY NAME (CATALOG (CATALOG.CATALOG_PROPERTIES 
PROPERTIES DIALOG BOX) VIEW) DESCRIPTION 
Retention Period (days) RETENTION_WINDOW Specify the maximum age of allowable 


operations data (in days). Data that is 
older than the specified number of 
days are removed by the SQL Agent 
job, operations cleanup. 


Back up, Restore, and Move the SSIS Catalog 


APPLIES TO: © SQL Server 2016 and later ‘*) Azure SQL Database ™) Azure Synapse Analytics 
Parallel Data Warehouse 


SQL Server 2019 Integration Services (SSIS) includes the SSISDB database. You query views in the SSISDB 
database to inspect objects, settings, and operational data that are stored in the SSISDB catalog. This topic 
provides instructions for backing up and restoring the database. 


The SSISDB catalog stores the packages that you've deployed to the Integration Services server. For more 
information about the catalog, see SSIS Catalog. 


To Back up the SSIS Database 


1. Open SQL Server Management Studio and connect to an instance of SQL Server. 


2. Back up the master key for the SSISDB database, by using the BACKUP MASTER KEY Transact-SQL 
statement. The key is stored in a file that you specify. Use a password to encrypt the master key in the file. 


For more information about the statement, see BACKUP MASTER KEY (Transact-SQL). 


In the following example, the master key is exported to the c:\temp directory\RCTestiInstkey file. The 
LS2Setup! password is used to encrypt the master key. 


backup master key to file = 'c:\temp\RCTestInstKey' 
encryption by password = 'LS2Setup!' 


3. Back up the SSISDB database by using the Backup Database dialog box in SQL Server Management 
Studio. For more information, see How to: Back Up a Database (SQL Server Management Studio). 


4. Generate the CREATE LOGIN script for ##MS_SS|ISServerCleanupJobLogin##, by doing the following 
things. For more information, see CREATE LOGIN (Transact-SQL). 


a. In Object Explorer in SQL Server Management Studio, expand the Security node and then expand 
the Logins node. 


b. Right-click ##MS_SSISServerCleanupJobLogin##, and then click Script Login as > CREATE 
To > New Query Editor Window. 


5. If you are restoring the SSISDB database to an SQL Server instance where the SSISDB catalog was never 
created, generate the CREATE PROCEDURE script for sp_ssis_startup, by doing the following things. For 
more information, see CREATE PROCEDURE (Transact-SQL). 


a. In Object Explorer, expand the Databases node and then expand the master > Programmability 
> Stored Procedures node. 


b. Right-click dbo.sp_ssis_startup, and then click Script Stored Procedure as > CREATE To > 
New Query Editor Window. 


6. Confirm that SQL Server Agent has been started 


7. If you are restoring the SSISDB database to an SQL Server instance where the SSISDB catalog was never 
created, generate a script for the SSIS Server Maintenance Job by doing the following things. The script is 
created in SQL Server Agent automatically when the SSISDB catalog is created. The job helps clean up 
cleanup operation logs outside the retention window and remove older versions of projects. 


a. In Object Explorer, expand the SQL Server Agent node and then expand the Jobs node. 


b. Right-click SSIS Server Maintenance Job, and then click Script Job as > CREATE To > New 
Query Editor Window. 


To Restore the SSIS Database 


1. If you are restoring the SSISDB database to an SQL Server instance where the SSISDB catalog was never 
created, enable common language runtime (clr) by running the sp_configure stored procedure. For more 


information, see sp_configure (Transact-SQL) and clr enabled Option. 


use master 
sp_configure ‘clr enabled’, 1 
reconfigure 


2. If you are restoring the SSISDB database to an SQL Server instance where the SSISDB catalog was never 
created, create the asymmetric key and the login from the asymmetric key, and grant UNSAFE permission 
to the login. 


Create Asymmetric Key MS_SQLEnableSystemAssemblyLoadingKey 

FROM Executable File = ‘C:\Program Files\Microsoft SQL 
Server\YourSQLServerDefaultCompatibilityLevel\DTS\Binn\Microsoft.SqlServer. IntegrationServices.Server 
ace Hike 


You can find the value for YoursQLserverDefaultCompatibilityLevel from a list of SQL Server default 
compatibility levels. 


Integration Services CLR stored procedures require UNSAFE permissions to be granted to the login 
because the login requires additional access to restricted resources, such as the Microsoft Win32 API. For 
more information about the UNSAFE code permission, see Creating an Assembly. 


Create Login ##MS_SQLEnableSystemAssemblyLoadingUser## FROM Asymmetric Key 
MS_SQLEnableSystemAssemblyLoadingKey 
Grant Unsafe Assembly to ##MS_SQLEnableSystemAssemblyLoadingUser## 


3. Restore the SSISDB database from the backup by using the Restore Database dialog box in SQL Server 
Management Studio. For more information, see the following topics: 


e Restore Database (General Page) 
e Restore Database (Files Page) 
e Restore Database (Options Page) 


4. Execute the scripts that you created in the To Back up the SSIS Database for 
##MS_SSI|SServerCleanupJobLogin##, sp_ssis_startup, and SSIS Server Maintenance Job. Confirm that 
SQL Server Agent has been started. 


5. Run the following statement to set the sp_ssis_startup procedure for autoexecution. For more 
information, see sp_procoption (Transact-SQL). 


EXEC sp_procoption N'sp_ssis_startup', startup’, ‘on’ 


6. Map the SSISDB user ##MS_SSISServerCleanupJobUser## (SSISDB database) to 
##MS_SSISServerCleanupJobLogin##, by using the Login Properties dialog box in SQL Server 
Management Studio. 


7. Restore the master key by using one of the following methods. For more information about encryption, 
see Encryption Hierarchy. 


e Method 1 
Use this method if you've already performed a backup of the database master key, and you have 


the password used to encrypt the master key. 


Restore master key from file = 'c:\temp\RCTestInstKey' 


Decryption by password = 'LS2Setup!' -- ‘Password used to encrypt the master key during 
SSISDB backup’ 

Encryption by password = 'LS3Setup!' -- 'New Password‘ 

Force 





NOTE 


Confirm that the SQL Server service account has permissions to read the backup key file. 


NOTE 


You see the following warning message displayed in SQL Server Management Studio if the database 


master key has not yet been encrypted by the service master key. Ignore the warning message. 


The current master key cannot be decrypted. The error was ignored because the FORCE 
option was specified. 


The FORCE argument specifies that the restore process should continue even if the current database 
master key is not open. For the SSISDB catalog, because the database master key has not been opened on 


the instance where you are restoring the database, you see this message. 











e Method 2 


Use this method if you have the original password that was used to create SSISDB. 


open master key decryption by password = 'LS1Setup!' --'Password used when creating SSISDB' 
Alter Master Key Add encryption by Service Master Key 


8. Determine whether the SSISDB catalog schema and the Integration Services binaries (ISServerExec and 
SQLCLR assembly) are compatible, by running catalog.check_schema_version. 


9. To confirm that the SSISDB database has been restored successfully, perform operations against the 
SSISDB catalog such as running packages that have been deployed to the Integration Services server. For 
more information, see Run Integration Services (SSIS) Packages. 


To Move the SSIS Database 


e Follow the instructions for moving user databases. For more information, see Move User Databases. 


Ensure that you back up the master key for the SSISDB database and protect the backup file. For more 


information, see To Back up the SSIS Database. 


Ensure that the Integration Services (SSIS) relevant objects are created in the new SQL Server instance 
where the SSISDB catalog has not yet been created. 


Upgrade the SSIS Catalog (SSISDB) 


Run the SSISDB Upgrade Wizard to upgrade the SSIS Catalog database, SSISDB, when the database is older than 
the current version of the SQL Server instance. The database may be older when one of the following conditions 
is true. 


e You restored the database from an older version of SQL Server. 


e You did not remove the database from an Always On Availability Group before upgrading the SQL Server 
instance. This condition prevents the automatic upgrade of the database. For more info, see Upgrading 
SSISDB in an availability group. 


The wizard can only upgrade the database on a local server instance. 


Upgrade the SSIS Catalog (SSISDB) by running the SSISDB Upgrade Wizard 
1. Back up the SSIS Catalog database, SSISDB. 


2. In SQL Server Management Studio, expand the local server, and then expand Integration Services 
Catalogs. 


3. Right-click on SSISDB, and then select Database Upgrade to launch the SSISDB Upgrade Wizard. Or 
launch the SSISDB Upgrade Wizard by running 
C:\Program Files\Microsoft SQL Server\14@\DTS\Binn\ISDBUpgradeWizard.exe with elevated permissions on 


the local server. 
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4. On the Select Instance page, select a SQL Server instance on the local server. 





IMPORTANT 


The wizard can only upgrade the database on a local server instance. 





Select the checkbox to indicate that you have backed up the SSISDB database before running the wizard. 


A °° Select Instance 


4 


Introduction 


Select Instance 


[_] | have taken a backup of the SSISDB database. Continue with the the SSISDB upgrade. 





5. Select Upgrade to upgrade the SSIS Catalog database. 


6. On the Result page, review the results. 
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Local instance validation 


User permission validation 
Database version validation 
| SSISDB upgrade 











Always On for SSIS Catalog (SSISDB) 


The Always On Availability Groups feature is a high-availability and disaster-recovery solution that provides an 
enterprise-level alternative to database mirroring. An availability group supports a failover environment for a 
discrete set of user databases, known as availability databases, that fail over together. For more information, see 
Always On Availability Groups. 


In order to provide the high-availability for the SSIS catalog (SSISDB) and its contents (projects, packages, 
execution logs, etc.), you can add the SSISDB database (just the same as any other user database) to an Always 
On Availability Group. When a failover occurs, one of the secondary nodes automatically becomes the new 
primary node. 





IMPORTANT 


When a failover occurs, packages that were running do not restart or resume. 











In this section: 

1. Prerequisites 

2. Configure SSIS support for Always On 

3. Upgrading SSISDB in an availability group 


Prerequisites 


Do the following prerequisite steps before enabling Always On support for the SSISDB database. 


1. Set up a Windows failover cluster. See Installing the Failover Cluster Feature and Tools for Windows 
Server 2012 blog post for instructions. Install the feature and tools on all cluster nodes. 


2. Install SQL Server 2016 with Integration Services (SSIS) feature on each node of the cluster. 


3. Enable Always On Availability Groups for each SQL Server instance. See Enable Always On Availability 
Groups for details. 


Configure SSIS support for Always On 


e Step 1: Create Integration Services Catalog 
e Step 2: Add SSISDB to an Always On Availability Group 


e Step 3: Enable SSIS support for Always On 





IMPORTANT 
e You must perform these steps on the primary node of the availability group. 


e You must enable SSIS support for Always On after you add SSISDB to an Always On Availability Group. 





Step 1: Create Integration Services Catalog 
1. Launch SQL Server Management Studio and connect to a SQL Server instance in the cluster that you 
want to set as the primary node of Always On high availability group for SSISDB. 


2. In Object Explorer, expand the server node, right-click the Integration Services Catalogs node, and 
then click Create Catalog. 


3. Click Enable CLR Integration. The catalog uses CLR stored procedures. 


4. Click Enable automatic execution of Integration Services stored procedure at SQL Server 
startup to enable the catalog.startup stored procedure to run each time the SSIS server instance is 
restarted. The stored procedure performs maintenance of the state of operations for the SSISDB catalog. 
It fixes the status of any packages there were running if and when the SSIS server instance goes down. 


5. Enter a password, and then click Ok. The password protects the database master key that is used for 
encrypting the catalog data. Save the password in a secure location. It is recommended that you also back 
up the database master key. For more information, see Back Up a Database Master Key. 


Step 2: Add SSISDB to an Always On Availability Group 
Adding the SSISDB database to an Always On Availability Group is almost same as adding any other user 
database into an availability group. See Use the Availability Group Wizard. 


Provide the password that you specified while creating the SSIS Catalog in the Select Databases page of the 
New Availability Group wizard. 
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Step 3: Enable SSIS support for Always On 

After you create the Integration Service Catalog, right-click the Integration Service Catalogs node, and click 
Enable Always On Support. You should see the following Enable Support for Always On dialog box. If 
this menu item is disabled, confirm that you have all the prerequisites installed and click Refresh. 


Script + (4 Help 


Connect to all new added secondary replicas. 


Before the dialog can configure SSIS to enable support AlwaysOn on the new added 
secondary replicas, you must connect to all new added secondary replicas. 


Service Name Connect As 
\SSISSOLSERVER Not Connected 


\SSISSQLSERVER 


View connection properties 
Progress 
Ready 





WARNING 
Auto-failover of SSISDB database is not supported until you enable SSIS Support for Always On. 





The newly added secondary replicas from the Always On availability group are shown in the table. Click 
Connect... button for each replica in the list and enter authentication credentials to connect to the replica. The 
user account must be a member of sysadmin group on each replica to enable SSIS support for Always On. After 
you successfully connect to each replica, click OK to enable SSIS support for Always On. 


If the Enable Always On support option on the context menu appears to be disabled after you've completed 
the other prerequisites, try these things: 


1. Refresh the context menu by clicking the Refresh option. 
2. Make sure you are connecting to the primary node. You have to enable Always On support on the primary 
node. 


3. Make sure the SQL Server version is 13.0 or higher. SSIS supports Always On only on SQL Server 2016 and 
later versions. 


Upgrading SSISDB in an availability group 


If you're upgrading SQL Server from a previous version, and SSISDB is in an Always On availability group, your 
upgrade may be blocked by the "SSISDB in Always On Availability Group check" rule. This blocking occurs 
because upgrade runs in single-user mode, while an availability database must be a multi-user database. 
Therefore, during upgrade or patching, all availability databases including SSISDB are taken offline and are not 
upgraded or patched. To let upgrade continue, first remove SSISDB from the availability group, then upgrade or 
patch each node, then add SSISDB back to the availability group. 


If you are blocked by the "SSISDB in Always On Availability Group check" rule, follow these steps to upgrade 
SQL Server. 


1. Remove the SSISDB database from the availability group. For more info, see Remove a Secondary 


Database from an Availability Group (SQL Server) and Remove a Primary Database from an Availability 
Group (SQL Server). 


2. Click Rerun in the upgrade wizard. The "SSISDB in Always On Availability Group check" rule passes. 
3. Click the Next to continue the upgrade. 


4. After you have upgraded all the nodes, add the SSISDB database back to the Always On availability 
group. For more info, see Add a Database to an Availability Group (SQL Server). 


If you're not blocked when you upgrade SQL Server, and SSISDB is in an Always On availability group, upgrade 
SSISDB separately after you upgrade the SQL Server database engine. Use the SSIS Upgrade Wizard to upgrade 
the SSISDB as described in the following procedure. 


1. Move the SSISDB database out of the availability group, or delete the availability group if SSISDB is the 
only database in the availability group. Launch SQL Server Management Studio on the primary 
node of the availability group to perform this task. 


2. Remove the SSISDB database from all replica nodes. 


3. Upgrade the SSISDB database on the primary node. InObject Explorer in SQL Server Management 
Studio, expand Integration Services Catalogs, right-click SSISDB, and then select Database 
Upgrade. Follow the instructions in the SSISDB Upgrade Wizard to upgrade the database. Launch the 
SSIDB Upgrade Wizard locally on the primary node. 


4. Follow the instructions in Step 2: Add SSISDB to an Always On Availability Group to add the SSISDB back 
to an availability group. 


5. Follow the instructions in Step 3: Enable SSIS support for Always On. 


SSISDB Catalog and delegation in double-hop scenarios 


By default, the remote invocation of SSIS packages stored under the SSISDB catalog doesn't support the 
delegation of credentials, sometimes referred to as a double-hop. 


Imagine a scenario in which a user logs in to client machine A and launches SQL Server Management Studio 
(SSMS). From within SSMS, the user connects to a SQL server that's hosted on machine B, which has the SSISDB 
catalog. The SSIS package is stored under this SSISDB catalog and the package in turn connects to a SQL Server 
service that is running on machine C (the package could also be accessing any other services). When the user 
invokes the execution of the SSIS package from machine A, SSMS first successfully passes the user credentials 
from machine A to machine B (where the SSIS runtime process is executing the package). The SSIS execution 
runtime process (ISServerExec.exe) is now required to delegate the user credentials from machine B to machine 
C for the execution to complete successfully. However, delegation of credentials is not enabled by default. 


A user can enable the delegation of credentials by granting the rust this user for delegation to any service 
(Kerberos Only) right to the SQL Server service account (on machine B), which launches ISServerExec.exe as a 
child process. This process is referred to as setting up unconstrained delegation or open delegation for a SQL 
Server service account. Before you grant this right, consider whether it meets the security requirements of your 


organization. 


SSISDB doesn't support constrained delegation. In a double-hop environment, if the service account of the SQL 
server that hosts the SSISDB catalog (machine B in our example) is set up for constrained delegation, 
ISServerExec.exe won't be able to delegate the credentials to the third machine (machine C). This is applicable to 
scenarios in which Windows Credential Guard is enabled, which mandatorily requires constrained delegation to 
be set up. 


Related Content 


e Blog entry, SSIS and PowerShell in SQL Server 2012, on blogs.msdn.com. 
e Blog entry, SSIS Catalog Access Control Tips, on blogs.msdn.com. 


e Blog entry, A Glimpse of the SSIS Catalog Managed Object Model, on blogs.msdn.com. 
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Applies to: Q sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 
You can view the list of packages that are stored on the Integration Services server in one of two ways. 


Transact-SQL access 


To view the list of packages that are stored on the server, query the view, catalog.packages (SSISDB Database). 


In SQL Server Management Studio 


To view packages stored on the server by using Object Explorer in SQL Server Management Studio, follow the 
procedure below. 


To view packages using SQL Server Management Studio 


1. In SQL Server Management Studio, connect to the Integration Services server. That is, connect to the 
instance of the SQL Server Database Engine that hosts the Integration Services database. 


2. In Object Explorer, expand the tree to display the Integration Services Catalogs node. 
3. Expand the Integration Services Catalogs node to display the SSISDB node. 


4. Expand the SSISDB node to display a list of one or more folders. Each folder contains one or more 
projects in the Projects folder, and each project contains one more packages in the Packages folder. 


Integration Services (SSIS) Catalog Transact-SQL 


Reference 
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Applies to: @sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Views (Integration Services Catalog) 
Stored Procedures (Integration Services Catalog) 


Functions (Integration Services Catalog) 


Browse All Principals Dialog Box 


11/23/2021 * 2 minutes to read « Edit Online 





Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Use the Browse All Principals dialog box to select a database principal to change the principal's permissions 
on the selected project or on all projects contained in a selected folder. 


What do you want to do? 
e@ Open the Browse All Principals dialog box 


e Configure the Options 


Open the Browse All Principals dialog box 
1. In SQL Server Management Studio, connect to the Integration Services server. 
You're connecting to the instance of the SQL Server Database Engine that hosts the SSISDB catalog. 
2. In Object Explorer, expand the tree to display the Integration Services Catalogs node. 
3. Expand the SSISDB node. 


4. To change the principal's permissions on all projects contained in a selected folder, right-click the folder 
and then click Properties. 


To change the principal's permissions on a selected project, expand the folder that contains the project, 
right-click the project, and then click Properties. 


5. Select the Permissions page, and then click Browse. 


Configure the Options 
This page displays the principals from the catalog view, sys.database_principals, of the SSISDB database. 


Selecting principals adds them to the Logins or roles list on the Permissions page of the parent dialog box 
when you click OK and close the Browse All Principals dialog box. After adding principals to the Logins or 
roles list, you can change their permissions on the selected project. 


Selection column 


Select to add the principal to the Logins or roles list on the Permissions page of the parent dialog box. 


Icon column 


An icon that corresponds to the Type of the principal. 


Name 
The name of the principal. 


Type 
The type of the principal. The common types are: 


e SQL User 
e Windows User 


e Database Role 


Configure Dialog Box 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Use the Configure dialog box to configure parameters, connection managers, and references to environments, 
for packages and projects. 


What do you want to do? 
e@ Open the Configure Dialog Box 
e Set the options on the Parameters page 


e Set the options on the References page 


Open the Configure Dialog Box 
1. In SQL Server Management Studio, connect to the Integration Services server. 
You're connecting to the instance of the SQL Server Database Engine that hosts the SSISDB database. 
2. In Object Explorer, expand the tree to display the Integration Services Catalogs node. 
3. Expand the SSISDB node. 
4. Expand the folder that contains the package or project that you want to configure. 


5. Right-click the package or project, and then click Configure. 


Set the options on the Parameters page 


Use the Parameters page to view parameter names and values, and to modify the values. 


Select the scope of the parameters displayed in the Parameters and Connection Managers tabs, in the 
Scope drop-down list. 


The following is a list of the options in the Parameters tab. 


Container 


Lists the object that contains the parameter. 


Name 


Lists the parameter name. 


Value 
Lists the parameter value. Click the ellipsis button to change the value in the Set Parameter Value dialog box. 


The following is a list of the options in the Connection Managers tab. You use this tab to change values for 
connection manager properties. Parameters are automatically generated on the SSIS server for the properties. 


Container 
Lists the object that contains the connection manager. 


Name 


Lists the connection manager name. 


Property name 
Lists the name of the connection manager property. 


Value 
Lists the value assigned to the connection manager property. Click the ellipsis button to change the value in the 
Set Parameter Value dialog box. You can enter a literal value, map an environment variable that contains the 


value you want to use, or use the default value from the package. 


Set the options on the References page 


Use the References page to add and remove references to environments, and to access environment 


properties. 


An environment specifies runtime values for packages contained in the projects you've deployed to Integration 


Services server. 


Environment 


Lists the environment. 


Environment Folder 


Lists the folder that contains the environment. 


Open 
Click to open the Environment Properties dialog box. 


Add 
Click to add a reference to an environment. In the Browse Environments dialog box click an environment and 
then click OK. 


You can select an environment contained in any project folder under the SSISDB node. 


Remove 
Click an environment listed in the References area, and then click Remove. 


Folder Properties Dialog Box 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


A folder contains projects and environments in the SSISDB catalog. Each folder defines permissions that apply 
to the contents of the folder. For more information about Integration Services permissions, see 
catalog.grant_permission (SSISDB Database). 


To Set Folder Description and Permissions 

1. Right-click the folder and select Properties. 

2. On the General page, select Description under General and enter an optional description. 

3. On the Permissions page, click Browse..., select one or more database principals, and click OK. 

4. Select aname under Logins or roles and specify the appropriate permissions under Permissions. 


5. Click OK to accept the changes and close the Folders Properties dialog box. 


See Also 


Integration Services (SSIS) Server 
catalog.grant_permission (SSISDB Database) 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Use the Package Properties dialog box to view properties for packages that are stored on the Integration 
Services server. 


For more information, see Integration Services (SSIS) Server. 
What do you want to do? 
@ Open the Package Properties dialog box 


e Configure the Options 


Open the Package Properties dialog box 
1. In SQL Server Management Studio, connect to the Integration Services server. 
You're connecting to the instance of the SQL Server Database Engine that hosts the SSISDB database. 
2. In Object Explorer, expand the tree to display the Integration Services Catalogs node. 
3. Expand the SSISDB node. 
4. Expand the folder that contains the package you want to view properties for. 


5. Right-click the package, and then select Properties. 


Configure the Options 
Use the General page to view the properties of the selected package. 
All properties on the General page are read-only. 


Name 


Displays the name of the package. 


Identifier 
Lists the package ID. 


Entry Point 
The value of True indicates that the package is started directly. The value of False indicates that the package is 
started by another package using the Execute Package task. The default value is True. 


You set this property in SQL Server Data Tools (SSDT) for both the parent package and the child packages by 
right-clicking the package in Solution Explorer and then clicking Entry-point Package. 


Description 
Displays the optional description of the package. 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


An Integration Services project is a unit of deployment. Each project can contain packages, parameters, and 
environment references. A project is a securable object and can define permissions for database principals. 
When a project is re-deployed, the previous version of the project can be stored in the Integration Services 
catalog. 


Project parameters and package parameters can be used to assign values to properties within packages at the 
time of execution. Some parameters require values before the package can be executed. Parameter values that 
reference environment variables require that the project has the corresponding environment reference prior to 
execution. 


What do you want to do? 
@ Open the Project Properties dialog box 
e Set the options on the General page 


e Set the options on the Permissions page 


Open the Project Properties dialog box 
1. In SQL Server Management Studio, connect to the Integration Services server. 
You're connecting to the instance of the SQL Server Database Engine that hosts the SSISDB database. 
2. In Object Explorer, expand the tree to display the Integration Services Catalogs node. 
3. Expand the SSISDB node. 
4. Expand the folder that contains the project that you want to set properties for. 


5. Right-click the project, and then click Properties. 


Set the options on the General page 
Use the General page to view project properties. 


Name 
Lists the project name. 


Identifier 


Lists the project ID. 


Description 
Displays the optional description of the project. 


Project Version 
Lists the project version. 


Deployment Date 
Lists the date and time the project was deployed or redeployed. 


Set the options on the Permissions page 


Use the Permissions page to view and set explicit permissions for the project. 


Browse 
Click Browse to select users and roles that you want to set permissions for, by using the Browse All 
Principals dialog box. 


Name 
Lists the name of the user or role. 


Type 
Lists the type of user or role. 


Permission 
Lists the permissions. 


Grantor 
Lists the user or role that grants the permission. 


Grant 
When Grant is selected, the permission is granted for the selected user or role. 


Deny 
When Deny is selected, the permission is denied for the selected user or role. 


Project Versions Dialog Box 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 
Use the Project Versions dialog box to view versions of a project and to restore a previous version. 


You can also view previous versions in the catalog.object_versions (SSISDB Database) view, and use the 
catalog.restore_project (SSISDB Database) stored procedure to restore previous versions. 


What do you want to do? 
e@ Open the Project Versions dialog box 


e Restore a Project Version 


Open the Project Versions dialog box 
1. In SQL Server Management Studio, connect to the Integration Services server. 


That is, connect to the instance of the SQL Server Database Engine that hosts the Integration Services 
database. 


2. In Object Explorer, expand the tree to display the Integration Services Catalogs node. 
3. Expand the Integration Services Catalogs node to display the SSISDB node. 


4. The SSISDB node contains one or more folders that each contain one or more projects. Expand the folder 
that contains the project you are interested in. 


5. Right-click the project, and then click Versions. 


In the Project Versions dialog box, the Versions table displays the list of versions of the project that have 
been deployed on the server, with the date and time the version was deployed, the date and time the version 
was restored (if it was restored), the version description, and a version identifier. The currently active version is 
indicated with a check mark in the Current column of the table. 


Restore a Project Version 


To restore a previous version of a project, select the version in the Versions table, and then click Restore to 
Selected Version. The project is restored to the selected version and that version is indicated with a check 
mark in the Current column of the Versions table. 


Set Parameter Value Dialog Box 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Use the Set Parameter Value dialog box to set values for parameters and connection manager properties, for 
projects and packages. 


What do you want to do? 
e@ Open the Set Parameter Value dialog box 


e Configure the options 


Open the Set Parameter Value dialog box 
1. In SQL Server Management Studio, connect to the Integration Services server. 
You're connecting to the instance of the SQL Server Database Engine that hosts the SSISDB database. 
2. In Object Explorer, expand the tree to display the Integration Services Catalogs node. 
3. Expand the SSISDB node. 


4. Right-click a package or project, click Configure, and then click the ellipsis button in the Parameters tab 
or in the Connection Managers tab. 


Configure the options 


Parameter 
Lists the parameter name. 


Type 
Lists the data type of the parameter value. 


Description 
Shows an optional description for the parameter. 


Edit value 
Select this option to edit the parameter value. 


Use default value from package 
Select this option to use the default parameter value stored in the package. 


Use environment variable 

Select this option to use a variable value stored in the environment, which is referenced by the project or 
package. To add an environment reference to a project or package, use the Configure dialog box. For more 
information, see Configure Dialog Box. 


Validate Dialog Box 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 
Use the Validate dialog box to check for common problems in Integration Services a project or package. 


If there is a problem, a message is displayed at the top of the dialog box. Otherwise, the term Ready displays at 
the top. 


What do you want to do? 
e Open the Validate dialog box 


e Set the options on the General page 


Open the Validate dialog box 
1. In SQL Server Management Studio, connect to the Integration Services server. 
You're connecting to the instance of the SQL Server Database Engine that hosts the SSISDB database. 
2. In Object Explorer, expand the tree to display the Integration Services Catalogs node. 
3. Expand the SSISDB node. 
4. Expand the folder that contains the project or package you want to validate. 


5. Right-click the package or package, and then click Validate. 


Set the options on the General page 


Environment 


Select the environment that you want to use to validate the project or package. 


32-bit runtime 
Select to use a 32-bit runtime to execute a package. 


The Parameters tab lists the parameter values that you use to validate the project or package. The following are 
the options on the Parameters tab. 


Container 


Lists the object that contains the parameter. 


Parameter 


Lists the name of the parameters 


Value 
Lists the parameter value. 


The Connection Managers tab lists the connection manager property values that you use to validate the 
project or package. 


The following are the options on the Connection Managers tab. 


Container 


Lists the object that contains the connection manager. 


Name 


Lists the connection manager name. 


Property name 


Lists the name of the connection manager property. 


Value 


Lists the value assigned to the connection manager property. 


Integration Services Service (SSIS Service) 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


The topics in this section discuss the Integration Services service, a Windows service for managing Integration 
Services packages. This service is not required to create, save, and run Integration Services packages. SQL 
Server 2012 (11.x) supports the Integration Services service for backward compatibility with earlier releases of 
Integration Services. 


Starting in SQL Server 2012 (11.x), Integration Services stores objects, settings, and operational data in the 
SSISDB database for projects that you've deployed to the Integration Services server using the project 
deployment model. The Integration Services server, which is an instance of the SQL Server Database Engine, 
hosts the database. For more information about the database, see SSIS Catalog. For more information about 
deploying projects to the Integration Services server, see Deploy Integration Services (SSIS) Projects and 
Packages. 


Management capabilities 


The Integration Services service is a Windows service for managing Integration Services packages. The 
Integration Services service is available only in SQL Server Management Studio. 


Running the Integration Services service provides the following management capabilities: 
e Starting remote and locally stored packages 

e Stopping remote and locally running packages 

e@ Monitoring remote and locally running packages 

e Importing and exporting packages 

e Managing package storage 

® Customizing storage folders 

e Stopping running packages when the service is stopped 

e Viewing the Windows Event log 


e Connecting to multiple Integration Services servers 


Startup type 


The Integration Services service is installed when you install the Integration Services component of SQL Server. 
By default, the Integration Services service is started and the startup type of the service is set to automatic. The 
service must be running to monitor the packages that are stored in the SSIS Package Store. The SSIS Package 

Store can be either the msdb database in an instance of SQL Server or the designated folders in the file system. 


The Integration Services service is not required if you only want to design and execute Integration Services 


packages. However, the service is required to list and monitor packages using SQL Server Management Studio. 


Manage the service 


When you install the Integration Services component of SQL Server, the Integration Services service is also 


installed. By default, the Integration Services service is started and the startup type of the service is set to 
automatic. However, you must also install SQL Server Management Studio to use the service to manage stored 


and running Integration Services packages. 


NOTE 


To connect directly to an instance of the legacy Integration Services Service, you have to use the version of SQL Server 
Management Studio (SSMS) aligned with the version of SQL Server on which the Integration Services Service is running. 
For example, to connect to the legacy Integration Services Service running on an instance of SQL Server 2016, you have 
to use the version of SSMS released for SQL Server 2016. Download SQL Server Management Studio (SSMS). 


In the SSMS Connect to Server dialog box, you cannot enter the name of a server on which an earlier version of the 
Integration Services service is running. However, to manage packages that are stored on a remote server, you do not 
have to connect to the instance of the Integration Services service on that remote server. Instead, edit the configuration 
file for the Integration Services service so that SQL Server Management Studio displays the packages that are stored on 
the remote server. 





You can only install a single instance of the Integration Services service on a computer. The service is not specific 
to a particular instance of the Database Engine. You connect to the service by using the name of the computer 
on which it is running. 


You can manage the Integration Services service by using one of the following Microsoft Management Console 
(MMC) snap-ins: SQL Server Configuration Manager or Services. Before you can manage packages in SQL 
Server Management Studio, you must make sure that the service is started. 


By default, the Integration Services service is configured to manage packages in the msdb database of the 
instance of the Database Engine that is installed at the same time as Integration Services. If an instance of the 
Database Engine is not installed at the same time, the Integration Services service is configured to manage 
packages in the msdb database of the local, default instance of the Database Engine. To manage packages that 
are stored in a named or remote instance of the Database Engine, or in multiple instances of the Database 
Engine, you have to modify the configuration file for the service. 


By default, the Integration Services service is configured to stop running packages when the service is stopped. 
However, the Integration Services service does not wait for packages to stop and some packages may continue 
running after the Integration Services service is stopped. 


If the Integration Services service is stopped, you can continue to run packages using the SQL Server Import 
and Export Wizard, the SSIS Designer, the Execute Package Utility, and the dtexec command prompt utility 
(dtexec.exe). However, you cannot monitor the running packages. 


By default, the Integration Services service runs in the context of the NETWORK SERVICE account. It is 
recommended to run the SQL Server Integration Services service under an account that has limited permissions 
such as the NETWORK SERVICE account. Running the SQL Server Integration Services service under a highly- 
priveleged account represents a potential security risk. 


The Integration Services service writes to the Windows event log. You can view service events in SQL Server 


Management Studio. You can also view service events by using the Windows Event Viewer. 


Set the properties of the service 


The Integration Services service manages and monitors packages in SQL Server Management Studio. When you 
first install SQL Server Integration Services, the Integration Services service is started and the startup type of 
the service is set to automatic. 


After the Integration Services service has been installed, you can set the properties of the service by using either 
SQL Server Configuration Manager or the Services MMC snap-in. 





To configure other important features of the service, including the locations where it stores and manages 
packages, you must modify the configuration file of the service. 


To set properties of the Integration Services service by using SQL Server Configuration Manager 


1. On the Start menu, point to All Programs, point to Microsoft SQL Server, point to Configuration 
Tools, and then click SQL Server Configuration Manager. 


2. Inthe SQL Server Configuration Manager snap-in, locate SQL Server Integration Services in the 
list of services, right-click SQL Server Integration Services, and then click Properties. 


3. In the SQL Server Integration Services Properties dialog box you can do the following: 
@ Click the Log On tab to view the logon information such as the account name. 


e Click the Service tab to view information about the service such as the name of the host 


computer and to specify the start mode of Integration Services service. 





NOTE 


The Advanced tab contains no information for Integration Services service. 





4. Click OK. 
5. On the File menu, click Exit to close the SQL Server Configuration Manager snap-in. 


To set properties of the Integration Services service by using Services 


1. In Control Panel, if you are using Classic View, click Administrative Tools, or, if you are using Category 
View, click Performance and Maintenance and then click Administrative Tools. 


2. Click Services. 


3. In the Services snap-in, locate SQL Server Integration Services in the list of services, right-click SQL 
Server Integration Services, and then click Properties. 


4. Inthe SQL Server Integration Services Properties dialog box, you can do the following: 


e Click the General tab. To enable the service, select either the manual or automatic startup type. To 
disable the service, select Disable in the Startup type box. Selecting Disable does not stop the 
service if it is currently running. 


If the service is already enabled, you can click Stop to stop the service, or click Start to start the 
service. 


e Click the Log On tab to view or edit the logon information. 


e Click the Recovery tab to view the default computer responses to service failure. You can modify 
these options to suit your environment. 


e Click the Dependencies tab to view a list of dependent services. The Integration Services service 
has no dependencies. 


5. Click OK. 


6. Optionally, if the startup type is Manual or Automatic, you can right-click SQL Server Integration 
Services and click Start, Stop, or Restart. 


7. On the File menu, click Exit to close the Services snap-in. 


Grant permissions to the service 


In previous versions of SQL Server, by default when you installed SQL Server all users in the Users group had 
access to the Integration Services service. When you install the current release of SQL Server, users do not have 
access to the Integration Services service. The service is secure by default. After SQL Server is installed, the 
administrator must grant access to the service. 


To grant access to the Integration Services service 


1. Run Dcomcnfg.exe. Dcomcnfg.exe provides a user interface for modifying certain settings in the registry. 


2. Inthe Component Services dialog, expand the Component Services > Computers > My Computer > 
DCOM Config node. 


3. Right-click Microsoft SQL Server Integration Services 13.0, and then click Properties. 
4. On the Security tab, click Edit in the Launch and Activation Permissions area. 

5. Add users and assign appropriate permissions, and then click Ok. 

6. Repeat steps 4 - 5 for Access Permissions. 

7. Restart SQL Server Management Studio. 

8. Restart the Integration Services Service. 


Event logged when permissions are missing 


If the service account of the SQL Server Agent doesn't have the Integration Services DCOM [Launch and 
Activation Permissions], the following event is added to the system event logs when the SQL Server Agent 
executes the SSIS package jobs: 


Log Name: System 

Source: **Microsoft-Windows -DistributedCOM** 

Date: 1/9/2019 5:42:13 PM 

Event ID: **100@16** 

Task Category: None 

Level: Error 

Keywords: Classic 

User: NT SERVICE\SQLSERVERAGENT 

Computer: testmachine 

Description: 

The application-specific permission settings do not grant Local Activation permission for the COM Server 
application with CLSID 

{XXXXXXXXXXXXXXXXXXXXXXXXXXKXX 

and APPID 

{XXXXXXXXXXXXXXXXXXXXXKXXXXKXX 

to the user NT SERVICE\SQLSERVERAGENT SID (S-1-5-80-344959196-2060754871- 2302487193 - 2804545603 - 1466107430) 
from address LocalHost (Using LRPC) running in the application container Unavailable SID (Unavailable). This 
security permission can be modified using the Component Services administrative tool. 


Configure the service 


When you install Integration Services, the setup process creates and installs the configuration file for the 


Integration Services service. This configuration file contains the following settings: 
e Packages are sent a stop command when the service stops. 


e The root folders to display for Integration Services in Object Explorer of SQL Server Management Studio 
are the MSDB and File System folders. 


e The packages in the file system that the Integration Services service manages are located in 
%ProgramFiles%\Microsoft SQL Server\130\DTS\Packages. 


This configuration file also specifies which msdb database contains the packages that the Integration Services 


service will manage. By default, the Integration Services service is configured to manage packages in the msdb 
database of the instance of the Database Engine that is installed at the same time as Integration Services. If an 
instance of the Database Engine is not installed at the same time, the Integration Services service is configured 
to manage packages in the msdb database of the local, default instance of the Database Engine. 


Default Configuration File Example 


The following example shows a default configuration file that specifies the following settings: 
e Packages stop running when the Integration Services service stops. 
e The root folders for package storage in Integration Services are MSDB and File System. 


e The service manages packages that are stored in the msdb database of the local, default instance of SQL 
Server. 


e The service manages packages that are stored in the file system in the Packages folder. 


Example of a Default Configuration File 


\<exml version="1.0" encoding="utf-8"?> 
\<DtsServiceConfiguration xmlns:xsd="http://www.w3.org/2001/XMLSchema”™ 
xmlns:xsi="http: //www.w3.org/2001/XMLSchema-instance"> 
<StopExecutingPackagesOnShutdown>true</StopExecutingPackagesOnShutdown> 
<TopLevelFolders> 
\<Folder xsi:type="SqlServerFolder"> 
<Name>MSDB</Name> 
<ServerName>.</ServerName> 
</Folder> 
\<Folder xsi:type="FileSystemFolder"> 
<Name>File System</Name> 
<StorePath>. .\Packages</StorePath> 
</Folder> 
</TopLevelFolders> 
</DtsServiceConfiguration> 


Modify the configuration file 


You can modify the configuration file to allow packages to continue running if the service stops, to display 
additional root folders in Object Explorer, or to specify a different folder or additional folders in the file system to 
be managed by Integration Services service. For example, you can create additional root folders of type, 
SqlServerFolder, to manage packages in the msdb databases of additional instances of Database Engine. 


NOTE 


Some characters are not valid in folder names. Valid characters for folder names are determined by the .NET Framework 
class System.1O.Path and the GetInvalidFilenameChars field. The GetInvalidFilenameChars field provides a 
platform-specific array of characters that cannot be specified in path string arguments passed to members of the Path 
class. The set of invalid characters can vary by file system. Typically, invalid characters are the quotation mark ("), less than 
(<) character, and pipe (|) character. 





However, you will have to modify the configuration file to manage packages that are stored in a named instance 
or a remote instance of Database Engine. If you do not update the configuration file, you cannot use Object 
Explorer in SQL Server Management Studio to view packages that are stored in the msdb database on the 
named instance or the remote instance. If you try to use Object Explorer to view these packages, you receive 
the following error message: 


Failed to retrieve data for this request. (Microsoft.SqlServer.SmoEnum) 





The SQL Server specified in Integration Services service configuration is not present or is not available. 
This might occur when there is no default instance of SQL Server on the computer. For more information, see 
the topic "Configuring the Integration Services Service" in SQL Server 2008 Books Online. 


Login Timeout Expired 


An error has occurred while establishing a connection to the server. When connecting to SQL Server 2008, this 
failure may be caused by the fact that under the default settings SQL Server does not allow remote 
connections. 


Named Pipes Provider: Could not open a connection to SQL Server [2]. (MsDtsSvr). 


To modify the configuration file for the Integration Services service, you use a text editor. 





IMPORTANT 


After you modify the service configuration file, you must restart the service to use the updated service configuration. 





Modified Configuration File Example 


The following example shows a modified configuration file for Integration Services. This file is for a named 


instance of SQL Server called InstanceName ON aserver named ServerName . 


Example of a Modified Configuration File for a Named Instance of SQL Server 


\<?xml version="1.0" encoding="utf-8"?> 
\<DtsServiceConfiguration xmlns:xsd="http://www.w3.org/2001/XMLSchema”™ 
xmlns:xsi="http: //www.w3.org/2001/XMLSchema-instance"> 
<StopExecutingPackagesOnShutdown>true</StopExecutingPackagesOnShutdown> 
<TopLevelFolders> 
\<Folder xsi: type="SqlServerFolder"> 
<Name>MSDB</Name> 
<ServerName>ServerName\InstanceName</ServerName> 
</Folder> 
\<Folder xsi:type="FileSystemFolder"> 
<Name>File System</Name> 
<StorePath>. .\Packages</StorePath> 
</Folder> 
</TopLevelFolders> 
</DtsServiceConfiguration> 


Modify the Configuration File Location 


The Registry key HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Microsoft SQL 
Server\130\SSIS\ServiceConfigFile specifies the location and name for the configuration file that 
Integration Services service uses. The default value of the Registry key is C:\Program Files\Microsoft SQL 
Server\130\DTS\Binn\MsDtsSrvr.ini.xml. You can update the value of the Registry key to use a different 
name and location for the configuration file. Note that the version number in the path (120 for SQL Server SQL 
Server 2014 (12.x), 130 for SQL Server 2016 (13.x), etc.) will vary depending on the SQL Server version. 


Caution 

Incorrectly editing the Registry can cause serious problems that may require you to reinstall your operating 
system. Microsoft cannot guarantee that problems resulting from editing the Registry incorrectly can be 
resolved. Before editing the Registry, back up any valuable data. For information about how to back up, restore, 
and edit the Registry, see the Microsoft Knowledge Base article, Description of the Microsoft Windows registry. 


The Integration Services service loads the configuration file when the service is started. Any changes to the 
Registry entry require that the service be restarted. 


Connect to the local service 


Before you connect to the Integration Services service, the administrator must grant you access to the service. 


To connect to the Integration Services Service 


1. Open SQL Server Management Studio. 
2. Click Object Explorer on the View menu. 
3. On the Object Explorer toolbar, click Connect, and then click Integration Services. 


4. Inthe Connect to Server dialog box, provide a server name. You can use a period (.), (local), or 
localhost to indicate the local server. 


5. Click Connect. 


Connect to a remote SSIS server 


Connecting to an instance of Integration Services on a remote server, from SQL Server Management Studio or 
another management application, requires a specific set of rights on the server for the users of the application. 





IMPORTANT 


To connect directly to an instance of the legacy Integration Services Service, you have to use the version of SQL Server 
Management Studio (SSMS) aligned with the version of SQL Server on which the Integration Services Service is running. 
For example, to connect to the legacy Integration Services Service running on an instance of SQL Server 2016, you have 
to use the version of SSMS released for SQL Server 2016. Download SQL Server Management Studio (SSMS). 


To manage packages that are stored on a remote server, you do not have to connect to the instance of the Integration 
Services service on that remote server. Instead, edit the configuration file for the Integration Services service so that SQL 
Server Management Studio displays the packages that are stored on the remote server. 





Connecting to Integration Services on a Remote Server 
To connect to Integration Services on a Remote Server 


1. Open SQL Server Management Studio. 
2. Select File, Connect Object Explorer to display the Connect to Server dialog box. 
3. Select Integration Services in the Server type list. 


4. Type the name of a SQL Server Integration Services server in the Server name text box. 


NOTE 


The Integration Services service is not instance-specific. You connect to the service by using the name of the 


computer on which the Integration Services service is running. 





5. Click Connect. 








NOTE 


The Browse for Servers dialog box does not display remote instances of Integration Services. In addition, the options 
available on the Connection Options tab of the Connect to Server dialog box, which is displayed by clicking the 
Options button, are not applicable to Integration Services connections. 











Eliminating the “Access Is Denied" Error 


When a user without sufficient rights attempts to connect to an instance of Integration Services on a remote 
server, the server responds with an "Access is denied" error message. You can avoid this error message by 


ensuring that users have the required DCOM permissions. 


To configure rights for remote users on Windows Server 2003 or Windows XP 
1. If the user is not a member of the local Administrators group, add the user to the Distributed COM Users 
group. You can do this in the Computer Management MMC snap-in accessed from the Administrative 


Tools menu. 


2. Open Control Panel, double-click Administrative Tools, and then double-click Component Services 
to start the Component Services MMC snap-in. 


3. Expand the Component Services node in the left pane of the console. Expand the Computers node, 
expand My Computer, and then click the DCOM Config node. 


4. Select the DCOM Config node, and then select SQL Server Integration Services 11.0 in the list of 
applications that can be configured. 


5. Right-click on SQL Server Integration Services 11.0 and select Properties. 
6. Inthe SQL Server Integration Services 11.0 Properties dialog box, select the Security tab. 


7. Under Launch and Activation Permissions, select Customize, then click Edit to open the Launch 


Permission dialog box. 


8. In the Launch Permission dialog box, add or delete users, and assign the appropriate permissions to 
the appropriate users and groups. The available permissions are Local Launch, Remote Launch, Local 
Activation, and Remote Activation. The Launch rights grant or deny permission to start and stop the 


service; the Activation rights grant or deny permission to connect to the service. 
9. Click OK to close the dialog box. 


10. Under Access Permissions, repeat steps 7 and 8 to assign the appropriate permissions to the 


appropriate users and groups. 
11. Close the MMC snap-in. 


12. Restart the Integration Services service. 


To configure rights for remote users on Windows 2000 with the latest service packs 


1. Run dcomcnfg.exe at the command prompt. 


2. On the Applications page of the Distributed COM Configuration Properties dialog box, select SQL 
Server Integration Services 11.0 and then click Properties. 


3. Select the Security page. 


4. Use the two separate dialog boxes to configure Access Permissions and Launch Permissions. You 
cannot distinguish between remote and local access - Access permissions include local and remote 


access, and Launch permissions include local and remote launch. 
5. Close the dialog boxes and dcomcnfg.exe. 
6. Restart the Integration Services service. 


Connecting by using a Local Account 


If you are working in a local Windows account on a client computer, you can connect to the Integration Services 
service on a remote computer only if a local account that has the same name and password and the appropriate 


rights exists on the remote computer. 


SSIS Windows service doesn't support delegation 


SSIS doesn't support the delegation of credentials, sometimes referred to as a double hop. In this scenario, 


you're working on a client computer, SSIS is installed on a second computer, and SQL Server is installed on a 


third computer. Although SSMS successfully passes your credentials from the client computer to the second 
computer (where SSIS is running), SSIS can't delegate your credentials from the second computer to the third 
computer (where SQL Server is running). 


Configure the firewall 


The Windows firewall system helps prevent unauthorized access to computer resources over a network 
connection. To access Integration Services through this firewall, you have to configure the firewall to enable 


access. 


IMPORTANT 
To manage packages that are stored on a remote server, you do not have to connect to the instance of the Integration 
Services service on that remote server. Instead, edit the configuration file for the Integration Services service so that SQL 


Server Management Studio displays the packages that are stored on the remote server. 





The Integration Services service uses the DCOM protocol. 


There are many firewall systems available. If you are running a firewall other than Windows firewall, see your 
firewall documentation for information that is specific to the system you are using. 


If the firewall supports application-level filtering, you can use the user interface that Windows provides to 
specify the exceptions that are allowed through the firewall, such as programs and services. Otherwise, you 
have to configure DCOM to use a limited set of TCP ports. The Microsoft website link previously provided 
includes information about how to specify the TCP ports to use. 


The Integration Services service uses port 135, and the port cannot be changed. You have to open TCP port 135 
for access to the service control manager (SCM). SCM performs tasks such as starting and stopping Integration 


Services services and transmitting control requests to the running service. 


The information in the following section is specific to Windows firewall. You can configure the Windows firewall 
system by running a command at the command prompt, or by setting properties in the Windows firewall dialog 
box. 


For more information about the default Windows firewall settings, and a description of the TCP ports that affect 
the Database Engine, Analysis Services, Reporting Services, and Integration Services, see Configure the 
Windows Firewall to Allow SQL Server Access. 

Configuring a Windows firewall 


You can use the following commands to open TCP port 135, add MsDtsSrvr.exe to the exception list, and specify 
the scope of unblocking for the firewall. 


To configure a Windows firewall using the Command Prompt window 


1. Run the following command: 


netsh firewall add portopening protocol=TCP port=135 name="RPC (TCP/135)" mode=ENABLE scope=SUBNET 


2. Run the following command: 


netsh firewall add allowedprogram program="%ProgramFiles%\Microsoft SQL 
Server\100\DTS\Binn\MsDtsSrvr.exe" name="SSIS Service" scope=SUBNET 








NOTE 


To open the firewall for all computers, and also for computers on the Internet, replace scope=SUBNET with 


scope=ALL. 








The following procedure describes how to use the Windows user interface to open TCP port 135, add 


MsDtsSrvr.exe to the exception list, and specify the scope of unblocking for the firewall. 


To configure a firewall using the Windows firewall dialog box 


1. 


2. 


In the Control Panel, double-click Windows Firewall. 


In the Windows Firewall dialog box, click the Exceptions tab and then click Add Program. 


. Inthe Add a Program dialog box, click Browse, navigate to the Program Files\Microsoft SQL 


Server\100\DTS\Binn folder, click MsDtsSrvr.exe, and then click Open. Click OK to close the Add a 
Program dialog box. 


. On the Exceptions tab, click Add Port. 


. Inthe Add a Port dialog box, type RPC(TCP/135) or another descriptive name in the Name box, type 
135 in the Port Number box, and then select TCP. 





IMPORTANT 


Integration Services service always uses port 135. You cannot specify a different port. 





. Inthe Add a Port dialog box, you can optionally click Change Scope to modify the default scope. 


. Inthe Change Scope dialog box, select My network (subnet only) or type a custom list, and then click 


OK. 


. To close the Add a Port dialog box, click OK. 


. To close the Windows Firewall dialog box, click OK. 





NOTE 


To configure the Windows firewall, this procedure uses the Windows Firewall item in Control Panel. The 
Windows Firewall item only configures the firewall for the current network location profile. However, you can 
also configure the Windows firewall by using the netsh command line tool or the Microsoft Management Console 
(MMC) snap-in named Windows firewall with Advanced Security. For more information about these tools, see 


Configure the Windows Firewall to Allow SQL Server Access. 








Package Management (SSIS Service) 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Package management includes monitoring, managing, importing and exporting packages. 


Package Store 
Integration Services provides two top-level folders for accessing packages: 


e Running Packages 


e Stored Packages 


The Running Packages folder lists the packages that are currently running on the server. The Stored 
Packages folder lists the packages that are saved in the package store. These are the only packages that the 
Integration Services service manages. The package store can consist of either or both the msdb database and 
file system folders listed in the Integration Services service configuration file. The configuration file specifies the 
msdb and file system folders to manage. You might also have packages stored elsewhere in the file system that 
are not managed by the Integration Services service. 


Packages you save to msdb are stored in a table named sysssispackages. When you save packages to msdb, you 
can group them in logical folders. Using logical folders can help you organize packages by purpose, or filter 
packages in the sysssispackages table. Create new logical folders in SQL Server Management Studio. By default, 
any logical folders that you add to msdb are automatically included in the package store. 


The logical folders you create are represented as rows in the sysssispackagefolders table in msdb. The folderid 
and parentfolderid columns in sysssispackagefolders define the folder hierarchy. The root logical folders in 
msdb are the rows in sysssispackagefolders with null values in the parentfolderid column. For more 
information, see sysssispackages (Transact-SQL) and sysssispackagefolders (Transact-SQL&). 


When you open SQL Server Management Studio and connect to Integration Services, you will see the msdb 
folders that Integration Services service manages listed within the Stored Packages folder. If the configuration 
file specifies root file system folders, the Stored Packages folder also lists packages saved to the file system in 
those folders and in all subfolders. 


You can store packages in any file system folder, but they will not be listed in subfolders of the Stored 
Packages folder unless you add the folder to the list of folders in the configuration file for the package store. 
For more information about the configuration file, see Integration Services Service (SSIS Service). 


The Running Packages folder contains no subfolders and it is not extensible. 


By default, the Stored Packages folder contains two folders: File System and MSDB. The File System folder 
lists the packages that are saved to the file system. The location of these files is specified in the configuration file 
for the Integration Services service. The default folder is the Packages folder, located in %Program 
Files%\Microsoft SQL Server\100\DTS. The MSDB folder lists the Integration Services packages that have been 
saved to the SQL Server msdb database on the server. The sysssispackages table contains the packages saved to 
msdb. 


To view the list of packages in the package store, you must open SQL Server Management Studio and connect to 
Integration Services. 


Monitor running packages 


The Running Packages folder lists packages currently running. To view information about current packages on 
the Summary page of SQL Server Management Studio, click the Running Packages folder. Information such 
as the execution duration of running packages is listed on the Summary page. Optionally, refresh the folder to 
display the most current information. 


To view information about a single running package on the Summary page, click the package. The Summary 
page displays information such as the version and description of the package. 


Stop a running package from the Running Packages folder by right-clicking the package and then clicking 
Stop. 


View packages in SSMS 


This procedure describes how to connect to Integration Services in SQL Server Management Studio and view a 
list of the packages that the Integration Services service manages. 


To connect to Integration Services 


1. Click Start, point to All Programs, point to Microsoft SQL Server, and then click SQL Server 
Management Studio. 


2. Inthe Connect to Server dialog box, select Integration Services in the Server type list, provide a 
server name in the Server name box, and then click Connect. 


IMPORTANT 


If you cannot connect to Integration Services, the Integration Services service is likely not running. To learn the 
status of the service, click Start, point to All Programs, point to Microsoft SQL Server, point to 
Configuration Tools, and then click SQL Server Configuration Manager. In the left pane, click SQL Server 
Services. In the right pane, find the Integration Services service. Start the service if it is not already running. 








SQL Server Management Studio opens. By default the Object Explorer window is open and positioned in 
the lower-left corner of the studio. If Object Explorer is not open, click Object Explorer on the View 
menu. 


To view the packages that Integration Services service manages 


1. In Object Explorer, expand the Stored Packages folder. 


2. Expand the Stored Packages subfolders to show packages. 


Import and export packages 
Packages can be saved either in the sysssispackages table in the SQL Server msdb database or in the file system. 


The package store, which is the logical storage that Integration Services service monitors and manages, can 
include both the msdb database and the file system folders specified in the configuration file for the Integration 
Services service. 


You can import and export packages between the following storage types: 
e File system folders anywhere in the file system. 
e Folders in the SSIS Package Store. The two default folders are named File System and MSDB. 


e The SQL Server msdb database. 


Integration Services gives you the ability to import and export packages, and by doing this change the storage 
format and location of packages. Using the import and export features, you can add packages to the file system, 
package store, or msdb database, and copy packages from one storage format to another. For example, 
packages saved in msdb can be copied to the file system and vice versa. 


You can also copy a package to a different format using the dtutil command prompt utility (dtutil.exe). For more 
information, see dtutil Utility. 


You can import or export an Integration Services package from or to the following locations: 


e You can import a package that is stored in an instance of Microsoft SQL Server, in the file system, or in 
the SSIS package store. The imported package is saved to SQL Server or to a folder in the SSIS package 
store. 


e You can export a package that is stored in an instance of SQL Server, the file system, or the SSIS Package 
Store to a different storage format and location. 


However, there are some restrictions on importing and exporting a package between different versions of SQL 
Server: 


e Onan instance of SQL Server 2008, you can import packages from an instance of SQL Server 2005 (9.x), 
but you cannot export packages to an instance of SQL Server 2005 (9.x). 


e Onan instance of SQL Server 2005 (9.x), you cannot import packages from, or export packages to, an 
instance of SQL Server 2008. 


The following procedures describe how to use SQL Server Management Studio to import or export a package. 


To import a package by Using SQL Server Management Studio 
1. Click Start, point to Microsoft SQL Server, and then click SQL Server Management Studio. 


2. Inthe Connect to Server dialog box set the following options: 
e Inthe Server type box, select Integration Services. 


e Inthe Server name box, provide a server name or click <Browse for more...> and locate the 
server to use. 


3. If Object Explorer is not open, on the View menu, click Object Explorer. 

4. In Object Explorer, expand the Stored Packages folder. 

5. Expand the subfolders to locate the folder into which you want to import a package. 
6. Right-click the folder, click Import Package. and then do one of the following: 


e Toimport from an instance of SQL Server, select the SQL Server option, and then specify the 
server and select the authentication mode. If you select SQL Server Authentication, provide a user 
name and a password. 


Click the browse button (...), select the package to import, and then click OK. 
e Toimport from the file system, select the File system option. 
Click the browse button (...), select the package to import, and then click Open. 


e Toimport from the SSIS Package Store, select the SSIS Package Store option and specify the 
server. 


Click the browse button (...), select the package to import, and then click OK. 


7. Optionally, update the package name. 


8. To update the protection level of the package, click the browse button (...) and choose a different 
protection level by using the Package Protection Level dialog box. If the Encrypt sensitive data 
with password or the Encrypt all data with password option is selected, type and confirm a 
password. 


9. Click OK to complete the import. 


To export a package by Using SQL Server Management Studio 
1. Click Start, point to Microsoft SQL Server, and then click SQL Server Management Studio. 


2. Inthe Connect to Server dialog box, set the following options: 
e Inthe Server type box, select Integration Services. 


e Inthe Server name box, provide a server name or click <Browse for more...> and locate the 
server to use. 


3. If Object Explorer is not open, on the View menu, click Object Explorer. 
4. In Object Explorer, expand the Stored Packages folder. 

5. Expand the subfolders to locate the package you want to export. 

6. Right-click the package, click Export, and then do one of the following: 


e To export to an instance of SQL Server, select the SQL Server option, and then specify the server 
and select the authentication mode. If you select SQL Server Authentication, provide a user name 
and a password. 


Click the browse button (...), and expand the SSIS Packages folder to locate the folder to which 
you want to save the package. Optionally, update the default name of the package, and then click 
OK. 


e To export to the file system, select the File System option. 


Click the browse button (...) to locate the folder to which you want to export the package, type the 
name of the package file, and then click Save. 


e To export to the SSIS package store, select the SSIS Package Store option, and specify the server. 


Click the browse button (...), expand the SSIS Packages folder, and select the folder to which you 
want to save the package. Optionally, enter a new name for the package in the Package Name 
text box. Click OK. 


7. To update the protection level of the package, click the browse button (...) and choose a different 
protection level by using the Package Protection Level dialog box. If the Encrypt sensitive data 
with password or the Encrypt all data with password option is selected, type and confirm a 
password. 


8. Click OK to complete the export. 


Import Package Dialog Box UI Reference 


Use the Import Package dialog box, available in SQL Server Management Studio, to import a Integration 
Services package and to set or modify the protection level of the package. 


Options 
Package location 
Select the type of storage location to import the package to. The following options are available: 


SQL Server 
File System 
SSIS Package Store 


Server 


Type a server name or select a server from the list. 


Authentication 
Select Windows Authentication or SQL Server Authentication. This option is available only if the storage location 
is SQL Server. 





IMPORTANT 


Whenever possible, use Windows Authentication. 











Authentication type 
Select an authentication type. 


User name 
If using SQL Server Authentication, provide a user name. 


Password 
If using SQL Server Authentication, provide a password. 


Package path 
Type the package path, or click the browse button (...) and locate the package. 


Package name 
Optionally, rename the package. The default name is the name of the package to import. 


Protection level 
Click the browse button (...) and, in the Package Protection Level dialog box, update the protection level. For 
more information, see Package and Project Protection Level Dialog Box. 


Export Package Dialog Box UI Reference 


Use the Export Package dialog box, available in SQL Server Management Studio, to export a Integration 
Services package to a different location and optionally, modify the protection level of the package. 


Options 
Package location 
Select the type of storage to export the package to. The following options are available: 


SQL Server 
File System 
SSIS Package Storage 


Server 


Type a server name or select a server from the list. 


Authentication 
Select Windows Authentication or SQL Server Authentication. This option is available only if the storage location 
is SQL Server. 





IMPORTANT 


Whenever possible, use Windows Authentication. 





Authentication type 


Select an authentication type. 


User name 


If using SQL Server Authentication, provide a user name. 


Password 


If using SQL Server Authentication, provide a password. 


Package path 
Type the package path, or click the browse button (...) and locate the folder in which to store the package. 


Protection level 
Click the browse button (...) and update the protection level in the Package Protection Level dialog box. For 
more information, see Package and Project Protection Level Dialog Box. 


Back up and restore packages 


SQL Server Integration Services packages can be saved to the file system or msdb, a SQL Server system 
database. Packages saved to msdb can be backed up and restored using SQL Server backup and restore 
features. 


For more information about backing up and restoring the msdb database, click one of the following topics: 
e Back Up and Restore of SQL Server Databases 
e Back Up and Restore of System Databases (SQL Server) 


Integration Services includes the dtutil command-prompt utility (dtutil.exec), which you can use to manage 
packages. For more information, see dtutil Utility. 


Configuration Files 


Any configuration files that the packages include are stored in the file system. These files are not backed up 
when you back up the msdb database; therefore, you should make sure that the configuration files are backed 
up regularly as part of your plan for securing packages saved to msdb. To include configurations in the backup 
of the msdb database, you should consider using the SQL Server configuration type instead of file-based 
configurations. 


Packages Stored in the File System 

The backup of packages that are saved to the file system should be included in the plan for backing up the file 
system of the server. The Integration Services service configuration file, which has the default name 
MsDtsSrvrini.xml, lists the folders on the server that the service monitors. You should make sure these folders 
are backed up. Additionally, packages may be stored in other folders on the server and you should make sure to 
include these folders in the backup. 


See Also 
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Events Logged by the Integration Services Service 





Applies to: Q sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


The Integration Services service logs various messages to the Windows Application event log. The service logs 


these messages when the service starts, when the service stops, and when certain problems occur. 


This topic provides information about the common event messages that the service logs to the Application 


event log. The Integration Services service logs all the messages described in this topic with an Event Source of 


SQLISService. 


For general information about the Integration Services service, see Integration Services Service (SSIS Service). 


Service status messages 


When you select Integration Services for installation, the Integration Services service is installed and started, 


and its Startup Type is set to Automatic. 


EVENT ID 


256 


257 


260 


258 


259 


SYMBOLIC NAME 


DTS_MSG_SERVER_STARTIN 
G 


DTS_MSG_SERVER_STARTED 


DTS_MSG_SERVER_START_F 
AILED 


DTS_MSG_SERVER_STOPPIN 
G 


DTS_MSG_SERVER_STOPPE 
D 


Settings file messages 


TEXT 


Starting Microsoft SSIS 
Service. 


Microsoft SSIS Service 
started. 


Microsoft SSIS Service failed 
to start.%nError: %1 


Stopping Microsoft SSIS 
Service.%n%nStop all 
running packages on exit: 
%1 


Microsoft SSIS Service 
stopped.%nServer version 
%I1 


NOTES 


The service is about to 
start. 


The service started. 


The service was not able to 
start. This inability to start 
might be the result of a 
damaged installation or an 
inappropriate service 
account. 


The service is stopping, and 
if you configure the service 
to do this, will stop all 
running packages. You can 
set a true or false value in 
the configuration file that 
determines whether the 
service stops running 
packages when the service 
itself stops. The message for 
this event includes the 
value of this setting. 


The service stopped. 


Settings for the Integration Services service are stored in an XML file that you can modify. For more information, 


see Integration Services Service (SSIS Service). 


Other messages 


View events 


There are two tools in which you can view events for the Integration Services service: 


EVENT ID 


274 


272 


273 


EVENT ID 


336 


SYMBOLIC NAME 


DTS_MSG_SERVER_MISSING 
_CONFIG_REG 


DTS_MSG_SERVER_MISSING 
_CONFIG 


DTS_MSG_SERVER_BAD_CO 
NFIG 


SYMBOLIC NAME 


DTS_MSG_SERVER_STOPPIN 
G_PACKAGE 


TEXT 


Microsoft SSIS Service: 
YnRegistry setting 
specifying configuration file 
does not exist. 
Y%nAttempting to load 
default config file. 


Microsoft SSIS Service 
configuration file does not 
exist.%nLoading with 
default settings. 


Microsoft SSIS Service 
configuration file is 
incorrect.%nError reading 
config file: %1%n%nLoading 
server with default settings. 


TEXT 


Microsoft SSIS Service: 
stopping running 
package.%nPackage 
instance ID: %1%nPackage 
ID: %2%nPackage name: 
%3%nPackage description: 
%A%Y%nPackage 


NOTES 


The Registry entry that 
contains the path of the 
configuration file does not 
exist or is empty. 


The configuration file itself 
does not exist at the 
specified location. 


The configuration file could 
not be read or is not valid. 
This error might be the 
result of an XML syntax 
error in the file. 


NOTES 


The service is trying to stop 
a running package. You can 
monitor and stop running 
packages in Management 
Studio. For information 
about how to manage 
packages in Management 
Studio, see Package 
Management (SSIS Service). 


The Log File Viewer dialog box in SQL Server Management Studio. The Log File Viewer dialog box 


includes options to export, filter, and search the log. For more information about the options in the Log 


File Viewer, see Log File Viewer F1 Help. 


The Windows Event Viewer. 


For descriptions of the events logged by the Integration Services service, see Events Logged by the Integration 


Services Service. 


To view service events for Integration Services in SQL Server Management Studio 


il: 


Open SQL Server Management Studio. 


. On the File menu, click Connect Object Explorer. 


server to connect to, and then click Connect. 


In Object Explorer, right-click Integration Services and click View Logs. 


. Inthe Connect to Server dialog box, select the Integration Services server type, select or locate the 


5. To view Integration Services events, select SQL Server Integration Services. The NT Events option is 
automatically selected and cleared with the SQL Server Integration Services option. 


To view service events for Integration Services in Windows Event Viewer 


1. In Control Panel, if you are using Classic View, click Administrative Tools, or, if you are using Category 
View, click Performance and Maintenance and then click Administrative Tools. 


2. Click Event Viewer. 
3. In the Event Viewer dialog box, click Application. 


4. In the Application snap-in, locate an entry in the Source column that has the value SQLISService, 
right-click the entry, and then click Properties. 


5. Optionally, click the up or down arrow to show the previous or next event. 
6. Optionally, click the Copy to Clipboard icon to copy the event information. 
7. Choose to display event data using bytes or words. 

8. Click OK. 


9. On the File menu, click Exit to close the Event Viewer dialog box. 


Related Tasks 


For information about how to view log entries, see Events Logged by an Integration Services Package 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Clustering Integration Services is not recommended because the Integration Services service is not a clustered 
or cluster-aware service, and does not support failover from one cluster node to another. Therefore, in a 
clustered environment, Integration Services should be installed and started as a stand-alone service on each 
node in the cluster. 


Although the Integration Services service is not a clustered service, you can manually configure the service to 
operate as a cluster resource after you install Integration Services separately on each node of the cluster. 


However, if high availability is your goal in establishing a clustered hardware environment, you can achieve this 
goal without configuring the Integration Services service as a cluster resource. To manage your packages on any 
node in the cluster from any other node in the cluster, modify the configuration file for the Integration Services 
service on each node in the cluster. You modify each of these configuration files to point to all available instances 
of SQL Server on which packages are stored. This solution provides the high availability that most customers 
need, without the potential problems encountered when the Integration Services service is configured as a 
cluster resource. For more information about how to change the configuration file, see Integration Services 
Service (SSIS Service). 


Understanding the role of the Integration Services service is critical to making an informed decision about how 
to configure the service in a clustered environment. For more information, see Integration Services Service 
(SSIS Service). 


Disadvantages 


Some of the potential disadvantages of configuring the Integration Services service as a cluster resource include 
the following: 


e When a failover occurs, running packages do not restart. 


You can recover from package failures by restarting packages from checkpoints. You can restart from 
checkpoints without configuring the service as a cluster resource. For more information, see Restart 
Packages by Using Checkpoints. 


e When you configure the Integration Services service in a different resource group from SQL Server, you 
cannot use Management Studio from client computers to manage packages that are stored in the msdb 
database. The Integration Services service cannot delegate credentials in this double-hop scenario. 


e@ When you have multiple SQL Server resource groups that include the Integration Services service in a 
cluster, a failover could lead to unexpected results. Consider the following scenario. Group1, which 
includes the SQL Server service and the Integration Services service, is running on Node A. Group2, 
which also includes the SQL Server service and the Integration Services service, is running on Node B. 
Group 2 fails over to Node A. The attempt to start another instance of the Integration Services service on 
Node A fails because the Integration Services service is a single-instance service. Whether the SQL 
Server service that is trying to fail over to Node A also fails depends on the configuration of the 
Integration Services service in Group 2. If the Integration Services service was configured to affect the 
other services in the resource group, the SQL Server service that is failing over will fail because the 
Integration Services service failed. If the service was configured not to affect the other services in the 
resource group, the SQL Server service will be able to fail over to Node A.Unless the Integration Services 


service in Group 2 was configured not to affect the other services in the resource group, the failure of the 
Integration Services service that is failing over could cause the SQL Server service that is failing over to 
fail also. 


Configure the Service as a Cluster Resource 


For those customers who conclude that the advantages of configuring the Integration Services service as a 
cluster resource outweigh the disadvantages, this section contains the necessary configuration instructions. 
However, Microsoft does not recommend that the Integration Services service be configured as a cluster 
resource. 


To configure the Integration Services service as a cluster resource, you need to complete the following tasks. 
e Install Integration Services on a cluster. 


To install Integration Services on a cluster, you must install Integration Services on each node in the 
cluster. 


e Configure Integration Services as a cluster resource. 


With Integration Services installed on each node in the cluster, you need to configure Integration Services 
as a cluster resource. When you configure the Integration Services service as a cluster resource, you can 
add the service to the same resource group as the SQL Server Database Engine, or to a different group. 


The following table describes the possible advantages and disadvantages in selecting a resource group. 


WHEN INTEGRATION SERVICES AND SQL SERVER ARE IN WHEN INTEGRATION SERVICES AND SQL SERVER ARE IN 


THE SAME RESOURCE GROUP DIFFERENT RESOURCE GROUPS 

Client computers can use SQL Server Management Client computers cannot use SQL Server Management 
Studio to manage packages stored in the msdb database Studio to manage packages stored in the msdb 

because both the SQL Server Database Engine and database. The client can connect to the virtual server on 
Integration Services service are running on the same which the Integration Services service is running. 

virtual server. This configuration avoids the delegation However, that computer cannot delegate the user's 
issues of the double-hop scenario. credentials to the virtual server on which SQL Server is 


running. This is known as a double-hop scenario. 


The Integration Services service competes with other The Integration Services service does not compete with 
SQL Server services for CPU and other computer other SQL Server services for CPU and other computer 
resources. resources because the different resource groups are 


configured on different nodes. 


The loading and saving of packages to the msdb The loading and saving of packages to the msdb 
database is faster and generates less network traffic database might be slower and generate more network 
because both services are running on the same traffic. 

computer. 

Both services are online or offline at the same time. The Integration Services service might be online while 


the SQL Server Database Engine is offline. Thus, the 
packages stored in the msdb database of the SQL Server 
Database Engine are unavailable. 


The Integration Services service cannot be moved The Integration Services service can be moved more 
quickly to another node if it is required. quickly to another node if it is required. 


After you have decided to which resource group you will add Integration Services, you have to configure 
Integration Services as a cluster resource in that group. 


e Configure the Integration Services service and package store. 


Having configured Integration Services as a cluster resource, you must modify the location and the 
content of the configuration file for the Integration Services service on each node in the cluster. These 
modifications make both the configuration file and the package store available to all nodes if there is a 
failover. After you modify the location and content of the configuration file, you have to bring the service 
online. 


e Bring the Integration Services service online as a cluster resource. 


After configuring the Integration Services service on a cluster, or on any server, you might have to configure 
DCOM permissions before you can connect to the service from a client computer. For more information, see 
Integration Services Service (SSIS Service). 


The Integration Services service cannot delegate credentials. Therefore, you cannot use Management Studio to 
manage packages stored in the msdb database when the following conditions are true: 


e The Integration Services service and SQL Server are running on separate servers or virtual servers. 
e The client that is running SQL Server Management Studio is a third computer. 


The client can connect to the virtual server on which the Integration Services service is running. However, that 
computer cannot delegate the user's credentials to the virtual server on which SQL Server is running. This is 


known as a double-hop scenario. 


To Install Integration Services on a Cluster 


1. Install and configure a cluster with one or more nodes. 
2. (Optional) Install clustered services, such as the SQL Server Database Engine. 
3. Install Integration Services on each node of the cluster. 


To Configure Integration Services as a Cluster Resource 


1. Open the Cluster Administrator. 
2. In the console tree, select the Groups folder. 
3. In the results pane, select the group to which you plan to add Integration Services: 


e To add Integrations Services as a cluster resource to the same resource group as SQL Server, select 
the group to which SQL Server belongs. 


e To add Integrations Services as a cluster resource to a different group than SQL Server, select a 
group other than the group to which SQL Server belongs. 


4. On the File menu, point to New, and then click Resource. 


5. On the New Resource page of the Resource Wizard, type a name and select "Generic Service" as the 
Service Type. Do not change the value of Group. Click Next. 


6. On the Possible Owners page, add or remove the nodes of the cluster as the possible owners of the 
resource. Click Next. 


—N 


. To add dependencies, on the Dependencies page, select a resource under Available resources, and 
then click Add. In case of a failover, both SQL Server and the shared disk that stores Integration Services 
packages should come back online before Integration Services is brought online. After you have selected 
the dependencies, click Next. 


For more information, see Add Dependencies to a SQL Server Resource. 


8. On the Generic Service Parameters page, enter MsDtsServer as the name of the service. Click Next. 


oO 


. On the Registry Replication page, click Add to add the registry key that identifies the location of the 


configuration file for the Integration Services service. This file must be located on a shared disk that is in 
the same resource group as the Integration Services service. 


10. In the Registry Key dialog box, type SOFTWARE\Microsoft\Microsoft SQL 
Server\100\SSIS\ServiceConfigFile. Click OK, and then click Finish. 


The Integration Services service has now been added as a cluster resource. 


To Configure the Integration Services Service and Package Store 


1. Locate the configuration file at %ProgramFiles%\Microsoft SQL Server\100\DTS\Binn\MsDtsSrvrinixml. 
Copy it to the shared disk for the group to which you added the Integration Services service. 


2. On the shared disk, create a new folder named Packages to serve as the package store. Grant List 
Folders and Write permissions on the new folder to appropriate users and groups. 


3. On the shared disk, open the configuration file in a text or XML editor. Change the value of the 


ServerName element to the name of the virtual SQL Server that is in the same resource group. 


4. Change the value of the StorePath element to the fully-qualified path of the Packages folder created on 
the shared disk in a previous step. 


5. On each node, update the value of HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Microsoft SQL 
Server\100\SSIS\ServiceConfigFile in the Registry to the fully-qualified path and file name of the 
service configuration file on the shared disk. 


To bring the Integration Services service online 


e Inthe Cluster Administrator, select the Integration Services service, right-click, and select Bring Online 


from the popup menu. The Integration Services service is now online as a cluster resource. 
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Security in SQL Server Integration Services consists of several layers that provide a rich and flexible security 


environment. These security layers include the use of digital signatures, package properties, SQL Server 


database roles, and operating system permissions. Most of these security features fall into the categories of 


identity and access control. 


Threat and Vulnerability Mitigation 


Although Integration Services includes a variety of security mechanisms, packages and the files that packages 


create or use could be exploited for malicious purposes. 


The following table describes these risks and the proactive steps that you can take to lessen the risks. 


THREAT OR VULNERABILITY 


Package source 


Package contents 


DEFINITION 


The source of a package is the 
individual or organization that created 
the package. Running a package from 
an unknown or untrusted source 
might be risky. 


Package contents include the elements 
in the package and their properties. 
The properties can contain sensitive 
data such as a password or a 
connection string. Package elements 
such as an SQL statement can reveal 
the structure of your database. 


MITIGATION 


Identify the source of a package by 
using a digital signature, and run 
packages that come from only known, 
trusted sources. For more information, 
see Identify the Source of Packages 
with Digital Signatures. 


Control access to a package and to the 
contents by doing the following steps: 


1) To control access to the package 
itself, apply SQL Server security 
features to packages that are saved to 
the msdb database in an instance of 
SQL Server. To packages that are saved 
in the file system, apply file system 
security features, such as access 
controls lists (ACLs). 


2) To control access to the package's 
contents, set the protection level of 
the package. 


For more information, see Security 
Overview (Integration Services) and 
Access Control for Sensitive Data in 
Packages. 


THREAT OR VULNERABILITY 


Package output 


DEFINITION 


When you configure a package to use 
configurations, checkpoints, and 
logging, the package stores this 
information outside the package. The 
information that is stored outside the 
package might contain sensitive data. 


MITIGATION 


To protect configurations and logs that 
the package saves to SQL Server 
database tables, use SQL Server 
security features. 


To control access to files, use the 


access control lists (ACLs) available in 
the file system. 


For more information, see Access to 
Files Used by Packages 


Identity Features 
By implementing identity features in your packages, you can achieve the following goal: 
Ensure that you only open and run packages from trusted sources. 


To ensure that you only open and run packages from trusted sources, you first have to identify the source of 
packages. You can identify the source by signing packages with certificates. Then, when you open or run the 
packages, you can have Integration Services check for the presence and the validity of the digital signatures. For 
more information, see Identify the Source of Packages with Digital Signatures. 


Access Control Features 
By implementing identity features in your packages, you can achieve the following goal: 
Ensure that only authorized users open and run packages. 


To ensure that only authorized users open and run packages, you have to control access to the following 
information: 


e Control access to the contents of packages, especially sensitive data. 
e Control access to packages and package configurations that are stored in SQL Server. 


e Control access to packages and to related files such as configurations, logs, and checkpoint files that are 
stored in the file system. 


e Control access to the Integration Services service and to the information about packages that the service 
displays in SQL Server Management Studio. 


Controlling Access to the Contents of Packages 


To help restrict access to the contents of a package, you can encrypt packages by setting the ProtectionLevel 
property of the package. You can set this property to the level of protection that your package requires. For 
example, in a team development environment, you can encrypt a package by using a password that is known 


only to the team members who work on the package. 


When you set the ProtectionLevel property of a package, Integration Services automatically detects sensitive 
properties and handles these properties according to the specified package protection level. For example, you 
set the ProtectionLevel property for a package to a level that encrypts sensitive information with a password. 
For this package, Integration Services automatically encrypts the values of all sensitive properties and will not 
display the corresponding data without the correct password being supplied. 


Typically, Integration Services identifies properties as sensitive if those properties contain information, such as a 
password or a connection string, or if those properties correspond to variables or task-generated XML nodes. 


Whether Integration Services considers a property sensitive depends on whether the developer of the 
Integration Services component, such as a connection manager or task, has designated the property as 
sensitive. Users cannot add properties to, nor can they remove properties from, the list of properties that are 
considered sensitive.lf you write custom tasks, connection managers, or data flow components, you can specify 
which properties Integration Services should treat as sensitive. 


For more information, see Access Control for Sensitive Data in Packages. 


Controlling Access to Packages 


You can save Integration Services packages to the msdb database in an instance of SQL Server, or to the file 
system as XML files that have the .dtsx file name extension. For more information, see Save Packages. 


Saving Packages to the msdb Database 

Saving the packages to the msdb database helps provide security at the server, database, and table levels. In the 
msdb database, Integration Services packages are stored in the sysssispackages table. Because the packages are 
saved to the sysssispackages and sysdtspackages tables in the msdb database, the packages are automatically 
backed up when you backup the msdb database. 


SQL Server packages stored in the msdb database can also be protected by applying the Integration Services 
database-level roles. Integration Services includes three fixed database-level roles db_ssisadmin, db_ssisltduser, 
and db_ssisoperator for controlling access to packages. A reader and a writer role can be associated with each 
package. You can also define custom database-level roles to use in Integration Services packages. Roles can be 
implemented only on packages that are saved to the msdb database in an instance of SQL Server. For more 
information, see Integration Services Roles (SSIS Service). 


Saving Packages to the File System 
If you store packages to the file system instead of in the msdb database, make sure to secure the package files 
and the folders that contain package files. 


Controlling Access to Files Used by Packages 


Packages that have been configured to use configurations, checkpoints, and logging generate information that is 
stored outside the package. This information might be sensitive and should be protected. Checkpoint files can be 
saved only to the file system, but configurations and logs can be saved to the file system or to tables in a SQL 
Server database. Configurations and logs that are saved to SQL Server are subject to SQL Server security, but 
information written to the file system requires additional security. 


For more information, see Access to Files Used by Packages. 


Storing Package Configurations Securely 


Package configurations can be saved to a table in a SQL Server database or to the file system. 


Configurations can be saved to any SQL Server database, not just the msdb database. Thus, you are able to 
specify which database serves as the repository of package configurations. You can also specify the name of the 
table that will contain the configurations, and Integration Services automatically creates the table with the 
correct structure. Saving the configurations to a table makes it possible to provide security at the server, 
database, and table levels. In addition, configurations that are saved to SQL Server are automatically backed up 
when you back up the database. 


If you store configurations in the file system instead of in SQL Server, make sure to secure the folders that 
contain the package configuration files. 


For more information about configurations, see Package Configurations. 


Controlling Access to the Integration Services Service 
SQL Server Management Studio uses the SQL Server service to list stored packages. To prevent unauthorized 
users from viewing information about packages that are stored on local and remote computers, and thereby 


learning private information, restrict access to computers that run the SQL Server service. 


For more information, see Access to the Integration Services Service. 


Access to Files Used by Packages 


The package protection level does not protect files that are stored outside the package. These files include the 
following: 


e Configuration files 

e Checkpoint files 

e Log files 

These files must be protected separately, especially if they include sensitive information. 


Configuration Files 


If you have sensitive information in a configuration, such as login and password information, you should 
consider saving the configuration to SQL Server, or use an access control list (ACL) to restrict access to the 
location or folder where you store the files and allow access only to certain accounts. Typically, you would grant 
access to the accounts that you permit to run packages, and to the accounts that manage and troubleshoot 
packages, which may include reviewing the contents of configuration, checkpoint, and log files. SQL Server 
provides the more secure storage because it offers protection at the server and database levels. To save 
configurations to SQL Server, you use the SQL Server configuration type. To save to the file system, you use the 
XML configuration type. 


For more information, see Package Configurations, Create Package Configurations, and Security Considerations 
for a SQL Server Installation. 


Checkpoint Files 


Similarly, if the checkpoint file that the package uses includes sensitive information, you should use an access 
control list (ACL) to secure the location or folder where you store the file. Checkpoint files save current state 
information on the progress of the package as well as the current values of variables. For example, the package 
may include a custom variable that contains a telephone number. For more information, see Restart Packages by 
Using Checkpoints. 


Log Files 

Log entries that are written to the file system should also be secured using an access control list (ACL). Log 
entries can also be stored in SQL Server tables and protected by SQL Server security. Log entries may include 
sensitive information, For example, if the package contains an Execute SQL task that constructs an SQL 
statement that refers to a telephone number, the log entry for the SQL statement includes the telephone 
number. The SQL statement may also reveal private information about table and column names in databases. 


For more information, see Integration Services (SSIS) Logging. 


Access to the Integration Services Service 


Package protection levels can limit who is allowed to edit and execute a package. Additional protection is needed 
to limit who can view the list of packages currently running on a server and who can stop currently executing 
packages in SQL Server Management Studio. 


SQL Server Management Studio uses the SQL Server service to list running packages. Members of the Windows 
Administrators group can view and stop all currently running packages. Users who are not members of the 
Administrators group can view and stop only packages that they started. 


It is important to restrict access to computers that run an SQL Server service, especially an SQL Server service 
that can enumerate remote folders. Any authenticated user can request the enumeration of packages. Even if the 
service does not find the service, the service enumerates folders. These folder names may be useful to a 


malicious user. If an administrator has configured the service to enumerate folders on a remote machine, users 
may also be able to see folder names that they would normally not be able to see. 


Related Tasks 


The following list contains links to topics that show you how to perform a certain task pertaining to the security. 
e Create a User-Defined Role 

e Assign a Reader and Writer Role to a Package 

e Implement a Signing Policy by Setting a Registry Value 

e Sign a Package by Using a Digital Certificate 


e Set or Change the Protection Level of Packages 


Access Control for Sensitive Data in Packages 
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To protect the data in an Integration Services package, you can set a protection level that helps protect just 
sensitive data or all the data in the package. Furthermore, you can encrypt this data with a password or a user 
key, or rely on the database to encrypt the data. Also, the protection level that you use for a package is not 
necessarily static, but changes throughout the life cycle of the package. You often set one protection level during 
development and another as soon as you deploy the package. 


NOTE 


In addition to the protection levels described in this topic, you can use fixed database-level roles to protect packages that 
are saved to the Integration Services server. 











Definition of Sensitive Information 


In an Integration Services package, the following information is defined as sensitive 


e The password part of a connection string. However, if you select an option that encrypts everything, the 
whole connection string will be considered sensitive. 


e The task-generated XML nodes that are tagged as sensitive. The tagging of XML nodes is controlled by 
Integration Services and cannot by changed by users. 


e Any variable that is marked as sensitive. The marking of variables is controlled by Integration Services. 


Whether Integration Services considers a property sensitive depends on whether the developer of the 
Integration Services component, such as a connection manager or task, has designated the property as 
sensitive. Users cannot add properties to, nor can they remove properties from, the list of properties that are 
considered sensitive. 


Encryption 


Encryption, as used by package protection levels, is performed by using the Microsoft Data Protection API 
(DPAPI), which is part of the Cryptography API (CryptoAPI). 


The package protection levels that encrypt packages by using passwords require that you provide a password 
also. If you change the protection level from a level that does not use a password to one that does, you will be 
prompted for a password. 


Also, for the protection levels that use a password, Integration Services uses the Triple DES cipher algorithm with 
a key length of 192 bits, available in the .NET Framework Class Library (FCL). 


Protection Levels 


The following table describes the protection levels that Integration Services provides. The values in parentheses 
are values from the DTSProtectionLevel enumeration. These values appear in the Properties window that you 
use to configure the properties of the package when you work with packages in SQL Server Data Tools (SSDT). 


PROTECTION LEVEL 


Do not save sensitive (DontSaveSensitive) 


Encrypt all with password (EncryptAllWithPassword) 


Encrypt all with user key (EncryptAllWithUserKey) 


Encrypt sensitive with password 
(EncryptSensitiveWithPassword) 


DESCRIPTION 


Suppresses the values of sensitive properties in the package 
when the package is saved. This protection level does not 
encrypt, but instead it prevents properties that are marked 
sensitive from being saved with the package and therefore 
makes the sensitive data unavailable to other users. If a 
different user opens the package, the sensitive information is 
replaced with blanks and the user must provide the sensitive 
information. 


When used with the dtutil utility (dtutil.exe), this protection 
level corresponds to the value of 0. 


Uses a password to encrypt the whole package. The package 
is encrypted by using a password that the user supplies 
when the package is created or exported. To open the 
package in SSIS Designer or run the package by using the 
dtexec command prompt utility, the user must provide the 
package password. Without the password the user cannot 
access or run the package. 


When used with the dtutil utility, this protection level 
corresponds to the value of 3. 


Uses a key that is based on the current user profile to 
encrypt the whole package. Only the user who created or 
exported the package can open the package in SSIS 
Designer or run the package by using the dtexec command 
prompt utility. 


When used with the dtutil utility, this protection level 
corresponds to the value of 4. 


Note: For protection levels that use a user key, Integration 
Services uses DPAPI standards. For more information about 
DPAPI, see the MSDN Library at 
https://msdn.microsoft.com/library. 


Uses a password to encrypt only the values of sensitive 
properties in the package. DPAPI is used for this encryption. 
Sensitive data is saved as a part of the package, but that 
data is encrypted by using a password that the current user 
supplies when the package is created or exported. To open 
the package in SSIS Designer, the user must provide the 
package password. If the password is not provided, the 
package opens without the sensitive data and the current 
user must provide new values for sensitive data. If the user 
tries to execute the package without providing the 
password, package execution fails. For more information 
about passwords and command line execution, see dtexec 
Utility. 


When used with the dtutil utility, this protection level 
corresponds to the value of 2. 


PROTECTION LEVEL DESCRIPTION 


Encrypt sensitive with user key Uses a key that is based on the current user profile to 

(EncryptSensitiveWithUserKey) encrypt only the values of sensitive properties in the 
package. Only the same user who uses the same profile can 
load the package. If a different user opens the package, the 
sensitive information is replaced with blanks and the current 
user must provide new values for the sensitive data. If the 
user attempts to execute the package, package execution 
fails. DPAPI is used for this encryption. 


When used with the dtutil utility, this protection level 
corresponds to the value of 1. 


Note: For protection levels that use a user key, Integration 
Services uses DPAPI standards. For more information about 
DPAPI, see the MSDN Library at 
https://msdn.microsoft.com/library. 


Rely on server storage for encryption (ServerStorage) Protects the whole package using SQL Server database roles. 
This option is supported when a package is saved to the 
SQL Server msdb database. In addition, the SSISDB catalog 
uses the ServerStorage protection level 


This option is not supported when a package is saved to the 
file system from SQL Server Data Tools (SSDT). 


Protection Level Setting and the SSISDB Catalog 


The SSISDB catalog uses the ServerStorage protection level. When you deploy an Integration Services project 
to the Integration Services server, the catalog automatically encrypts the package data and sensitive values. The 
catalog also automatically decrypts the data when you retrieve it. 


If you export the project (.ispac file) from the Integration Services server to the file system, the system 
automatically changes the protection level to EncryptSensitiveWithUserKey. If you import the project by 
using the Integration Services Import Project Wizard in SQL Server Data Tools (SSDT), the 
ProtectionLevel property in the Properties window shows a value of EncryptSensitiveWithUserKey. 


Protection Level Setting Based on Package Life Cycle 


You set the protection level of a SQL Server Integration Services package when you first develop it in SQL 
Server Data Tools (SSDT). Later, when the package is deployed, imported or exported from Integration Services 
in SQL Server Management Studio, or copied from SQL Server Data Tools (SSDT) to SQL Server, the SSIS 
Package Store, or the file system, you can update the package protection level. For example, if you create and 
save packages on your computer with one of the user key protection level options, you likely would want to 
change the protection level when you give the package to other users; otherwise they cannot open the package. 


Typically, you change the protection level as listed in the following steps: 


1. During development, leave the protection level of packages set to the default value, 
EncryptSensitiveWithUserKey. This setting helps ensure that only the developer sees sensitive values 
in the package. Or, you can consider using EncryptAllWithUserKey, or DontSaveSensitive. 


2. When it is time to deploy the packages, you have to change the protection level to one that does not 
depend on the developer's user key. Therefore you typically have to select 
EncryptSensitiveWithPassword, or EncryptAllWithPassword. Encrypt the packages by assigning a 


temporary strong password that is also known to the operations team in the production environment. 


3. After the packages have been deployed to the production environment, the operations team can re- 
encrypt the deployed packages by assigning a strong password that is known only to them. Or, they can 
encrypt the deployed packages by selecting EncryptSensitiveWithUserKey or 
EncryptAllWithUserKey, and using the local credentials of the account that will run the packages. 


Set or Change the Protection Level of Packages 


To control access to the contents of packages and to the sensitive values that they contain, such as passwords, 
set the value of the ProtectionLevel property. The packages contained in a project need to have the same 
protection level as the project, to build the project. If you change the ProtectionLevel property setting on the 
project, you need to manually update the property setting for the packages. 


For an overview of security features in Integration Services, see Security Overview (Integration Services). 


The procedures in this topic describe how to use either SQL Server Data Tools (SSDT) or the dtutil command 
prompt utility to change the ProtectionLevel property. 





NOTE 
In addition to the procedures in this topic, you can typically set or change the ProtectionLevel property of a package 
when you import or export the package. You can also change the ProtectionLevel property of a package when you use 


the SQL Server Import and Export Wizard to save a package. 





To set or change the protection level of a package in SQL Server Data Tools 


1. Review the available values for the ProtectionLevel property in the section, Protection Levels, and 
determine the appropriate value for your package. 


2. In SQL Server Data Tools (SSDT), open the Integration Services project that contains the package. 
3. Open the package in the SSIS designer. 
4. If the Properties window does not show the properties of the package, click the design surface. 


5. In the Properties window, in the Security group, select the appropriate value for the ProtectionLevel 
property. 


If you select a protection level that requires a password, enter the password as the value of the 
PackagePassword property. 


6. On the File menu, select Save Selected Items to save the modified package. 


To set or change the protection level of packages at the command prompt 


1. Review the available values for the ProtectionLevel property in the section, Protection Levels, and 
determine the appropriate value for your package. 


2. Review the mappings for the Encrypt option in the topic, dtutil Utility, and determine the appropriate 
integer to use as the value of the selected ProtectionLevel property. 


3. Open a Command Prompt window. 


4. At the command prompt, navigate to the folder that contains the package or packages for which you 
want to set the ProtectionLevel property. 


The syntax examples shown in the following step assume that this folder is the current folder. 


5. Set or change the protection level of the package or packages by using a command similar to the one of 
the following examples: 





e The following command sets the ProtectionLevel property of an individual package in the file 
system to level 2, "Encrypt sensitive with password", with the password, "strongpassword": 


dtutil.exe /file "C:\Package.dtsx" /encrypt file;"C:\Package.dtsx";2;strongpassword 


e The following command sets the ProtectionLevel property of all packages in a particular folder 
in the file system to level 2, "Encrypt sensitive with password", with the password, 
"strongpassword": 


for “Ff in (*.dtsx) do dtutil.exe /file %Ff /encrypt file;%f;2;strongpassword 


If you use a similar command in a batch file, enter the file placeholder, "%f", as "%%f" in the batch 
file. 


Package Project Protection Level Dialog Box 


Use the Package Protection Level dialog box to update the protection level of a package. The protection level 
determines the protection method, the password or user key, and the scope of package protection. Protection 
can include all data or sensitive data only. 


To understand the requirements and options for package security, you may find it useful to see Security 


Overview (Integration Services). 


Options 
Package protection level 
Select a protection level from the list. 


Password 
If using the Encrypt sensitive data with password or Encrypt all data with password protection level, 
type a password. 


Retype password 
Type the password again. 


Package Password Dialog Box 


Use the Package Password dialog box to provide the package password for a package that is encrypted with a 
password. You must provide a password if the package uses the Encrypt sensitive with password or 
Encrypt all with password protection level. 


Options 


Password 
Enter the password. 


See Also 


Integration Services (SSIS) Packages 
Security Overview (Integration Services) 
dtutil Utility 


Identify the Source of Packages with Digital 


Signatures 
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An Integration Services package can be signed with a digital certificate to identify its source. After a package has 
been signed with a digital certificate, you can have Integration Services check the digital signature before 
loading the package. To have Integration Services check the signature, you set an option in either SQL Server 
Data Tools (SSDT) or in the dtexec utility (dtexec.exe), or set an optional registry value. 


Sign a package with a digital certificate 


Before you can sign a package with a digital certificate, you first have to obtain or create the certificate. After you 
have the certificate, you can then use this certificate to sign the package. For more information about how to 
obtain a certificate and sign a package with that certificate, see Sign a Package by Using a Digital Certificate. 


Set an option to check the package signature 


Both SQL Server Data Tools (SSDT) and the dtexec utility have an option that configures Integration Services to 
check the digital signature of a signed package. Whether you use SQL Server Data Tools (SSDT) or the dtexec 
utility depends on whether you want to check all packages or just specific ones: 


@ To check the digital signature of all packages before loading the packages at design time, set the Check 
digital signature when loading a package option in SQL Server Data Tools (SSDT). This option is a 
global setting for all packages in SQL Server Data Tools (SSDT). 


e To check the digital signature of an individual package, specify the /VerifyS[igned] option when you use 
the dtexec utility to run the package. For more information, see dtexec Utility. 


Set a Registry value to check package signature 


Integration Services also supports an optional registry value, BlockedSignatureStates, that you can use to 
manage an organization's policy for loading signed and unsigned packages. The registry value can prevent 
packages from loading if the packages are unsigned, or have invalid or untrusted signatures. For more 
information about how to set this registry value, see Implement a Signing Policy by Setting a Registry Value. 


NOTE 

The optional BlockedSignatureStates registry value can specify a setting that is more restrictive than the digital 
signature option set in SQL Server Data Tools (SSDT) or at the dtexec command line. In this situation, the more restrictive 
registry setting overrides the other settings. 





Implement a Signing Policy by Setting a Registry Value 


You can use an optional registry value to manage an organization's policy for loading signed or unsigned 
packages. If you use this registry value, you must create this registry value on each computer on which 
Integration Services packages will run and on which you want to enforce the policy. After the registry value has 
been set, Integration Services will check or verify the signatures before loading packages. 





The procedure in this article describes how to add the optional BlockedSignatureStates DWORD value to the 
HKLM\SOFTWARE\Microsoft\Microsoft SQL Server\150\SSIS\Setup\DTSPath registry key. 





NOTE 


A registry location under 150 represents SQL Server 2019, under 140 represents SQL Server 2017, under 130 represents 
SQL Server 2016, under 120 represents SQL Server 2014, and under 110 represents SQL Server 2012. 











The data value in BlockedSignatureStates determines whether a package should be blocked if it has an 
untrusted signature, has an invalid signature, or is unsigned. 


For the status of signatures used to sign packages, the BlockedSignatureStates registry value uses the 
following definitions: 


e A valid signature is one that can be read successfully. 


e An invalid signature is one for which the decrypted checksum (the one-way hash of the package code 
encrypted by a private key) does not match the decrypted checksum that is calculated as part of the 
process of loading Integration Services packages. 


e A trusted signature is one that is created by using a digital certificate signed by a Trusted Root 
Certification Authority. This setting does not require the signer to be found in the user's list of Trusted 
Publishers. 


e An untrusted signature is one that cannot be verified as issued by a Trusted Root Certification Authority, 
or a signature that is not current. 


The following table lists the valid values of the DWORD data and their associated policy. 


VALUE DESCRIPTION 
0 No administrative restriction. 
1 Block invalid signatures. 


This setting does not block unsigned packages. 


2 Block invalid and untrusted signatures. 


This setting does not block unsigned packages, but blocks 
self-generated signatures. 


3 Block invalid and untrusted signatures and unsigned 
packages 


This setting also blocks self-generated signatures. 


NOTE 


The recommended setting for BlockedSignatureStates is 3. This setting provides the greatest protection against 
unsigned packages or signatures that are either not valid or untrusted. However, the recommended setting may not be 
appropriate in all circumstances. For more information about signing digital assets, see the topic, "Introduction to Code 
Signing," in the MSDN Library. 











To implement a signing policy for packages 


1. On the Start menu, click Run. 


2. In the Run dialog box, type Regedit, and then click OK. 

3. Locate the registry key, HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Microsoft SQL Server\100\SSIS. 
4. Right-click MSDTS, point to New, and then click DWORD Value. 

5. Update the name of the new value to BlockedSignatureStates. 

6. Right-click BlockedSignatureStates and click Modify. 

7. Inthe Edit DWORD Value dialog box, type the value 0, 1, 2, or 3. 

8. Click OK. 


9. On the File menu, click Exit. 


Sign a Package by Using a Digital Certificate 


This topic describes how to sign an Integration Services package with a digital certificate. You can use a digital 
signature, together with other settings, to prevent a package that is not valid from loading and running. 


Before you can sign an Integration Services package, you must do the following tasks: 


e Create or obtain a private key to associate with the certificate, and store this private key on the local 
computer. 


e Obtain a certificate for the purpose of code signing from a trusted certification authority. You can use one 
of the following methods to obtain or create a certificate: 


© Obtain a certificate from a public, commercial certification authority that issues certificates. 


o Obtain a certificate from a certificate server, that enables an organization to internally issue 
certificates. You have to add the root certificate that is used to sign the certificate to the Trusted 
Root Certification Authorities store. To add the root certificate, you can use the Certificates 
snap-in for the Microsoft Management Console (MMC). For more information, see the topic, 
"Certificate Services," in the MSDN library. 


o Create your own certificate for testing purposes only. The Certificate Creation Tool (Makecert.exe) 
generates X.509 certificates for testing purposes. For more information, see the topic, "Certificate 
Creation Tool (Makecert.exe)," in the MSDN Library. 


For more information about certificates, see the online Help for the Certificates snap-in. For more 
information about how to sign digital assets, see the topic, "Signing and Checking Code with 
Authenticode,” in the MSDN Library. 


e Make sure that the certificate has been enabled for code signing. To determine whether a certificate is 
enabled for code signing, review the properties of the certificate in the Certificates snap-in. 


e Store the certificate in the Personal store. 
After you have completed the previous tasks, you can use the following procedure to sign a package. 


To sign a package 
1. In SQL Server Data Tools (SSDT), open the Integration Services project that contains the package to be 
signed. 


2. In Solution Explorer, double-click the package to open it. 
3. In SSIS Designer, on the SSIS menu, click Digital Signing. 


4. In the Digital Signing dialog box, click Sign. 


5. Inthe Select a Certificate dialog box, select a certificate. 

6. (Optional) Click View Certificate to view certificate information. 

7. Click OK to close the Select a Certificate dialog box. 

8. Click OK to close the Digital Signing dialog box. 

9. To save the updated package, click Save Selected Items on the File menu. 


Although the package has been signed, you must now configure Integration Services to check or verify 
the digital signature before loading the package. 


Digital Signing Dialog Box UI Reference 


Use the Digital Signing dialog box to sign a package with a digital signature or to remove the signature. The 
Digital Signing dialog box is available from the Digital Signing option on the SSIS menu in SQL Server Data 
Tools (SSDT). 


For more information, see Sign a Package by Using a Digital Certificate. 


Options 
Sign 


Click to open the Select Certificate dialog box, and select the certificate to use. 


Remove 
Click to remove the digital signature. 


See also 


Integration Services (SSIS) Packages 
Security Overview (Integration Services) 
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SQL Server Integration Services provides certain fixed database-level roles to help secure access to packages 
that are stored in SQL Server. The available roles are different depending on whether you're saving packages in 
the SSIS Catalog database (SSISDB) or in the msdb database. 


Roles in the SSIS Catalog database (SSISDB) 


The SSIS Catalog database (SSISDB) provides the following fixed database-level roles to help secure access to 
packages and information about packages. 


e ssis_admin. This role provides full administrative access to the SSIS Catalog database. 
e ssis_logreader This role provides permissions to access all the views related SSISDB operational logs. 


The list of views includes: [catalog].[projects], [catalog].[packages], [catalog].[operations], [catalog]. 
[extended_operation_info], [catalog].[operation_messages], [catalog].[event_messages], [catalog]. 
[execution_data_statistics], [catalog].[execution_component_phases], [catalog].[execution_data_taps], 
[catalog].[event_message_context], [catalog].[executions], [catalog].[executables], [catalog]. 
[executable_statistics], [catalog].[validations], [catalog].[execution_parameter_values], and [catalog]. 
[execution_property_override_values]. 


Roles in the msdb database 


SQL Server Integration Services includes the three fixed database-level roles, db_ssisadmin, db_ssisltduser, 
and db_ssisoperator, for controlling access to packages that are saved to the msdb database. You assign roles 
to a package using SQL Server Management Studio. The role assignments are saved to the msdb database. 
Read and Write Actions 


The following table describes the read and write actions of Windows and fixed database-level roles in 
Integration Services. 


ROLE READ ACTION WRITE ACTION 


ROLE 


db_ssisadmin 
or 


sysadmin 


db_ssisltduser 


db_ssisoperator 


READ ACTION 


Enumerate own packages. 


Enumerate all packages. 
View own packages. 
View all packages. 
Execute own packages. 
Execute all packages. 
Export own packages. 


Export all packages. 


Execute all packages in SQL Server 


Agent. 


Enumerate own packages. 


Enumerate all packages. 
View own packages. 
Execute own packages. 


Export own packages. 


Enumerate all packages. 
View all packages. 
Execute all packages. 


Export all packages. 


WRITE ACTION 


Import packages. 

Delete own packages. 
Delete all packages. 
Change own package roles. 


Change all package roles. 


**** Warning ****Members of the 
db_ssisadmin role and the dc_admin 
role may be able to elevate their 
privileges to sysadmin. This elevation 
of privilege can occur because these 
roles can modify Integration Services 
packages and Integration Services 
packages can be executed by SQL 
Server using the sysadmin security 
context of SQL Server Agent. To guard 
against this elevation of privilege when 
running maintenance plans, data 
collection sets, and other Integration 
Services packages, configure SQL 
Server Agent jobs that run packages 
to use a proxy account with limited 
privileges or only add sysadmin 
members to the db_ssisadmin and 
dc_admin roles. 


Import packages. 
Delete own packages. 


Change own package roles. 


None 


Execute all packages in SQL Server 
Agent. 


Windows administrators View execution details of all running Stop all currently running packages. 


packages. 


Sysssispackages Table 


The sysssispackages table in msdb contains the packages that are saved to SQL Server. For more information, 
see sysssispackages (Transact-SQL). 


The sysssispackages table includes columns that contain information about the roles that are assigned to 
packages. 


e Thereaderrole column specifies the role that has read access to the package. 
e Thewriterrole column specifies the role that has write access to the package. 


e The ownersid column contains the unique security identifier of the user who created the package. This 
column defines the owner of the package. 


Permissions 


By default, the permissions of the db_ssisadmin and db_ssisoperator fixed database-level roles and the 
unique security identifier of the user who created the package apply to the reader role for packages, and the 
permissions of the db_ssisadmin role and the unique security identifier of the user who created the package 
apply to the writer role. A user must be a member of the db_ssisadmin, db_ssisltduser, or db_ssisoperator 
role to have read access to the package. A user must be a member of the db_ssisadmin role to have write 


access. 


Access to Packages 


The fixed database-level roles work in conjunction with user-defined roles. The user-defined roles are the roles 
that you create in SQL Server Management Studio and then use to assign permissions to packages. To access a 
package, a user must be a member of the user-defined role and the pertinent Integration Services fixed 
database-level role. For example, if users are members of the AuditUsers user-defined role that is assigned to a 
package, they must also be members of db_ssisadmin, db_ssisltduser, or db_ssisoperator role to have read 
access to the package. 


If you do not assign user-defined roles to packages, access to packages is determined by the fixed database-level 
roles. 


If you want to use user-defined roles, you must add them to the msdb database before you can assign them to 


packages. You can create new database roles in SQL Server Management Studio. 


The Integration Services database-level roles grant rights on the Integration Services system tables in the msdb 
database. 


SQL Server (the MSSQLSERVER service) must be started before you can connect to the Database Engine and 
access the msdb database. 


To assign roles to packages, you need to complete the following tasks. 
e Open Object Explorer and Connect to Integration Services 


Before you can assign roles to packages by using SQL Server Management Studio, you must open Object 


Explorer in SQL Server Management Studio and connect to Integration Services. 
The Integration Services service must be started before you can connect to Integration Services. 
e Assign Reader and Writer Roles to Packages 


You can assign a reader and a writer role to each package. 


Assign a Reader and Writer Role to a Package 


You can assign a reader and a writer role to each package. 


Assign a reader and writer role to a package 


1. In Object Explorer, locate the Integration Services connection. 


2. Expand the Stored Packages folder, and then expand the subfolder that contains the package to which you 


want to assign roles. 
3. Right-click the package to which you want to assign roles. 


4. In the Packages Roles dialog box, select a reader role in the Reader Role list and a writer role in the 
Writer Role list. 


5. Click OK. 


Create a User-Defined Role 


To create a user-defined role 


1. Open SQL Server Management Studio. 
2. Click Object Explorer on the View menu. 
3. On the Object Explorer toolbar, click Connect, and then click Database Engine. 


4. In the Connect to Server dialog box, provide a server name and select an authentication mode. You can 


use a period (.), (local), or localhost to indicate the local server. 
5. Click Connect. 
6. Expand Databases, System Databases, msdb, Security, and Roles. 
7. Inthe Roles node, right-click Database Roles, and click New Database Role. 


8. On the General page, provide a name and optionally, specify an owner and owned schemas and add role 
members. 


9. Optionally, click Permissions and configure object permissions. 
10. Optionally, click Extended Properties and configure any extended properties. 


11. Click OK. 


Package Roles Dialog Box UI Reference 


Use the Package Roles dialog box, available in SQL Server Management Studio, to specify the database-level 
roles that have read access to the package and the database-level roles that have write access to the package. 
Database-level roles apply only to packages that are stored in the SQL Server msdb database. 


The roles listed in the dialog box are the current database roles of the msdb system database. If no roles are 
selected, the default Integration Services roles apply. By default, the reader role includes db_ssisadmin, 
db_ssisoperator, and the user who created the package. A user who is a member of one of these roles or 
created the packages can enumerate, view, export, and run packages. By default, the writer role includes 
db_ssisadmin and the user who created the package. A user who is a member of this role and the user who 
created the packages can import, delete, and change packages. 


The ownersid column in the sysssispackages table lists the unique security identifier of the user who created 
the package. 


Options 
Package Name 
Specify the name of the package. 


Reader Role 


Select a role in the list. 


Writer Role 


Select a role in the list 
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You can monitor Integration Services package executions, project validations, and other operations by using one 
of more of the following tools. Certain tools such as data taps are available only for projects that are deployed to 
the Integration Services server. 


e Logs 
For more information, see Integration Services (SSIS) Logging. 
e Reports 
For more information, see Reports for the Integration Services Server. 
e Views 
For more information, see Views (Integration Services Catalog). 
e Performance counters 
For more information, see Performance Counters. 


e Data taps 


NOTE 


This article describes how to monitor running SSIS packages in general, and how to monitor running packages on 
premises. You can also run and monitor SSIS packages in Azure SQL Database. For more info, see Lift and shift SQL Server 
Integration Services workloads to the cloud. 


Although you can also run SSIS packages on Linux, no monitoring tools are provided on Linux. For more info, see Extract, 
transform, and load data on Linux with SSIS. 











Operation Types 


Several different types of operations are monitored in the SSISDB catalog, on the Integration Services server. 
Each operation can have multiple messages associated with it. Each message can be classified into one of 
several different types. For example, a message can be of type Information, Warning, or Error. For the full list of 
message types, see the documentation for the Transact-SQL catalog.operation_messages (SSISDB Database) 
view. For a full list of the operations types, see catalog.operations (SSISDB Database). 


Nine different status types are used to indicate the status of an operation. For a full list of the status types, see 
the catalog.operations (SSISDB Database) view. 


Active Operations Dialog Box 


Use the Active Operations dialog box to view the status of currently running Integration Services operations 
on the Integration Services server, such as deployment, validation, and package execution. This data is stored in 
the SSISDB catalog. 


For more information about related Transact-SQL views, see catalog.operations (SSISDB Database), 


catalog.validations (SSISDB Database), and catalog.executions (SSISDB Database) 


Open the Active Operations Dialog Box 
1. Open SQL ServerManagement Studio. 


2. Connect Microsoft SQL Server Database Engine 


3. In Object Explorer, expand the Integration Services node, right-click SSISDB, and then click Active 


Operations. 


Configure the Options 
Type 


Specifies the type of operation. The following are the possible values for the Type field and the corresponding 


values in the operations_type column of the Transact-SQL catalog.operations view. 


TYPE FIELD DESCRIPTION 


Integration Services initialization 


Operations cleanup (SQL Agent job) 


Project versions cleanup (SQL Agent job) 


Deploy project 


Restore project 


Create and start package execution 


Stop operation (stopping a validation or execution 


Validate project 


Validate package 


Configure catalog 


Stop 
Click to stop a currently running operation. 


OPERATIONS_TYPE VALUE 


106 


200 


202 


300 


301 


1000 


Viewing and Stopping Packages Running on the Integration Services 


Server 


The SSISDB database stores execution history in internal tables that are not visible to users. However it exposes 


the information that you need through public views that you can query. It also provides stored procedures that 


you can call to perform common tasks related to packages. 


Typically you manage Integration Services objects on the server in SQL Server Management Studio. However 


you can also query the database views and call the stored procedures directly, or write custom code that calls 


the managed API. SQL Server Management Studio and the managed API query the views and call the stored 


procedures to perform many of their tasks. For example, you can view the list of Integration Services packages 


that are currently running on the server, and request packages to stop if you have to. 


Viewing the List of Running Packages 


You can view the list of packages that are currently running on the server in the Active Operations dialog box. 
For more information, see Active Operations Dialog Box. 


For information about the other methods that you can use to view the list of running packages, see the 
following topics. 


Transact-SQL access 
To view the list of packages that are running on the server, query the view, catalog.executions (SSISDB Database) 
for packages that have a status of 2. 


Programmatic access through the managed API 
See the Microsoft.SqiServer.Management.IntegrationServices namespace and its classes. 


Stopping a Running Package 


You can request a running package to stop in the Active Operations dialog box. For more information, see 
Active Operations Dialog Box. 


For information about the other methods that you can use to stop a running package, see the following topics. 


Transact-SQL access 
To stop a package that is running on the server, call the stored procedure, catalog.stop_operation (SSISDB 
Database). 


Programmatic access through the managed API 
See the Microsoft.SqiServerManagement.IntegrationServices namespace and its classes. 


Viewing the History of Packages That Have Run 


To view the history of packages that have run in Management Studio, use the All Executions report. For more 
information on the All Executions report and other standard reports, see Reports for the Integration Services 
Server. 


For information about the other methods that you can use to view the history of running packages, see the 
following topics. 


Transact-SQL access 
To view information about packages that have run, query the view, catalog.executions (SSISDB Database). 


Programmatic access through the managed API 
See the Microsoft.SqiServerManagement.IntegrationServices namespace and its classes. 


Reports for the Integration Services Server 


In the current release of SQL Serverlntegration Services, standard reports are available in SQL Server 
Management Studio to help you monitor Integration Services projects that have been deployed to the 
Integration Services server. These reports help you to view package status and history, and, if necessary, identify 
the cause of package execution failures. 


At the top of each report page, the back icon takes you to the previous page you viewed, the refresh icon 
refreshes the information displayed on the page, and the print icon allows you to print the current page. 


For information on how to deploy packages to the Integration Services server, see Deploy Integration Services 
(SSIS) Projects and Packages. 


Integration Services Dashboard 


The Integration Services Dashboard report provides an overview of all the package executions on the SQL 
Server instance. For each package that has run on the server, the dashboard allows you to "zoom in" to find 
specific details on package execution errors that may have occurred. 


The report displays the following sections of information. 


SECTION 


Execution Information 


Package Information 


Connection Information 


Package Detailed Information 


DESCRIPTION 


Shows the number of executions that are in different states 
(failed, running, succeeded, others) in the past 24 hours. 


Shows the total number of packages that have been 
executed in the past 24 hours. 


Shows the connections that have been used in failed 
executions in the past 24 hours. 


Shows the details of the completed executions that have 
occurred in the past 24 hours. For example, this section 
shows the number of failed executions versus the total 
number of executions, the duration of an executions (in 
seconds), and the average duration of executions for over 
the past three months. 


You can view additional information for a package by clicking 
Overview, All Messages, and Execution Performance. 


The Execution Performance report shows the duration of 
the last execution instance, as well as the start and end 
times, and the environment that was applied. 


The chart and associated table included in the Execution 
Performance report shows the duration of the past 10 
successful executions of the package. The table also shows 
the average execution duration over a three-month period. 
Different environments and different literal values may have 
been applied at runtime for these 10 successful executions of 
the package. 


Finally, the Execution Performance report shows the 
Active Time and Total Time for the package data flow 
components. The Active Time refers to the total amount of 
time that component has spent executing in all phases, and 
the Total Time refers to the total time elapsed for a 
component. The report only displays this information for 
package components when the logging level of the last 
package execution was set to Performance or Verbose. 


The Overview report shows the state of package tasks. The 
Messages report shows the event messages and error 
messages for the package and tasks, such as reporting the 
start and end times, and the number of rows written. 


You can also click View Messages in the Overview report 
to navigate to the Messages report. You can also click 
View Overview in the Messages report to navigate to the 
Overview report. 


You can filter the table displayed on any page by clicking Filter and then selecting criteria in the Filter Settings 


dialog. The filter criteria that are available depend on the data being displayed. You can change the sort order of 


the report by clicking the sort icon in the Filter Settings dialog. 


All Executions Report 


The All Executions Report displays a summary of all Integration Services executions that have been 


performed on the server. There can be multiple executions of the sample package. Unlike the Integration 


Services Dashboard report, you can configure the All Executions report to show executions that have 
started during a range of dates. The dates can span multiple days, months, or years. 


The report displays the following sections of information. 
SECTION DESCRIPTION 


Filter Shows the current filter applied to the report, such as the 
Start time range. 


Execution Information Shows the start time, end time, and duration for each 
package execution.You can view a list of the parameter 
values that were used with a package execution, such as 
values that were passed to a child package using the Execute 
Package task. To view the parameter list, click Overview. 


For more information about using the Execute Package task to make values available to a child package, see 
Execute Package Task. 


For more information about parameters, see Integration Services (SSIS) Package and Project Parameters. 


All Connections 


The All Connections report provides the following information for connections that have failed, for executions 
that have occurred on the SQL Server instance. 


The report displays the following sections of information. 


SECTION DESCRIPTION 

Filter Shows the current filter applied to the report, such as 
connections with a specified string and the Last failed time 
range. 


You set the Last failed time range to display only 
connection failures that occurred during a range of dates. 
The range can span multiple days, months, or years. 


Details Shows the connection string, number of executions during 
which a connection failed, and the date when the connection 
last failed. 


All Operations Report 


The All Operations Report displays a summary of all Integration Services operations that have been 
performed on the server, including package deployment, validation, and execution, as well as other 
administrative operations. As with the Integration Services Dashboard, you can apply a filter to the table to 
narrow down the information displayed. 


All Validations Report 


The All Validations Report displays a summary of all Integration Services validations that have been 
performed on the server. The summary displays information for each validation such as status, start time, and 
end time. Each summary entry includes a link to messages generated during validation. As with the Integration 
Services Dashboard, you can apply a filter to the table to narrow down the information displayed. 


Custom Reports 


You can add a custom report (.rdl file) to the SSISDB catalog node under the Integration Services Catalogs 
node in SQL Server Management Studio. Before adding the report, confirm that you are using a three-part 
naming convention to fully qualify the objects you reference such as a source table. Otherwise, SQL Server 


Management Studio will display an error. The naming convention is <database>.<owner>.<object>. An 
example would be SSISDB.internal.executions. 





NOTE 


When you add custom reports to the SSISDB node under the Databases node, the SSISDB prefix is not necessary. 





For instructions on how to create and add a custom report, see Add a Custom Report to Management Studio. 


View Reports for the Integration Services Server 


In the current release of SQL Serverlntegration Services, standard reports are available in SQL Server 
Management Studio to help you monitor Integration Services projects that have been deployed to the 
Integration Services server. For more information about the reports, see Reports for the Integration Services 
Server. 


To view reports for the Integration Services server 


1. In SQL Server Management Studio, expand the Integration Services Catalogs node in Object Explorer. 
2. Right-click SSISDB, click Reports, and then click Standard Reports. 
3. Click one more of the following to view a report. 


e Integration Services Dashboard 


All Executions 


e All Validations 


All Operations 


e All Connections 


See Also 


Execution of Projects and Packages 
Troubleshooting Reports for Package Execution 
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An Integration Services package logs various event messages to the Windows Application event log. A package 


logs these messages when the package starts, when the package stops, and when certain problems occur. 


This topic provides information about the common event messages that a package logs to the Application event 


log. By default, a package logs some of these messages even if you have not enabled logging on the package. 


However, there are other messages that the package will log only if you have enabled logging on the package. 


Regardless of whether the package logs these messages by default or because logging has been enabled, the 


Event Source for the messages is SQLIS Package. 


For general information about how to run SSIS packages, see Execution of Projects and Packages. 


For information about how to troubleshoot running packages, see Troubleshooting Tools for Package Execution. 


Messages about the Status of the Package 


When you run an Integration Services package, the package typically logs various messages about the progress 


and status of the package. The following table lists those messages. 





NOTE 


The package will log the messages in the following table even if you have not enabled logging for the package. 





EVENT ID 


12288 


12289 


12290 


12291 


SYMBOLIC NAME 


DTS_MSG_PACKAGESTART 


DTS_MSG_PACKAGESUCCES 
S 


DTS_MSG_PACKAGECANCE 
L 


DTS_MSG_PACKAGEFAILUR 
E 


TEXT 


Package "" started. 


Package "" finished 
successfully. 


Package "%1!s!" has been 
cancelled. 


Package "" failed. 


NOTES 


The package has started to 
run. 


The package successfully 
ran and is no longer 
running. 


The package is no longer 
running because the 
package was canceled. 


The package could not run 
successfully and stopped 
running. 


By default, in a new installation, Integration Services is configured not to log certain events that are related to 


the running of packages to the Application event log. This setting prevents too many event log entries when you 


use the Data Collector feature of the current release of SQL Serverlntegration Services. The events that are not 


logged are EventID 12288, "Package started," and EventID 12289, "Package finished successfully." To log these 


events to the Application event log, open the registry for editing. Then in the registry, locate the 
HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Microsoft SQL Server\110\SSIS node, and change the DWORD 
value of the LogPackageExecutionToEventLog setting from 0 to 1. However, in an upgrade insallation, Integration 


Services is configured to log these two events. To disable logging, change the value of the 


LogPackageExecutionToEventLog setting from 1 to 0. 


Messages Associated with Package Logging 


If you have enabled logging on the package, the Application event log is one of the destinations that is 


supported by the optional logging features in Integration Services packages. For more information, see 


Integration Services (SSIS) Logging. 


When you have enabled logging on the package and the log location is the Application event log, the package 


logs entries that pertain to the following information: 


e Messages about which stage the package is in while the package runs. 


e Messages about particular events that occur while the package runs. 


Messages about the Stages of Package Execution 


EVENT ID 


12544 


12556 


12547 


12548 


12552 


SYMBOLIC NAME 


DTS_MSG_EVENTLOGENTRY 


DTS_MSG_EVENTLOGENTRY 


_PACKAGESTART 


DTS_MSG_EVENTLOGENTRY 
_PREVALIDATE 


DTS_MSG_EVENTLOGENTRY 
_POSTVALIDATE 


DTS_MSG_EVENTLOGENTRY 
_PROGRESS 


TEXT 


Event Name: %1 %r 

Message: %9%r Operator: 
%2%r Source Name: %3%r 
Source ID: %4%r Execution 
ID: %5%r Start Time: %6%r 


End Time: %7%r Data Code: 


%8 


Event Name: %1 %r 

Message: %9%r Operator: 
%2%r Source Name: %3 %r 
Source ID: %4%r Execution 
ID: %5%r Start Time: %6%r 


End Time: %7%r Data Code: 


%8 


Event Name: %1 %r 

Message: %9%r Operator: 
%2%r Source Name: %3%r 
Source ID: %4%r Execution 
ID: %5%r Start Time: %6%r 


End Time: %7%r Data Code: 


%8 


Event Name: %1 %r 

Message: %9%r Operator: 
%2%r Source Name: %3%r 
Source ID: %4%r Execution 
ID: %5%r Start Time: %6%r 


End Time: %7%r Data Code: 


%8 


Event Name: %1 %r 

Message: %9%r Operator: 
%2%r Source Name: %3%r 
Source ID: %4%r Execution 
ID: %5%r Start Time: %6%r 


End Time: %7%r Data Code: 


%8 


NOTES 


When you configure 
package logging to the 
Application event log, 
various messages use this 
generic format. 


The package started. 


Validation of the object is 
about to begin. 


Validation of the object has 
finished. 


This generic message 
reports package progress. 


EVENT ID SYMBOLIC NAME 

12546 DTS_MSG_EVENTLOGENTRY 
_POSTEXECUTE 

12557 DTS_MSG_EVENTLOGENTRY 


_PACKAGEEND 


Messages about Events that Occur 


TEXT 


Event Name: %1 %r 

Message: %9%r Operator: 
%2%r Source Name: %3%r 
Source ID: %4%r Execution 
ID: %5%r Start Time: %6%r 


End Time: %7%r Data Code: 


%8 


Event Name: %1 %r 

Message: %9%r Operator: 
%2%r Source Name: %3%r 
Source ID: %4%r Execution 
ID: %5%r Start Time: %6%r 


End Time: %7%r Data Code: 


%8 


NOTES 


The object has finished its 
work. 


The package has finished 
running. 


The following table lists only some of the messages that are the result of events. For a more comprehensive list 


of error, warning, and informational messages that Integration Services uses, see Integration Services Error and 


Message Reference. 


EVENT ID SYMBOLIC NAME 

12251 DTS_MSG_EVENTLOGENTRY 
_TASKFAILED 

12250 DTS_MSG_EVENTLOGENTRY 
_ERROR 

12249 DTS_MSG_EVENTLOGENTRY 
_WARNING 

12258 DTS_MSG_EVENTLOGENTRY 


_INFORMATION 


TEXT 


Event Name: %1 %r 

Message: %9%r Operator: 
%2%r Source Name: %3%r 
Source ID: %4%r Execution 
ID: %5%r Start Time: %6%r 


End Time: %7%r Data Code: 


%8 


Event Name: %1 %r 

Message: %9%r Operator: 
%2%r Source Name: %3%r 
Source ID: %4%r Execution 
ID: %5%r Start Time: %6%r 


End Time: %7%r Data Code: 


%8 


Event Name: %1 %r 

Message: %9%r Operator: 
%2%r Source Name: %3 %r 
Source ID: %4%r Execution 
ID: %5%r Start Time: %6%r 


End Time: %7%r Data Code: 


%8 


Event Name: %1 %r 

Message: %9%r Operator: 
%2%r Source Name: %3 %r 
Source ID: %4%r Execution 
ID: %5%r Start Time: %6%r 


End Time: %7%r Data Code: 


%8 


View Log Entries in the Log Events Window 


NOTES 


The task failed. 


This message reports an 
error that has occurred. 


This message reports a 
warning that has occurred. 


This message reports 
informational that is not 
associated with an error or 
a warning. 


This procedure describes how to run a package and view the log entries it writes. You can view the log entries in 
real time. The log entries that are written to the Log Events window can also be copied and saved for further 
analysis. 


It is not necessary to write the log entries to a log to write the entries to the Log Events window. 


To view log entries 


1. In SQL Server Data Tools, open the Integration Services project that contains the package you want. 


2. On the SSIS menu, click Log Events. You can optionally display the Log Events window by mapping 
the View.LogEvents command to a key combination of your choosing on the Keyboard page of the 
Options dialog box. 


3. On the Debug menu, click Start Debugging. 


As the runtime encounters the events and custom messages that are enabled for logging, log entries for 


each event or message are written to the Log Events window. 
4. On the Debug menu, click Stop Debugging. 


The log entries remain available in the Log Events window until you rerun the package, run a different 


package, or close SQL Server Data Tools. 
5. View the log entries in the Log Events window. 
6. Optionally, click the log entries to copy, right-click, and then click Copy. 


7. Optionally, double-click a log entry, and in the Log Entry dialog box, view the details for a single log 
entry. 


8. Inthe Log Entry dialog box, click the up and down arrows to display the previous or next log entry, and 
click the copy icon to copy the log entry. 


9. Open a text editor, paste, and then save the log entry to a text file. 


Integration Services (SSIS) Logging 
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SQL Server Integration Services includes log providers that you can use to implement logging in packages, 
containers, and tasks. With logging, you can capture run-time information about a package, helping you audit 
and troubleshoot a package every time it is run. For example, a log can capture the name of the operator who 
ran the package and the time the package began and finished. 


You can configure the scope of logging that occurs during a package execution on the Integration Services 
server. For more information, see Enable Logging for Package Execution on the SSIS Server. 


You can also include logging when you run a package using the dtexec command prompt utility. For more 
information about the command prompt arguments that support logging, see dtexec Utility. 


Configure Logging in SQL Server Data Tools 


Logs are associated with packages and are configured at the package level. Each task or container in a package 
can log information to any package log. The tasks and containers in a package can be enabled for logging even 
if the package itself is not. For example, you can enable logging on an Execute SQL task without enabling 
logging on the parent package. A package, container, or task can write to multiple logs. You can enable logging 
on the package only, or you can choose to enable logging on any individual task or container that the package 
includes. 


When you add the log to a package, you choose the log provider and the location of the log. The log provider 
specifies the format for the log data: for example, a SQL Server database or text file. 


Integration Services includes the following log providers: 


e The Text File log provider, which writes log entries to ASCII text files in a comma-separated value (CSV) 
format. The default file name extension for this provider is .log. 


e The SQL Server Profiler log provider, which writes traces that you can view using SQL Server Profiler. The 
default file name extension for this provider is .trc. 





NOTE 


You cannot use the SQL Server Profiler log provider in a package that is running in 64-bit mode. 





e The SQL Server log provider, which writes log entries to the sysssislog table in a SQL Server database. 


e The Windows Event log provider, which writes entries to the Application log in the Windows Event log on 
the local computer. 


e The XML File log provider, which writes log files to an XML file. The default file name extension for this 
provider is .xml. 


If you add a log provider to a package or configure logging programmatically, you can use either a ProgID or 
ClassID to identify the log provider, instead of using the names that SSIS Designer displays in the Configure 
SSIS Logs dialog box. 


The following table lists the ProgID and ClassID for the log providers that Integration Services includes, and the 


location of the logs to which log providers write. 


LOG PROVIDER PROGID CLASSID LOCATION 
Text file DTS.LogProviderTextFile {0A039101-ACC1-4E06- The File connection 
943F-279948323883} manager that the log 


provider uses specifies the 
path of the text file. 


SQL Server Profiler DTS.LogProviderSQLProfiler {E93F6300-AEOC-4916- The File connection 
A7BF-A8DOCE12C77A} manager that the log 
provider uses specifies the 
path of the file used by SQL 
Server Profiler. 


SQL Server DTS.LogProviderSQLServer {94150B25-6AEB-4COD- The OLE DB connection 
996D-D37D1C4FDEDA} manager that the log 
provider uses specifies the 
SQL Server database that 
contains the sysssislog table 
with the log entries. 


Windows Event Log DTS.LogProviderEventLog {071CC8EB-C343-4CFF- The Application log in 
8D58-564B92FCA3CF} Windows Event Viewer 
contains the Integration 
Services log information. 


XML File DTS.LogProviderXMLFile {440945A4-2A22-4F19- The File connection 
B577-EAFS5FDDC5F7A} manager that the log 
provider uses specifies the 
path of the XML file. 


You can also create custom log providers. For more information, see Creating a Custom Log Provider. 


The log providers in a package are members of the log providers collection of the package. When you create a 
package and implement logging by using SSIS Designer, you can see a list of the collection members in the Log 
Provider folders on the Package Explorer tab of SSIS Designer. 


You configure a log provider by providing a name and description for the log provider and specifying the 
connection manager that the log provider uses. The SQL Server log provider uses an OLE DB connection 
manager. The Text File, SQL Server Profiler, and XML File log providers all use File connection managers. The 
Windows Event log provider does not use a connection manager, because it writes directly to the Windows 
Event log. For more information, see OLE DB Connection Manager and File Connection Manager. 


Logging Customization 


To customize the logging of an event or custom message, Integration Services provides a schema of commonly 
logged information to include in log entries. The Integration Services log schema defines the information that 


you can log. You can select elements from the log schema for each log entry. 


A package and its containers and tasks do not have to log the same information, and tasks within the same 
package or container can log different information. For example, a package can log operator information when 
the package starts, one task can log the source of the task's failure, and another task can log information when 
errors occur. If a package and its containers and tasks use multiple logs, the same information is written to all 
the logs. 


You can select a level of logging that suits your needs by specifying the events to log and the information to log 
for each event. You may find that some events provide more useful information than others. For example, you 
might want to log only the computer and operator names for the PreExecute event but all available 


information for the Error event. 


To prevent log files from using large amounts of disk space, or to avoid excessive logging, which could degrade 
performance, you can limit logging by selecting specific events and information items to log. For example, you 
can configure a log to capture only the date and the computer name for each error. 


In SSIS Designer, you define the logging options by using the Configure SSIS Logs dialog box. 


Log Schema 


The following table describes the elements in the log schema. 


ELEMENT DESCRIPTION 

Computer The name of the computer on which the log event occurred. 

Operator The identity of the user who launched the package. 

SourceName The name of the container or task in which the log event 
occurred. 

SourcelD The unique identifier of the package; the For Loop, Foreach 


Loop, or Sequence container; or the task in which the log 
event occurred. 


ExecutionID The GUID of the package execution instance. 


Note: Running a single package might create log entries with 
different values for the ExecutionID element. For example, 
when you run a package in SQL Server Data Tools, the 
validation phase might create log entries with an 
ExecutionID element that corresponds to SQL Server Data 
Tools. However, the execution phase might create log entries 
with an ExecutionID element that corresponds to 
dtshost.exe. For another example, when you run a package 
that contains Execute Package tasks, each of these tasks runs 
a child package. These child packages might create log 
entries that have a different ExecutionID element than the 
log entries that the parent package creates. 


MessageText A message associated with the log entry. 


DataBytes A byte array specific to the log entry. The meaning of this 
field varies by log entry. 


The following table describes three additional elements in the log schema that are not available on the Details 
tab of the Configure SSIS Logs dialog box. 


ELEMENT DESCRIPTION 


StartTime The time at which the container or task starts to run. 


EndTime The time at which the container or task stops running. 


ELEMENT 


DataCode 


Log Entries 


DESCRIPTION 


An optional integer value that typically contains a value from 
the DTSExecResult enumeration that indicates the result of 
running the container or task: 

0 - Success 

1 - Failure 


2 - Completed 


3 - Canceled 


Integration Services supports log entries on predefined events and provides custom log entries for many 


Integration Services objects. The Configure SSIS Logs dialog box in SSIS Designer lists these events and 


custom log entries. 


The following table describes the predefined events that can be enabled to write log entries when run-time 


events occur. These log entries apply to executables, the package, and the tasks and containers that the package 


includes. The name of the log entry is the same as the name of the run-time event that was raised and caused 


the log entry to be written. 


EVENTS 


OnError 


OnExecStatusChanged 


OnInformation 


OnPostExecute 


OnPostValidate 


OnPreExecute 


OnPreValidate 


OnProgress 


OnQueryCancel 


OnTaskFailed 


OnVariableValueChanged 


OnWarning 


DESCRIPTION 


Writes a log entry when an error occurs. 


Writes a log entry when a task (not a container) is 
suspended or resumed during debugging. 


Writes a log entry during the validation and execution of an 
executable to report information. 


Writes a log entry immediately after the executable has 
finished running. 


Writes a log entry when the validation of the executable 
finishes. 


Writes a log entry immediately before the executable runs. 


Writes a log entry when the validation of the executable 
starts. 


Writes a log entry when measurable progress is made by the 
executable. 


Writes a log entry at any juncture in the task processing 
where it is feasible to cancel execution. 


Writes a log entry when a task fails. 


Writes a log entry when the value of a variable changes. 


Writes a log entry when a warning occurs. 


EVENTS DESCRIPTION 


PipelineComponentTime For each data flow component, writes a log entry for each 
phase of validation and execution. The log entry specifies the 
processing time for each phase. 


Diagnostic Writes a log entry that provides diagnostic information. 


DiagnosticEx For example, you can log a message before and after every 
call to an external data provider. For more information, see 
Troubleshooting Tools for Package Execution. 


Log the DiagnosticEx event when you want to find the 
column names for columns in the data flow that have errors. 
This event writes a data flow lineage map to the log. You can 
then look up the column name in this lineage map by using 
the column identifier captured by an error output. For more 
info, see Error Handling in Data. 


Note that the DiagnosticEx event does not preserve 
whitespace in its XML output to reduce the size of the log. 
To improve readability, copy the log into an XML editor - in 
Visual Studio, for example - that supports XML formatting 
and syntax highlighting. 


Note: If you log the DiagnosticEx event with the SQL 
Server log provider, the output may be truncated. The 
message field of the SQL Server log provider is of type 
nvarchar(2048). To avoid truncation, use a different log 
provider when you log the DiagnosticEx event. 


The package and many tasks have custom log entries that can be enabled for logging. For example, the Send 
Mail task provides the SendMailTaskBegin custom log entry, which logs information when the Send Mail task 
starts to run, but before the task sends an e-mail message. For more information, see Custom Messages for 
Logging. 


Differentiating Package Copies 


Log data includes the name and the GUID of the package to which the log entries belong. If you create a new 
package by copying an existing package, the name and the GUID of the existing package are also copied. As a 
result, you may have two packages that have the same GUID and name, making it difficult to differentiate 
between the packages in the log data. 


To eliminate this ambiguity, you should update the name and the GUID of the new packages. In SQL Server Data 
Tools (SSDT), you can regenerate the GUID in the ID property and update the value of the Name property in the 
Properties window. You can also change the GUID and the name programmatically, or by using the dtutil 
command prompt. For more information, see Set Package Properties and dtutil Utility. 


Parent Logging Options 


Frequently, the logging options of tasks and For Loop, Foreach Loop, and Sequence containers match those of 
the package or a parent container. In that case, you can configure them to inherit their logging options from 
their parent container. For example, in a For Loop container that includes an Execute SQL task, the Execute SQL 
task can use the logging options that are set on the For Loop container. To use the parent logging options, you 
set the LoggingMode property of the container to UseParentSetting. You can set this property in the 
Properties window of SQL Server Data Tools (SSDT) or through the Configure SSIS Logs dialog box in SSIS 
Designer. 


Logging Templates 


In the Configure SSIS Logs dialog box, you can also create and save frequently used logging configurations as 


templates, and then use the templates in multiple packages. This makes it easy to apply a consistent logging 
strategy across multiple packages and to modify log settings on packages by updating and then applying the 
templates. The templates are stored in XML files. 


To configure logging using the Configure SSIS Logs dialog box 


1. Enable the package and its tasks for logging. Logging can occur at the package, the container, and the task 
level. You can specify different logs for packages, containers, and tasks. 


2. Select a log provider and add a log for the package. Logs can be created only at the package level, anda 
task or container must use one of the logs created for the package. Each log is associated with one of the 
following log providers: Text file, SQL Server Profiler, SQL Server, Windows Event Log, or XML file. For 
more information, see Enable Package Logging in SQL Server Data Tools. 


3. Select the events and the log schema information about each event you want to capture in the log. For 
more information, see Configure Logging by Using a Saved Configuration File. 


Configuration of Log Provider 


You can set properties through SSIS Designer or programmatically. 
A log provider is created and configured as a step in implementing logging in a package. 


After you create a log provider, you can view and modify its properties in the Properties window of SQL Server 
Data Tools (SSDT). 


For information about programmatically setting these properties, see the documentation for the LogProvider 
class. 


Logging for Data Flow Tasks 


The Data Flow task provides many custom log entries that can be used to monitor and adjust performance. For 
example, you can monitor components that might cause memory leaks, or keep track of how long it takes to run 
a particular component. For a list of these custom log entries and sample logging output, see Data Flow Task. 


Capture the names of columns in which errors occur 
When you configure an error output in the data flow, by default the error output provides only the numeric 
identifier of the column in which the error occurred. For more info, see Error Handling in Data. 


You can find column names by enabling logging and selecting the DiagnosticEx event. This event writes a data 
flow lineage map to the log. You can then look up the column name from its identifier in this lineage map. Note 
that the DiagnosticEx event does not preserve whitespace in its XML output to reduce the size of the log. To 
improve readability, copy the log into an XML editor - in Visual Studio, for example - that supports XML 
formatting and syntax highlighting. 


Use the PipelineComponentTime Event 

Perhaps the most useful custom log entry is the PipelineComponentTime event. This log entry reports the 
number of milliseconds that each component in the data flow spends on each of the five major processing steps. 
The following table describes these processing steps. Integration Services developers will recognize these steps 
as the principal methods of a PipelineComponent. 


STEP DESCRIPTION 


Validate The component checks for valid property values and 
configuration settings. 


PreExecute The component performs one-time processing before it 
starts to process rows of data. 


STEP DESCRIPTION 


PostExecute The component performs one-time processing after it has 
processed all rows of data. 


ProcessInput The transformation or destination component processes the 
incoming rows of data that an upstream source or 
transformation has passed to it. 


PrimeOutput The source or transformation component fills the buffers of 
data to be passed to a downstream transformation or 
destination component. 


When you enable the PipelineComponentTime event, Integration Services logs one message for each 
processing step performed by each component. The following log entries show a subset of the messages that 
the Integration Services CalculatedColumns package sample logs: 


The component "Calculate LineItemTotalCost" (3522) spent 356 milliseconds in ProcessInput. 

The component "Sum Quantity and LineItemTotalCost" (3619) spent 79 milliseconds in ProcessInput. 
The component "Calculate Average Cost" (3662) spent 16 milliseconds in ProcessInput. 

The component "Sort by ProductID" (3717) spent 125 milliseconds in ProcessInput. 

The component “Load Data" (3773) spent @ milliseconds in ProcessInput. 


The component "Extract Data" (3869) spent 688 milliseconds in PrimeOutput filling buffers on output "OLE DB 
Source Output" (3879). 


The component "Sum Quantity and LineItemTotalCost" (3619) spent 141 milliseconds in PrimeOutput filling 
buffers on output "Aggregate Output 1" (3621). 


The component "Sort by ProductID" (3717) spent 16 milliseconds in PrimeOutput filling buffers on output "Sort 
Output" (3719). 


These log entries show that the data flow task spent the most time on the following steps, shown here in 
descending order: 


e The OLE DB source that is named "Extract Data" spent 688 ms. loading data. 


@ The Derived Column transformation that is named "Calculate LineltemTotalCost" spent 356 ms. 
performing calculations on incoming rows. 


e The Aggregate transformation that is named "Sum Quantity and LineltemTotalCost" spent a combined 
220 ms-141 in PrimeOutput and 79 in ProcessInput-performing calculations and passing the data to the 
next transformation. 


Enable Package Logging in SQL Server Data Tools 


This procedure describes how to add logs to a package, configure package-level logging, and save the logging 
configuration to an XML file. You can add logs only at the package level, but the package does not have to 
perform logging to enable logging in the containers that the package includes. 





IMPORTANT 


If you deploy the Integration Services project to the Integration Services server, the logging level that you set for the 
package execution overrides the package logging that you configure using SQL Server Data Tools (SSDT). 











By default, the containers in the package use the same logging configuration as their parent container. For 


information about setting logging options for individual containers, see Configure Logging by Using a Saved 


Configuration File. 


To enable logging in a package 


Ts 


2. 


10. 


ale 


In SQL Server Data Tools, open the Integration Services project that contains the package you want. 


On the SSIS menu, click Logging. 


. Select a log provider in the Provider type list, and then click Add. 


. Inthe Configuration column, select a connection manager or click <New connection> to create a new 


connection manager of the appropriate type for the log provider. Depending on the selected provider, use 
one of the following connection managers: 


e For Text files, use a File connection manager. For more information, see File Connection Manager 
e For SQL Server Profiler, use a File connection manager. 


e For SQL Server, use an OLE DB connection manager. For more information, see OLE DB 
Connection Manager. 


e For Windows Event Log, do nothing. SSIS automatically creates the log. 


e For XML files, use a File connection manager. 


. Repeat steps 3 and 4 for each log to use in the package. 





NOTE 


A package can use more than one log of each type. 





. Optionally, select the package-level check box, select the logs to use for package-level logging, and then 


click the Details tab. 


. On the Details tab, select Events to log all log entries, or clear Events to select individual events. 


. Optionally, click Advanced to specify which information to log. 





NOTE 


By default, all information is logged. 





. On the Details tab, click Save. The Save As dialog box appears. Locate the folder in which to save the 


logging configuration, type a file name for the new log configuration, and then click Save. 
Click OK. 


To save the updated package, click Save Selected Items on the File menu. 


Configure SSIS Logs Dialog Box 


Use the Configure SSIS Logs dialog box to define logging options for a package. 


What do you want to do? 


As 


2: 


Open the Configure SSIS Logs Dialog Box 


Configure the Options in the Containers Pane 


3. Configure the Options on the Providers and Logs Tab 
4. Configure the Options on the Details Tab 


Open the Configure SSIS Logs Dialog Box 
To open the Configure SSIS Logs dialog box 


e Inthe SSIS Designer, click Logging on the SSIS menu. 


Configure the Options in the Containers Pane 

Use the Containers pane of the Configure SSIS Logs dialog box to enable the package and its containers for 
logging. 

Options 

Containers 

Select the check boxes in the hierarchical view to enable the package and its containers for logging: 


e If cleared, the container is not enabled for logging. Select to enable logging. 


e If dimmed, the container uses the logging options of its parent. This option is not available for the 
package. 


e If checked, the container defines its own logging options. 


If a container is dimmed and you want to set logging options on the container, click its check box twice. The first 
click clears the check box, and the second click selects it, enabling you to choose the log providers to use and 
select the information to log. 


Configure the Options on the Providers and Logs Tab 


Use the Providers and Logs tab of the Configure SSIS Logs dialog box to create and configure logs for 
capturing run-time events. 


Options 
Provider type 
Select a type of log provider from the list. 


Add 
Add a log of the specified type to the collection of log providers of the package. 


Name 

Enable or disable logs for containers or tasks selected in the Containers pane of the Configure SSIS Logs 
dialog box, by using the check boxes. The name field is editable. Use the default name for the provider, or type a 
unique descriptive name. 


Description 
The description field is editable. Click and then modify the default description of the log. 


Configuration 

Select an existing connection manager in the list, or click <New connection...> to create a new connection 
manager. Depending on the type of log provider, you can configure an OLE DB connection manager or a File 
connection manager. The log provider for the Microsoft Windows Event Log requires no connection. 


Related Topics: OLE DB Connection Manager manager, File Connection Manager 


Delete 
Select a log provider and then click Delete. 


Configure the Options on the Details Tab 
Use the Details tab of the Configure SSIS Logs dialog box to specify the events to enable for logging and the 


information details to log. The information that you select applies to all the log providers in the package. For 
example, you cannot write some information to the SQL Server instance and different information to a text file. 


Options 
Events 
Enable or disable events for logging. 


Description 
View a description of the event. 


Advanced 
Select or clear events to log, and select or clear information to log for each event. Click Basic to hide all logging 
details, except the list of events. The following information is available for logging: 


VALUE DESCRIPTION 

Computer The name of the computer on which the logged event 
occurred. 

Operator The user name of the person who started the package. 

SourceName The name of the package, container, or task in which the 


logged event occurred. 


SourcelD The global unique identifier (GUID) of the package, container, 
or task in which the logged event occurred. 


Execution|ID The global unique identifier of the package execution 
instance. 
MessagetText A message associated with the log entry. 
DataBytes Reserved for future use. 
Basic 


Select or clear events to log. This option hides logging details except the list of events. If you select an event, all 
logging details are selected for the event by default. Click Advanced to show all logging details. 


Load 
Specify an existing XML file to use as a template for setting logging options. 


Save 
Save configuration details as a template to an XML file. 


Configure Logging by Using a Saved Configuration File 


This procedure describes how to configure logging for new containers in a package by loading a previously 


saved logging configuration file. 


By default, all containers in a package use the same logging configuration as their parent container. For example, 


the tasks in a Foreach Loop use the same logging configuration as the Foreach Loop. 


To configure logging for a container 


1. In SQL Server Data Tools, open the Integration Services project that contains the package you want. 


2. On the SSIS menu, click Logging. 


3. Expand the package tree view and select the container to configure. 


4. On the Providers and Logs tab, select the logs to use for the container. 





NOTE 
You can create logs only at the package level. For more information, see Enable Package Logging in SQL Server 
Data Tools. 








5. Click the Details tab and click Load. 
6. Locate the logging configuration file you want to use and click Open. 


7. Optionally, select a different log entry to log by selecting its check box in the Events column. Click 


Advanced to select the type of information to log for this entry. 





NOTE 
The new container may include additional log entries that are not available for the container originally used to 
create the logging configuration. These additional log entries must be selected manually if you want them to be 


logged. 








8. To save the updated version of the logging configuration, click Save. 


9. To save the updated package, click Save Selected Items on the File menu. 


Enable Logging for Package Execution on the SSIS Server 


This topic describes how to set or change the logging level for a package when you run a package that you have 
deployed to the Integration Services server. The logging level you set when you run the package overrides the 
package logging you configure at design time in SQL Server Data Tools (SSDT). See Enable Package Logging in 
SQL Server Data Tools for more information. 


In SQL Server Server Properties, under the Server logging level property, you can select a default server- 
wide logging level. You can pick from one of the built-in logging levels described in this topic, or you can pick an 
existing customized logging level. The selected logging level applies by default to all packages deployed to the 
SSIS Catalog. It also applies by default to a SQL Agent job step that runs an SSIS package. 


You can also specify the logging level for an individual package by using one of the following methods. This 
topic covers the first method. 


e Configuring an instance of a package execution by using the Execute Package dialog box 


e Setting parameters for an instance of an execution by using the catalog.set_execution_parameter_value 
(SSISDB Database) 


e Configuring a SQL Server Agent job for a package execution by using the New Job Step dialog box. 


Set the logging level for a package by using the Execute Package dialog box 


1. In SQL Server Management Studio, navigate to the package in Object Explorer. 

2. Right-click the package and select Execute. 

3. Select the Advanced tab in the Execute Package dialog box. 

4. Under Logging level, select the logging level. This topic contains a description of available values. 


5. Complete any other package configurations, then click OK to run the package. 


Select a logging level 


The following built-in logging levels are available. You can also select an existing customized logging level. This 
topic contains a description of customized logging levels. 


LOGGING LEVEL DESCRIPTION 

None Logging is turned off. Only the package execution status is 
logged. 

Basic All events are logged, except custom and diagnostic events. 


This is the default value. 


RuntimeLineage Collects the data required to track lineage information in the 
data flow. You can parse this lineage information to map the 
lineage relationship between tasks. ISVs and developers can 
build custom lineage mapping tools with this information. 


Performance Only performance statistics, and OnError and OnWarning 
events, are logged. 


The Execution Performance report displays Active Time 
and Total Time for package data flow components. This 
information is available when the logging level of the last 
package execution was set to Performance or Verbose. 
For more information, see Reports for the Integration 
Services Server. 


The catalog.execution_component_phases view displays the 
start and end times for the data flow components, for each 
phase of an execution. This view displays this information for 
these components only when the logging level of the 
package execution is set to Performance or Verbose. 


LOGGING LEVEL 


Verbose 


DESCRIPTION 


All events are logged, including custom and diagnostic 
events. 


Custom events include those events that are logged by 
Integration Services tasks. For more information about 
custom events, see Custom Messages for Logging. 


An example of a diagnostic event is the DiagnosticEx 
event. Whenever an Execute Package task executes a child 
package, this event captures the parameter values passed to 
child packages. 


The DiagnosticEx event also helps you to get the names of 
columns in which row-level errors occur. This event writes a 
data flow lineage map to the log. You can then look up the 
column name in this lineage map by using the column 
identifier captured by an error output. For more info, see 
Error Handling in Data. 


The value of the message column for DiagnosticEx is XML 
text. To view the message text for a package execution, 
query the catalog.operation_messages (SSISDB Database) 
view. Note that the DiagnosticEx event does not preserve 
whitespace in its XML output to reduce the size of the log. 
To improve readability, copy the log into an XML editor - in 
Visual Studio, for example - that supports XML formatting 
and syntax highlighting. 


The catalog.execution_data_statistics view displays a row 
each time a data flow component sends data to a 
downstream component, for a package execution. The 
logging level must be set to Verbose to capture this 
information in the view. 


Create and manage customized logging levels by using the Customized Logging Level Management dialog 


box 


You can create customized logging levels that collect only the statistics and events that you want. Optionally you 


can also capture the context of events, which includes variable values, connection strings, and component 


properties. When you run a package, you can select a customized logging level wherever you can select a built- 


in logging level. 





TIP 


To capture the values of package variables, the IncludelnDebugDump property of the variables must be set to True. 





. To create and manage customized logging levels, in SQL Server Management Studio, right-click on the 


SSISDB database and select Customized Logging Level to open the Customized Logging Level 


Management dialog box. The Customized Logging Levels list contains all the existing customized 


logging levels. 


. To create a new customized logging level, click Create, and then provide a name and description. On the 


Statistics and Events tabs, select the statistics and events that you want to collect. On the Events tab, 


optionally select Include Context for individual events. Then click Save. 


. Toupdate an existing customized logging level, select it in the list, reconfigure it, and then click Save. 


. To delete an existing customized logging level, select it in the list, and then click Delete. 


Permissions for customized logging levels. 


e All users of the SSISDB database can see customized logging levels and select a customized logging level 
when they run packages. 


e Only users in the ssis_admin or sysadmin role can create, update, or delete customized logging levels. 


Custom Messages for Logging 


SQL Server Integration Services provides a rich set of custom events for writing log entries for packages and 
many tasks. You can use these entries to save detailed information about execution progress, results, and 
problems by recording predefined events or user-defined messages for later analysis. For example, you can 
record when a bulk insert begins and ends to identify performance issues when the package runs. 


The custom log entries are a different set of entries than the set of standard logging events that are available for 
packages and all containers and tasks. The custom log entries are tailored to capture useful information about a 
specific task in a package. For example, one of the custom log entries for the Execute SQL task records the SQL 
statement that the task executes in the log. 


All log entries include date and time information, including the log entries that are automatically written when a 
package begins and finishes. Many of the log events write multiple entries to the log. This typically occurs when 
the event has different phases. For example, the ExecuteSQLExecutingQuery log event writes three entries: 
one entry after the task acquires a connection to the database, another after the task starts to prepare the SQL 
statement, and one more after the execution of the SQL statement is completed. 


The following Integration Services objects have custom log entries: 
Package 

Bulk Insert Task 

Data Flow Task 

Execute DTS 2000 Task 

Execute Process Task 

Execute SQL Task 

File System Task 

FTP Task 

Message Queue Task 

Script Task 

Send Mail Task 

Transfer Database Task 

Transfer Error Messages Task 

Transfer Jobs Task 

Transfer Logins Task 

Transfer Master Stored Procedures Task 
Transfer SQL Server Objects Task 


Web Services Task 


WMI Data Reader Task 
WMI Event Watcher Task 
XML Task 


Log Entries 


Package 


The following table lists the custom log entries for packages. 


LOG ENTRY 


PackageStart 


PackageEnd 


Diagnostic 


Bulk Insert Task 


DESCRIPTION 


Indicates that the package began to run. This log entry is 
automatically written to the log. You cannot exclude it. 


Indicates that the package completed. This log entry is 
automatically written to the log. You cannot exclude it. 


Provides information about the system configuration that 
affects package execution such as the number executables 
that can be run concurrently. 


The Diagnostic log entry also includes before and after 
entries for calls to external data providers. 


The following table lists the custom log entries for the Bulk Insert task. 


LOG ENTRY 


DTSBulkinsertTaskBegin 


DTSBulkInsertTaskEnd 


DTSBulkInsertTaskInfos 


Data Flow Task 


DESCRIPTION 


Indicates that the bulk insert began. 


Indicates that the bulk insert finished. 


Provides descriptive information about the task. 


The following table lists the custom log entries for the Data Flow task. 


LOG ENTRY 


BufferSizeTuning 


OnPipelinePostEndOfRowset 


OnPipelinePostPrimeOutput 


DESCRIPTION 


Indicates that the Data Flow task changed the size of the 
buffer. The log entry describes the reasons for the size 
change and lists the temporary new buffer size. 


Denotes that a component has been given its end-of-rowset 
signal, which is set by the last call of the ProcessInput 
method. An entry is written for each component in the data 
flow that processes input. The entry includes the name of 
the component. 


Indicates that the component has completed its last call to 
the PrimeOutput method. Depending on the data flow, 
multiple log entries may be written. If the component is a 
source, this means that the component has finished 
processing rows. 


LOG ENTRY 


OnPipelinePreEndOfRowset 


OnPipelinePrePrimeOutput 


OnPipelineRowsSent 


PipelineBufferLeak 


PipelineExecutionPlan 


PipelineExecutionTrees 


Pipelinelnitialization 


Execute DTS 2000 Task 


DESCRIPTION 


Indicates that a component is about to receive its end-of- 
rowset signal, which is set by the last call of the 
ProcessInput method. An entry is written for each 
component in the data flow that processes input. The entry 
includes the name of the component. 


Indicates that the component is about to receive its call from 
the PrimeOutput method. Depending on the data flow, 
multiple log entries may be written. 


Reports the number of rows provided to a component input 
by a call to the ProcessInput method. The log entry 
includes the component name. 


Provides information about any component that kept 
buffers alive after the buffer manager goes away. This means 
that buffers resources were not released and may cause 
memory leaks. The log entry provides the name of the 
component and the ID of the buffer. 


Reports the execution plan of the data flow. It provides 
information about how buffers will be sent to components. 
This information, in combination with the 
PipelineExecutionTrees entry, describes what is occurring in 
the task. 


Reports the execution trees of the layout in the data flow. 
The scheduler of the data flow engine use the trees to build 
the execution plan of the data flow. 


Provides initialization information about the task. This 
information includes the directories to use for temporary 
storage of BLOB data, the default buffer size, and the 
number of rows in a buffer. Depending on the configuration 
of the Data Flow task, multiple log entries may be written. 


The following table lists the custom log entries for the Execute DTS 2000 task. 


LOG ENTRY 


ExecuteDTS80PackagelaskBegin 


ExecuteDTS80PackageTaskEnd 


ExecuteDTS80PackagetlaskTaskInfo 


ExecuteDTS80PackagetTaskTaskResult 


Execute Process Task 


DESCRIPTION 


Indicates that the task began to run a DTS 2000 package. 


Indicates that the task finished. 


Note: The DTS 2000 package may continue to run after the 
task ends. 


Provides descriptive information about the task. 


Reports the execution result of the DTS 2000 package that 
the task ran. 


The following table lists the custom log entries for the Execute Process task. 


LOG ENTRY DESCRIPTION 


ExecuteProcessExecutingProcess Provides information about the process of running the 
executable that the task is configured to run. 


Two log entries are written. One contains information about 
the name and location of the executable that the task runs, 
and the other records the exit from the executable. 


ExecuteProcessVariableRouting Provides information about which variables are routed to the 
input and outputs of the executable. Log entries are written 
for stdin (the input), stdout (the output), and stderr (the 
error output). 


Execute SQL Task 


The following table describes the custom log entry for the Execute SQL task. 


LOG ENTRY DESCRIPTION 


ExecuteSQLExecutingQuery Provides information about the execution phases of the SQL 
statement. Log entries are written when the task acquires 
connection to the database, when the task starts to prepare 
the SQL statement, and after the execution of the SQL 
statement is completed. The log entry for the prepare phase 
includes the SQL statement that the task uses. 


File System Task 


The following table describes the custom log entry for the File System task. 


LOG ENTRY DESCRIPTION 


FileSystemOperation Reports the operation that the task performs. The log entry 
is written when the file system operation starts and includes 
information about the source and destination. 


FTP Task 


The following table lists the custom log entries for the FTP task. 


LOG ENTRY DESCRIPTION 

FTPConnectingToServer Indicates that the task initiated a connection to the FTP 
server. 

FTPOperation Reports the beginning of and the type of FTP operation that 


the task performs. 


Message Queue Task 


The following table lists the custom log entries for the Message Queue task. 


LOG ENTRY DESCRIPTION 
MSMQAfterOpen Indicates that the task finished opening the message queue. 
MSMQBeforeOpen Indicates that the task began to open the message queue. 


MSMQBeginReceive Indicates that the task began to receive a message. 


LOG ENTRY DESCRIPTION 


MSMQBeginSend Indicates that the task began to send a message. 
MSMQEndReceive Indicates that the task finished receiving a message. 
MSMQEndSend Indicates that the task finished sending a message 
MSMAQtTaskInfo Provides descriptive information about the task. 
MSMQTaskTimeOut Indicates that the task timed out. 

Script Task 


The following table describes the custom log entry for the Script task. 


LOG ENTRY DESCRIPTION 


ScriptTaskLogEntry Reports the results of implementing logging in the script. A 
log entry is written for each call to the Log method of the 
Dts object. The entry is written when the code is run. For 
more information, see Logging in the Script Task. 


Send Mail Task 


The following table lists the custom log entries for the Send Mail task. 


LOG ENTRY DESCRIPTION 

SendMailTaskBegin Indicates that the task began to send an e-mail message. 
SendMailTaskEnd Indicates that the task finished sending an e-mail message. 
SendMailTaskInfo Provides descriptive information about the task. 


Transfer Database Task 


The following table lists the custom log entries for the Transfer Database task. 


LOG ENTRY DESCRIPTION 
SourceDB Specifies the database that the task copied. 
SourceSQLServer Specifies the computer from which the database was copied. 


Transfer Error Messages Task 


The following table lists the custom log entries for the Transfer Error Messages task. 


LOG ENTRY DESCRIPTION 

TransferErrorMessages laskFinishedTransferringObjec Indicates that the task finished transferring error messages. 
ts 

TransferErrorMessagesTaskStartTransferringObjects Indicates that the task started to transfer error messages. 


Transfer Jobs Task 


The following table lists the custom log entries for the Transfer Jobs task. 


LOG ENTRY DESCRIPTION 


TransferJobsTaskFinishedTransferringObjects Indicates that the task finished transferring SQL Server 
Agent jobs. 

TransferJobsTaskStartTransferringObjects Indicates that the task started to transfer SQL Server Agent 
jobs. 


Transfer Logins Task 


The following table lists the custom log entries for the Transfer Logins task. 


LOG ENTRY DESCRIPTION 
TransferLoginsTaskFinishedTransferringObjects Indicates that the task finished transferring logins. 
TransferLoginsTaskStartTransferringObjects Indicates that the task started to transfer logins. 


Transfer Master Stored Procedures Task 


The following table lists the custom log entries for the Transfer Master Stored Procedures task. 


LOG ENTRY DESCRIPTION 

TransferStoredProcedures TaskFinishedTransferringOb Indicates that the task finished transferring user-defined 
jects stored procedures that are stored in the master database. 
TransferStoredProcedures TaskStartTransferringObject Indicates that the task started to transfer user-defined 

s stored procedures that are stored in the master database. 


Transfer SQL Server Objects Task 


The following table lists the custom log entries for the Transfer SQL Server Objects task. 
LOG ENTRY DESCRIPTION 


TransferSqlServerObjectsTaskFinishedTransferringObj Indicates that the task finished transferring SQL Server 


ects database objects. 
TransferSqlServerObjectsTaskStartTransferringObject Indicates that the task started to transfer SQL Server 
s database objects. 


Web Services Task 


The following table lists the custom log entries that you can enable for the Web Services task. 


LOG ENTRY DESCRIPTION 

WSTaskBegin The task began to access a Web service. 
WSTaskEnd The task completed a Web service method. 
WSTaskinfo Descriptive information about the task. 


WMI Data Reader Task 
The following table lists the custom log entries for the WMI Data Reader task. 


LOG ENTRY DESCRIPTION 
WMIDataReaderGettingWMIData Indicates that the task began to read WMI data. 


WM IDataReaderOperation Reports the WQL query that the task ran. 


WMI Event Watcher Task 


The following table lists the custom log entries for the WMI Event Watcher task. 


LOG ENTRY DESCRIPTION 

WMlEventWatcherEventOccurred Denotes that the event occurred that the task was 
monitoring. 

WMlEventWatcherTimedout Indicates that the task timed out. 

WMlEventWatcherWatchingForWMlEvents Indicates that the task began to execute the WQL query. The 


entry includes the query. 


XML Task 


The following table describes the custom log entry for the XML task. 


LOG ENTRY DESCRIPTION 
XMLOperation Provides information about the operation that the task 
performs 


Related Tasks 


The following list contains links to topics that show how to perform tasks related to the logging feature. 


e Events Logged by an Integration Services Package 


Performance Counters 
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Integration Services installs a set of performance counters that you can use to monitor the performance of the 
data flow engine. For example, you can watch the "Buffers spooled" counter to determine whether data buffers 


are being written to disk temporarily while a package is running. This swapping reduces performance and 


indicates that the computer has insufficient memory. 


NOTE: If you install Integration Services on a computer that is running Windows Server 2003, and then 
upgrade that computer to Windows Server 2008, the upgrade process removes the Integration Services 


performance counters from the computer. To restore the Integration Services performance counters on the 


computer, run SQL Server Setup in repair mode. 


The following table describes the performance counters. 
PERFORMANCE COUNTER 


BLOB bytes read 


BLOB bytes written 


BLOB files in use 


Buffer memory 


Buffers in use 


Buffers spooled 


Flat buffer memory 


Flat buffers in use 


DESCRIPTION 


The number of bytes of binary large object (BLOB) data that 
the data flow engine has read from all sources. 


The number of bytes of BLOB data that the data flow engine 
has written to all destinations. 


The number of BLOB files that the data flow engine currently 
is using for spooling. 


The amount of memory that is in use. This may include both 
physical and virtual memory. When this number is larger 
than the amount of physical memory, the Buffers Spooled 
count rises as an indication that memory swapping is 
increasing. Increased memory swapping slows performance 
of the data flow engine. 


The number of buffer objects, of all types, that all data flow 
components and the data flow engine is currently using. 


The number of buffers currently written to the disk. If the 
data flow engine runs low on physical memory, buffers not 
currently used are written to disk and then reloaded when 
needed. 


The total amount of memory, in bytes, that all flat buffers 
use. Flat buffers are blocks of memory that a component 
uses to store data. A flat buffer is a large block of bytes that 
is accessed byte by byte. 


The number of flat buffers that the Data flow engine uses. Alll 
flat buffers are private buffers. 


PERFORMANCE COUNTER DESCRIPTION 


Private buffer memory The total amount of memory in use by all private buffers. A 
buffer is not private if the data flow engine creates it to 
support data flow. A private buffer is a buffer that a 
transformation uses for temporary work only. For example, 
the Aggregation transformation uses private buffers to do 


its work. 
Private buffers in use The number of buffers that transformations use. 
Rows read The number of rows that a source produces. The number 


does not include rows read from reference tables by the 
Lookup transformation. 


Rows written The number of rows offered to a destination. The number 
does not reflect rows written to the destination data store. 


You use the Performance Microsoft Management Console (MMC) snap-in to create a log that captures 


performance counters. 


For information about how to improve performance, see Data Flow Performance Features. 


Obtain Performance Counter Statistics 


For Integration Services projects that are deployed to the Integration Services server, you can obtain 
performance counter statistics by using the dm_execution_performance_counters (SSISDB Database) function. 


In the following example, the function returns statistics for a running execution with an ID of 34. 
select * from [catalog].[dm_execution_performance_counters] (34) 


In the following example, the function returns statistics for all the executions running on the Integration Services 
server. 


select * from [catalog].[dm_execution_performance_counters] (NULL) 


IMPORTANT!! If you are a member of the ssis_admin database role, performance statistics for all running 
executions are returned. If you are not a member of the ssis_admin database role, performance statistics 
for the running executions for which you have read permissions, are returned. 


Related Content 


e Video, Measuring and Understanding the Performance of Your SSIS Packages in the Enterprise (SQL 
Server Video), on msdn.microsoft.com. 


e Support article, The SSIS performance counter is no longer available in the Performance Monitor after 


you upgrade to Windows Server 2008, on support.microsoft.com. 


Add a Log for Data Flow Performance Counters 


This procedure describes how to add a log for the performance counters that the data flow engine provides. 








NOTE 


If you install Integration Services on a computer that is running Windows Server 2003, and then upgrade that computer 
to Windows Server 2008, the upgrade process removes the Integration Services performance counters from the 
computer. To restore the Integration Services performance counters on the computer, run SQL Server Setup in repair 
mode. 





To add logging of performance counters 














1. In Control Panel, if you are using Classic view, click Administrative Tools. If you are using Category 
view, click Performance and Maintenance and then click Administrative Tools. 

2. Click Performance. 

3. In the Performance dialog box, expand Performance Logs and Alerts, right-click Counter Logs, and 
then click New Log Settings. Type the name of the log. For example, type MyLog. 

4. Click OK. 

5. In the MyLog dialog box, click Add Counters. 

6. Click Use local computer counters to log performance counters on the local computer, or click Select 
counters from computer and then select a computer from the list to log performance counters on the 
specified computer. 

7. Inthe Add Counters dialog box, select SQL Server:SSIS Pipeline in the Performance object list. 

8. To select performance counters, do one of the following: 

e Select All Counters to log all performance counters. 
e Select Select counters in list and select the performance counters to use. 
9. Click Add. 
10. Click Close. 
11. In the MyLog dialog box, review the list of logging performance counters in the Counters list. 
12. To add additional counters, repeat steps 5 through 10. 
13. Click OK. 
NOTE 
You must start the Performance Logs and Alerts service using a local account or a domain account that is a 
member of the Administrators group. 
See Also 


Execution of Projects and Packages Events Logged by an Integration Services Package 


Troubleshoot Integration Services (SSIS) Packages 
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In this section 


® Troubleshooting Tools for Package Development 


Troubleshooting Tools for Package Connectivity 


e Troubleshooting Tools for Package Execution 


Troubleshooting Reports for Package Development 


e@ Generating Dump Files for Package Execution 


Troubleshooting Tools for Package Development 
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Integration Services includes features and tools that you can use to troubleshoot packages while you are 
developing them in SQL Server Data Tools (SSDT). 


Troubleshooting Design-time Validation Issues 


In the current release of Integration Services, when a package is opened, the system validates all connections 
before validating all of the data flow components and sets any connections that are slow or unavailable to work 
offline. This helps reduce the delay in validating the package data flow. 


After a package is opened, you can also turn off a connection by right-clicking the connection manager in the 
Connection Managers area and then clicking Work Offline. This can speed up operations in the SSIS 
Designer. 


Connections that have been set to work offline, will remain offline until you do one of the following: 


e Test the connection by right-clicking the connection manager in the Connection Managers area of SSIS 
Designer and then clicking Test Connectivity. 


For example, a connection is initially set to work offline when the package is opened. You modify the 
connection string to resolve the issue and click Test Connectivity to test the connection. 


e Re-open the package or re-open the project that contains the package. Validation is run again on all of the 
connections in the package. 


Integration Services includes the following, additional features to help you avoid validation errors : 


e Set all of the package and all of the connections to work offline when data sources are not 
available. You can enable Work Offline from the SSIS menu. Unlike the DelayValidation property, 
the Work Offline option is available even before you open a package. You can also enable Work 
Offline to speed up operations in the designer, and disable it only when you want your package to be 
validated. 


e Configure the DelayValidation property on package elements that are not valid until run 
time. You can set DelayValidation to True on package elements whose configuration is not valid at 
design time to prevent validation errors. For example, you may have a Data Flow task that uses a 
destination table that does not exist until an Execute SQL task creates the table at run time. The 
DelayValidation property can be enabled at the package level, or at the level of the individual tasks and 
containers that the package includes. Normally you must leave this property set to True on the same 
package elements when you deploy the package, to prevent the same validation errors at run time. 


The DelayValidation property can be set on a Data Flow task, but not on individual data flow 
components. You can achieve a similar effect by setting the ValidateExternalMetadata property of 
individual data flow components to false. However, when the value of this property is false, the 
component is not aware of changes to the metadata of external data sources. 


If database objects that are used by the package are locked when validation occurs, the validation process might 
stop responding. In these circumstances, the SSIS Designer also stops responding. You can resume validation by 
using Management Studio to close the associated session in SQL Server. You can also avoid this issue by using 


the settings described in this section. 


Troubleshooting Control Flow 


Integration Services includes the following features and tools that you can use to troubleshoot the control flow 


in packages during package development: 


Set breakpoints on tasks, containers, and the package. You can set breakpoints by using the 
graphical tools that SSIS Designer provides. Breakpoints can be enabled at the package level, or at the 
level of the individual tasks and containers that the package includes. Some tasks and containers provide 
additional break conditions for setting breakpoints. For example, you can enable a break condition on the 
For Loop container that suspends execution at the start of each iteration of the loop. 


Use the debugging windows. When you run a package that has breakpoints, the debug windows in 
SQL Server Data Tools (SSDT) provide access to variable values and status messages. 


Review the information on the Progress tab. SSIS Designer provides additional information about 
control flow when you run a package in SQL Server Data Tools (SSDT). The Progress tab lists tasks and 
containers in order of execution and includes start and finish times, warnings, and error messages for 
each task and container, including the package itself. 


For more information on these features, see Debugging Control Flow. 


Troubleshooting Data Flow 


Integration Services includes the following features and tools that you can use to troubleshoot the data flows in 


packages during package development: 


Test with only a subset of your data. If you want to troubleshoot the data flow in a package by using 
only a sample of the dataset, you can include a Percentage Sampling or Row Sampling transformation to 
create an in-line data sample at run time. For more information, see Percentage Sampling Transformation 
and Row Sampling Transformation. 


Use data viewers to monitor data as it moves through the data flow. Data viewers display data 
values as the data moves between sources, transformations, and destinations. A data viewer can display 
data in a grid. You can copy the data from a data viewer to the Clipboard, and then paste the data into a 
file or Excel spreadsheet. For more information, see Debugging Data Flow . 


Configure error outputs on data flow components that support them. Many data flow sources, 
transformations, and destinations also support error outputs. By configuring the error output of a data 
flow component, you can direct data that contains errors to a different destination. For example, you can 
capture the data that failed or was truncated in a separate text file. You can also attach data viewers to 
error outputs and examine only the erroneous data. At design time, error outputs capture troublesome 
data values to help you develop packages that deal effectively with real-world data. However, while other 
troubleshooting tools and features are useful only at design time, error outputs retain their usefulness in 
the production environment. For more information, see Error Handling in Data. 


Capture the count of rows processed. When you run a package in SSIS Designer, the number of rows 
that have passed through a path is displayed in the data flow designer. This number is updated 
periodically while the data moves through the path. You can also add a Row Count transformation to the 
data flow to capture the final row count in a variable. For more information, see Row Count 
Transformation. 


Review the information on the Progress tab. SSIS Designer provides additional information about 
data flows when you run a package in SQL Server Data Tools (SSDT). The Progress tab lists data flow 
components in order of execution and includes information about progress for each phase of the 


package, displayed as percentage complete, and the number of rows written to the destination. 


For more information on these features, see Debugging Data Flow. 


Troubleshooting Scripts 


Microsoft Visual Studio Tools for Applications (VSTA) is the development environment in which you write the 
scripts that are used by the Script task and Script component. VSTA provides the following features and tools 
that you can use to troubleshoot scripts during package development: 


e Set breakpoints in script in Script tasks. VSTA provides debugging support for scripts in the Script 
task only. The breakpoints that you set in Script tasks are integrated with the breakpoints that you set on 
packages and the tasks and containers in the package, enabling seamless debugging of all package 


elements. 


NOTE 
When you debug a package that contains multiple Script tasks, the debugger hits breakpoints in only one Script 
task and will ignore breakpoints in the other Script tasks. If a Script task is part of a Foreach Loop or For Loop 


container, the debugger ignores breakpoints in the Script task after the first iteration of the loop. 





For more information, see Debugging Script. For suggestions about how to debug the Script component, see 
Coding and Debugging the Script Component. 


Troubleshooting Errors without a Description 


If you encounter an Integration Services error number without an accompanying description during package 
development, you can locate the description in Integration Services Error and Message Reference. The list does 
not include troubleshooting information at this time. 


See Also 


Troubleshooting Tools for Package Execution 
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Debugging Control Flow 
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SQL Server Data Tools (SSDT) and Microsoft Integration Services include features and tools that you can use to 
troubleshoot the control flow in an Integration Services package. 


e Integration Services supports breakpoints on containers and tasks. 
e SSIS Designer provides progress reporting at run time. 


e SQL Server Data Tools (SSDT) provides debug windows. 


Breakpoints 


SSIS Designer provides the Set Breakpoints dialog box, in which you can set breakpoints by enabling break 
conditions and specifying the number of times a breakpoint can occur before the execution of the package is 
suspended. Breakpoints can be enabled at the package level, or at the level of the individual component. If break 
conditions are enabled at the task or container level, the breakpoint icon appears next to the task or container on 
the design surface of the Control Flow tab. If the break conditions are enabled on the package, the breakpoint 
icon appears on the label of the Control Flow tab. 


When a breakpoint is hit, the breakpoint icon changes to help you identify the source of the breakpoint. You can 


add, delete, and change breakpoints when the package is running. 


Integration Services provides ten break conditions that you can enable on all tasks and containers. In the Set 


Breakpoints dialog box, you can enable breakpoints on the following conditions: 


BREAK CONDITION 


When the task or container receives the OnPreExecute 
event. 


When the task or container receives the OnPostExecute 
event. 


When the task or container receives the OnError event. 


When the task or container receives the OnWarning event. 


When the task or container receives the OnInformation 
event. 


When the task or container receives the OnTaskFailed 
event. 


When the task or container receives the OnProgress event. 


When the task or container receives the OnQueryCancel 
event. 


DESCRIPTION 


Called when a task is about to execute. This event is raised 
by a task or a container immediately before it runs. 


Called immediately after the execution logic of the task 
finishes. This event is raised by a task or container 
immediately after it runs. 


Called by a task or container when an error occurs. 


Called when the task is in a state that does not justify an 
error, but does warrant a warning. 


Called when the task is required to provide information. 


Called by the task host when it fails. 


Called to update progress about task execution. 


Called at any time in task processing when you can cancel 
execution. 


BREAK CONDITION DESCRIPTION 


When the task or container receives the Called by the Integration Services runtime when the value of 
OnVariableValueChanged event. a variable changes. The RaiseChangeEvent of the variable 
must be set to true to raise this event. 


** Warning ** The variable associated with this breakpoint 
must be defined at the container scope. If the variable is 
defined at the package scope, the breakpoint does not get 
hit. 


When the task or container receives the OnCustomEvent Called by tasks to raise custom task-defined events. 
event. 


In addition to the break conditions available to all tasks and containers, some tasks and containers include 
special break conditions for setting breakpoints. For example, you can enable a break condition on the For Loop 
container that sets a breakpoint that suspends execution at the start of each iteration of the loop. 


To add flexibility and power to a breakpoint, you can modify the behavior of a breakpoint by specifying the 
following options: 


e@ The hit count, or the maximum number of times that a break condition occurs before the execution is 
suspended. 


e The hit count type, or the rule that specifies when the break condition triggers the breakpoint. 


The hit count types, except for the Always type, are further qualified by the hit count. For example, if the type is 
"Hit count equals" and the hit count is 5, execution is suspended on the sixth occurrence of the break condition. 


The following table describes the hit count types. 


HIT COUNT TYPE DESCRIPTION 
Always Execution is always suspended when the breakpoint is hit. 
Hit count equals Execution is suspended when the number of times the 


breakpoint has occurred is equal to the hit count. 


Hit count greater than or equal to Execution is suspended when the number of times the 
breakpoint has occurred is equal to or greater than the hit 
count. 

Hit count multiple Execution is suspended when a multiple of the hit count 


occurs. For example, if you set this option to 5, execution is 
suspended every fifth time. 


To set breakpoints 


e Debug a Package by Setting Breakpoints on a Task or a Container 


Progress Reporting 


SSIS Designer includes two types of progress reporting: color-coding on the design surface of the Control 
Flow tab, and progress messages on the Progress tab. 


When you run a package, SSIS Designer depicts execution progress by displaying each task or container using a 
color that indicates execution status. You can tell by its color whether the element is waiting to run, currently 
running, has completed successfully, or has ended unsuccessfully. After you stop package execution, the color- 
coding disappears. 


The following table describes the colors that are used to depict execution status. 


COLOR EXECUTION STATUS 
Gray Waiting to run 
Yellow Running 

Green Ran successfully 
highlighted Ran with errors 


The Progress tab lists tasks and containers in execution order and includes the start and finish times, warnings, 
and error messages. After you stop package execution, the progress information remains available on the 
Execution Results tab. 


NOTE 


To enable or disable the display of messages on the Progress tab, toggle the Debug Progress Reporting option on 
the SSIS menu. 





The following diagram shows the Progress tab. 
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[Package execution completed. To switch to design mode, select Stop Debugging .. 


Debug Windows 


SQL Server Data Tools (SSDT) includes many windows that you can use to work with breakpoints, and to debug 
packages that contain breakpoints. To learn more about each window, open the window, and then press F1 to 
display Help for the window. 


To open these windows in SQL Server Data Tools (SSDT), click the Debug menu, point to Windows, and then 
click Breakpoints, Output, or Immediate. 


The following table describes each window. 


WINDOW DESCRIPTION 


Breakpoints Lists the breakpoints in a package and provides options to 
enable and delete breakpoints. 


WINDOW DESCRIPTION 


Output Displays status messages for features in SQL Server Data 
Tools (SSDT). 

Immediate Used to debug and evaluate expressions and print variable 
values. 


Debug a Package by Setting Breakpoints on a Task or a Container 


This procedure describes how to set breakpoints in a package, a task, a For Loop container, a Foreach Loop 


container, or a Sequence container. 


To set breakpoints in a package, a task, or a container 


1. In SQL Server Data Tools (SSDT), open the Integration Services project that contains the package you 


want. 
2. Double-click the package in which you want to set breakpoints. 
3. In SSIS Designer, do the following: 


e To set breakpoints in the package object, click the Control Flow tab, place the cursor anywhere on 
the background of the design surface, right-click, and then click Edit Breakpoints. 


e Toset breakpoints in a package control flow, click the Control Flow tab, right-click a task, a For 
Loop container, a Foreach Loop container, or a Sequence container, and then click Edit 


Breakpoints. 


e To set breakpoints in an event handler, click the Event Handler tab, right-click a task, a For Loop 
container, a Foreach Loop container, or a Sequence container, and then click Edit Breakpoints. 


4. In the Set Breakpoints <container name> dialog box, select the breakpoints to enable. 
5. Optionally, modify the hit count type and the hit count number for each breakpoint. 


6. To save the package, click Save Selected Items on the File menu. 


Set Breakpoints 


Use the Set Breakpoints dialog box to specify the events on which to enable breakpoints and to control the 
behavior of the breakpoint. 


Options 
Enabled 
Select to enable a breakpoint on an event. 


Break Condition 
View a list of available events on which to set breakpoints. 


Hit Count Type 
Specify when the breakpoint takes effect. 


VALUE DESCRIPTION 


Always Execution is always suspended when the breakpoint is hit. 


VALUE 


Hit count equals 


Hit greater or equal 


Hit count multiple 


Hit Count 


DESCRIPTION 


Execution is suspended when the number of times the 
breakpoint has occurred is equal to the hit count. 


Execution is suspended when the number of times the 
breakpoint has occurred is equal to or greater than the hit 
count. 


Execution is suspended when a multiple of the hit count 
occurs. For example, if you set this option to 5, execution is 
suspended every fifth time. 


Specify the number of hits at which to trigger a break. This option is not available if the breakpoint is always in 


effect. 


See Also 


Troubleshooting Tools for Package Development 


Debug a Script by Setting Breakpoints in a Script Task and Script Component 


Debugging Script 
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You write the scripts that the Script task and Script component use, in Microsoft Visual Studio Tools for 
Applications (VSTA). 


You set and script breakpoints in VSTA. You can manage breakpoints in VSTA, but you can also manage the 
breakpoints using the Set Breakpoints dialog box that SSIS Designer provides. For more information, see 
Debugging Control Flow. 


The Set Breakpoints dialog box includes the script breakpoints. These breakpoints appear at the bottom of the 
breakpoint list, and display the line number and the name of the function in which the breakpoint appears. You 
can delete a script breakpoint from the Set Breakpoints dialog box. 


At run time, the breakpoints set on lines of code in script are integrated with the breakpoints set on the package 
or the tasks and containers in the package. The debugger can run from a breakpoint in the script to a breakpoint 
set on the package, task, or container, and vice versa. For example, a package might have breakpoints set on the 
break conditions that occur when the package receives the OnPreExecute and OnPostExecute events, and 
also have a Script task that has breakpoints on lines of its script. In this scenario, the package can suspend 
execution on the break condition associated with the OnPreExecute event, run to the breakpoints in the script, 
and finally run to the break condition associated with the OnPostExecute event. 


For more information about debugging the Script task and Script component, see Coding and Debugging the 
Script Task and Coding and Debugging the Script Component. 


To set a breakpoint in Visual Studio for Applications 


e Debug a Script by Setting Breakpoints in a Script Task and Script Component 


See Also 


Troubleshooting Tools for Package Development 
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Microsoft Integration Services and the SSIS Designer include features and tools that you can use to troubleshoot 
the data flows in an Integration Services package. 


e SSIS Designer provides data viewers. 
e SSIS Designer and Integration Services transformations provide row counts. 


e SSIS Designer provides progress reporting at run time. 


Data Viewers 


Data viewers display data between two components in a data flow. Data viewers can display data when the data 
is extracted from a data source and first enters a data flow, before and after a transformation updates the data, 
and before the data is loaded into its destination. 


To view the data, you attach data viewers to the path that connects two data flow components. The ability to 
view data between data flow components makes it easier to identify unexpected data values, view the way a 
transformation changes column values, and discover the reason that a transformation fails. For example, you 
may find that a lookup in a reference table fails, and to correct this you may want to add a transformation that 
provides default data for blank columns. 


A data viewer can display data in a grid. Using a grid, you select the columns to display. The values for the 
selected columns display in a tabular format. 


You can also include multiple data viewers on a path. You can display the same data in different formats-for 
example, create a chart view and a grid view of the data-or create different data viewers for different columns of 
data. 


When you add a data viewer to a path, SSIS Designer adds a data viewer icon to the design surface of the Data 
Flow tab, next to the path. Transformations that can have multiple outputs, such as the Conditional Split 
transformation, can include a data viewer on each path. 


At run time, a Data Viewer window opens and displays the information specified by the data viewer format. 
For example, a data viewer that uses the grid format shows data for the selected columns, the number of output 
rows passed to the data flow component, and the number of rows displayed. The information displays buffer by 
buffer and, depending on the width of the rows in the data flow, a buffer may contain more or fewer rows. 


In the Data Viewer dialog box, you can copy the data to the Clipboard, clear all data from the table, reconfigure 
the data viewer, resume the flow of data, and detach or attach the data viewer. 


To add a data viewer 


e Add a Data Viewer to a Data Flow 


Row Counts 


The number of rows that have passed through a path is displayed on the design surface of the Data Flow tab in 
SSIS Designer next to the path. The number is updated periodically while the data moves through the path. 


You can also add a Row Count transformation to the data flow to capture the final row count in a variable. For 


more information, see Row Count Transformation. 


Progress Reporting 


When you run a package, SSIS Designer depicts progress on the design surface of the Data Flow tab by 
displaying each data flow component in a color that indicates status. When each component starts to perform 
its work, it changes from no color to yellow, and when it finishes successfully, it changes to green. A red color 
indicates that the component failed. 


The following table describes the color-coding. 


COLOR DESCRIPTION 

No color Waiting to be called by the data flow engine. 

Yellow Performing a transformation, extracting data, or loading 
data. 

Green Ran successfully. 

red Ran with errors. 


Analysis of Data Flow 


You can use the catalog.execution_data_statistics SSISDB database view to analyze the data flow of packages. 
This view displays a row each time a data flow component sends data to a downstream component. The 


information can be used to gain a deeper understanding of the rows that are sent to each component. 





NOTE 


The logging level must be set to Verbose in order to capture information with the catalog.execution_data_statistics view. 





The following example displays the number of rows sent between components of a package. 


use SSISDB 


select package_name, task_name, source_component_name, destination_component_name, rows_sent 
from catalog.execution_data_statistics 
where execution_id = 132 


order by source_component_name, destination_component_name 
The following example calculates the number of rows per millisecond sent by each component for a specific 
execution. The calculated values are: 
e total_rows - the sum of all the rows sent by the component 
e wall_clock_time_ms - the total elapsed execution time, in milliseconds, for each component 
e num_rows_per_millisecond - the number of rows per millisecond sent by each component 


The HAVING clause is used to prevent a divide-by-zero error in the calculations. 


use SSISDB 

select source_component_name, destination_component_name, 
sum(rows_sent) as total_rows, 
DATEDIFF(ms,min(created_time),max(created_time)) as wall_clock_time_ms, 
((@.0+sum(rows_sent)) / (datediff(ms,min(created_time),max(created_time)))) as 

[num_rows_per_millisecond] 

from [catalog]. [execution_data_statistics] 

where execution_id = 132 

group by source_component_name, destination_component_name 

having (datediff(ms,min(created_time),max(created_time))) > @ 

order by source_component_name desc 


Configure an Error Output in a Data Flow Component 


Many data flow components support error outputs, and depending on the component, SSIS Designer provides 
different ways to configure an error output. In addition to configuring an error output, you can also configure 
the columns of an error output. This includes configuring the ErrorCode and ErrorColumn columns that are 
added by the component. 


Configuring an Error Output 


To configure an error output, you have two options: 


e Use the Configure Error Output dialog box. You can use this dialog box to configure an error output on 
any data flow component that supports an error output. 


e Use the editor dialog box for the component. Some components let you configure error outputs directly 
from their editor dialog box. However, you cannot configure error outputs from the editor dialog box for 
the ADO NET source, the Import Column transformation, the OLE DB Command transformation, or the 
SQL Server Compact destination. 


The following procedures describe how to use these dialog boxes to configure error outputs. 


To configure an error output using the Configure Error Output dialog box 


1. In SQL Server Data Tools (SSDT), open the Integration Services project that contains the package you 
want. 


2. In Solution Explorer, double-click the package to open it. 
3. In SSIS Designer, click the Data Flow tab. 


4. Drag the error output, represented by the red arrow, from the component that is the source of the errors 


to another component in the data flow. 


5. In the Configure Error Output dialog box, select an action in the Error and Truncation columns for 


each column in the component input. 


6. To save the updated package, on the File menu, click Save Selected Items. 


To add an error output using the editor dialog box for the component 


1. In SQL Server Data Tools (SSDT), open the Integration Services project that contains the package you 
want. 


2. In Solution Explorer, double-click the package to open it. 
3. In SSIS Designer, click the Data Flow tab. 


4. Double-click the data flow components in which you want to configure an error output and, depending 


on the component, do one of the following steps: 


e Click Configure Error Output. 


e Click Error Output. 
5. Set the Error option for each column. 
6. Set the Truncation option for each column. 
7. Click OK. 
8. To save the updated package, on the File menu, click Save Selected Items. 


Configuring Error Output Columns 


To configure the error output columns, you have to use the Input and Output Properties tab of the 
Advanced Editor dialog box. 


To configure error output columns 
1. In SQL Server Data Tools (SSDT), open the Integration Services project that contains the package you 


want. 
2. In Solution Explorer, double-click the package to open it. 
3. In SSIS Designer, click the Data Flow tab. 


4. Right-click the component whose error output columns you want to configure and click Show 
Advanced Editor. 


5. Click the Input and Output Properties tab and expand <component name> Error Output and 
then expand Output Columns. 


6. Click a column and update its properties. 


NOTE 


The list of columns includes the columns in the component input, the ErrorCode and ErrorColumn columns 


added by previous error outputs, and the ErrorCode and ErrorColumn columns added by this component. 





7. Click OK. 


8. To save the updated package, on the File menu, click Save Selected Items. 


Add a Data Viewer to a Data Flow 


This topic describes how to add and configure a data viewer in a data flow. A data viewer displays data that is 
moving between two data flow components. For example, a data viewer can display the data that is extracted 
from a data source before a transformation in the data flow modifies the data. 


A path connects components in a data flow by connecting the output of one data flow component to the input of 


another component. 


Before you can add data viewers to a package, the package must include a Data Flow task and at least two data 
flow components that are connected. 


Add a data viewer to an error output to see the description of the error and the name of the column in which the 
error occurred. By default the error output includes only numeric identifiers for the error and the column. 


To add a data viewer to a data flow 


1. In SQL Server Data Tools (SSDT), open the Integration Services project that contains the package you 


want. 


2. In Solution Explorer, double-click the package to open it. 


3. Click the Control Flow tab, if it is not already active. 


4. Click the Data Flow task to whose data flow you want to attach a data viewer and then click the Data 
Flow tab. 


5. Right-click a path between two data flow components, and click Edit. 


6. On the General page, you can view and edit path properties. For example, from the PathAnnotation 
drop-down list you can select the annotation that appears next to the path. 


7. On the Metadata page, you can view the column metadata and copy the metadata to the Clipboard. 
8. On the Data Viewer page, click Enable data viewer. 


9. In the Columns to display area, select the columns you want to display in the data viewer. By default, all 
the available columns are selected and listed in the Displayed Columns list. Move columns that you do 
not want to use to the Unused Column list by selecting them and then clicking the left arrow. 





NOTE 


In the grid, values that represent the DT_DATE, DT_DBTIME2, DT_FILETIME, DT_DBTIMESTAMP 
DT_DBTIMESTAMP2, and DT_DBTIMESTAMPOFFSET data types appear as ISO 8601 formatted strings and a space 
separator replaces the T separator. Values that represent the DT_DATE and DT_FILETIME data types include seven 
digits for fractional seconds. Because the DT_FILETIME data type stores only three digits of fractional seconds, the 
grid displays zeros for the remaining four digits. Values that represent the DT_DBTIMESTAMP data type include 
three digits for fractional seconds. For values that represent the DT_DBTIME2, DT_DBTIMESTAMP2, and 
DT_DBTIMESTAMPOFFSET data types, the number of digits for fractional seconds corresponds to the scale 


specified for the column's data type. For more information about ISO 8601 formats, see Date and Time Formats. 


For more information about data types, see Integration Services Data Types. 








10. Click OK. 


Data Flow Taps 


You can add a data tap on a data flow path of a package at runtime and direct the output from the data tap to an 
external file. To use this feature, you must deploy your SSIS project using the project deployment model to an 
SSIS Server. After you deploy the package to the server, you need to execute T-SQL scripts against the SSISDB 
database to add data taps before executing the package. Here is a sample scenario: 


1. Create an execution instance of a package by using the catalog.create_execution (SSISDB Database) 
stored procedure. 


2. Add a data tap by using either catalog.add_data_tap or catalog.add_data_tap_by_guid stored procedure. 
3. Start the execution instance of the package by using the catalog.start_execution (SSISDB Database). 


Here is a sample SQL script that performs the steps described in the above scenario: 


Declare @execid bigint 

EXEC [SSISDB].[catalog].[create_execution] @folder_name=N'ETL Folder', @project_name=N'ETL Project’, 
@package_name=N'Package.dtsx', @execution_id=@execid OUTPUT 

EXEC [SSISDB].[catalog].add_data_tap @execution_id = @execid, @task_package_ path = '\Package\Data Flow 
Task', @dataflow_path_id_string = ‘Paths[Flat File Source.Flat File Source Output]', @data_filename = 
“output. txt" 

EXEC [SSISDB].[catalog].[start_execution] @execid 


The folder name, project name, and package name parameters of the create_execution stored procedure 
correspond to the folder, project, and package names in the Integration Services catalog. You can get the folder, 


project, and package names to use in the create_execution call from the SQL Server Management Studio as 
shown in the following image. If you do not see your SSIS project here, you may not have deployed the project 
to SSIS server yet. Right-click on SSIS project in Visual Studio and click Deploy to deploy the project to the 
expected SSIS server. 


Instead of typing the SQL statements, you can generate the execute package script by performing the following 
steps: 


1. Right-click Package.dtsx and click Execute. 
2. Click Script toolbar button to generate the script. 
3. Now, add the add_data_tap statement before the start_execution call. 


The task_package_path parameter of add_data_tap stored procedure corresponds to the PackagePath property 
of the data flow task in Visual Studio. In Visual Studio, right-click the Data Flow Task, and click Properties to 
launch the Properties window. Note the value of the PackagePath property to use it as a value for the 
task_package_path parameter for add_data_tap stored procedure call. 


The dataflow_path_id_string parameter of add_data_tap stored procedure corresponds to the 
IdentificationString property of the data flow path to which you want to add a data tap. To get the 
dataflow_path_id_string, click the data flow path (arrow between tasks in the data flow), and note the value of 
the IdentificationString property in the Properties window. 


When you execute the script, the output file is stored in <Program Files>\Microsoft SQL 
Server\110\DTS\DataDumps. If a file with the name already exists, a new file with a suffix (for example: 
output[1].txt) is created. 


As mentioned earlier, you can also use catalog.add_data_tap_by_guidstored procedure instead of using 
add_data_tap stored procedure. This stored procedure takes the ID of data flow task as a parameter instead of 
task_package_path. You can get the ID of data flow task from the properties window in Visual Studio. 


Removing a data tap 


You can remove a data tap before starting the execution by using the catalog.remove_data_tap stored 
procedure. This stored procedure takes the ID of data tap as a parameter, which you can get as an output of the 
add_data_tap stored procedure. 


DECLARE @tap_id bigint 

EXEC [SSISDB].[catalog].add_data_tap @execution_id = @execid, @task_package_ path = '\Package\Data Flow 
Task', @dataflow_path_id_string = ‘Paths[Flat File Source.Flat File Source Output]', @data_filename = 
‘output.txt’ @data_tap_id=@tap_id OUTPUT 

EXEC [SSISDB].[catalog].remove_data_tap @tap_id 


Listing all data taps 


You can also list all the data taps by using the catalog.execution_data_taps view. The following example extracts 
data taps for a specification execution instance (ID: 54). 


select * from [SSISDB].[catalog].execution_data_taps where execution_id=@execid 


Performance consideration 


Enabling verbose logging level and adding data taps increase the I/O operations performed by your data 
integration solution. Hence, we recommend that you add data taps only for troubleshooting purposes 


Video 


This video on TechNet demonstrates how to add/use data taps in SQL Server 2012 SSISDB catalog that help 
with debugging packages programmatically and capturing the partial results at the runtime. It also discusses 


how to list/ remove these data taps and best practices for using data taps in SSIS packages. 


See Also 
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Integration Services includes features and tools that you can use to troubleshoot connectivity between packages 
and the data sources from which packages extract and load data. 


Troubleshooting Issues with External Data Providers 


Many packages fail during interactions with external data providers. However, the messages that those providers 
return to Integration Services frequently do not provide enough information to start troubleshooting the 
interaction. To address this troubleshooting need, Integration Services includes logging messages that you can 
use to troubleshoot a package's interaction with external data sources. 


e Enable logging and select the package's Diagnostic event to see the troubleshooting 
messages. The following Integration Services components are capable of writing a message to the log 
before and after every call to an external data provider: 


o OLE DB connection manager, OLE DB source, and OLE DB destination 
o ADO.NET connection manager and ADO NET source 
o Execute SQL task 


o Lookup transformation, OLE DB Command transformation, and Slowly Changing Dimension 
transformation 


The log messages include the name of the method being called. For example, these log messages might 
include the Open method of an OLE DB Connection object or the ExecuteNonQuery method of a 
Command object. The messages have the following format, where '%1!s!' is a placeholder for the 
method information: 


ExternalRequest_pre: The object is ready to make the following external request: ‘%1!s!'. 
ExternalRequest_post: '%1!s!'. The external request has completed. 


To troubleshoot the interaction with the external data provider, review the log to see whether every 
"before" message ( ExternalRequest_pre ) has a corresponding "after" message ( ExternalRequest_post ). If 


there is no corresponding "after" message, you know that the external data provider did not respond as 
expected. 


The following example shows some sample rows from a log that contains these logging messages: 


ExternalRequest_pre: The object is ready to make the following external request: 
"ITransactionJoin: :JoinTransaction'. 

ExternalRequest_post: ‘ITransactionJoin::JoinTransaction succeeded’. The external request has 
completed. 

ExternalRequest_pre: The object is ready to make the following external request: 
"IDbConnection.Open’. 

ExternalRequest_post: ‘'IDbConnection.Open succeeded’. The external request has completed. 
ExternalRequest_pre: The object is ready to make the following external request: 
"IDbConnection.CreateCommand' . 

ExternalRequest_post: 'IDbConnection.CreateCommand finished’. The external request has completed." 
ExternalRequest_pre: The object is ready to make the following external request: 

"IDbCommand. ExecuteReader' . 

ExternalRequest_post: 'IDbCommand.ExecuteReader finished’. The external request has completed." 
ExternalRequest_pre: The object is ready to make the following external request: 
"IDataReader.GetSchemaTable’. 

ExternalRequest_post: 'IDataReader.GetSchemaTable finished’. The external request has completed." 
ExternalRequest_pre: The object is ready to make the following external request: 'IDataReader.Close'. 
ExternalRequest_post: 'IDataReader.Close finished’. The external request has completed.” 
ExternalRequest_pre: The object is ready to make the following external request: 
"IDbConnection.Close’. 

ExternalRequest_post: 'IDbConnection.Close finished’. The external request has completed.” 
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Integration Services includes features and tools that you can use to troubleshoot packages when you execute 
them after they have been completed and deployed. 


At design time, SQL Server Data Tools (SSDT) provides breakpoints to pause package execution, the Progress 
window, and data viewers to watch your data as it passes through the data flow. However, these features are not 
available when you are running packages that have been deployed. The main techniques for troubleshooting 
deployed packages are as follows: 


e Catch and handle package errors by using event handlers. 

e Capture bad data by using error outputs. 

e Track the steps of package execution by using logging. 

You can also use the following tips and techniques to avoid problems with running packages 


e Help to ensure data integrity by using transactions. For more information, see Integration Services 
Transactions. 


e Restart packages from the point of failure by using checkpoints. For more information, see 
Restart Packages by Using Checkpoints. 


Catch and Handle Package Errors by Using Event Handlers 


You can respond to the many events that are raised by the package and the objects in the package by using 
event handlers. 


e Create an event handler for the OnError event. In the event handler, you can use a Send Mail task to 
notify an administrator of the failure, use a Script task and custom logic to obtain system information for 
troubleshooting, or clean up temporary resources or incomplete output. For more information, see 
Integration Services (SSIS) Event Handlers. 


Troubleshoot Bad Data by Using Error Outputs 


You can use the error output available on many data flow components to direct rows that contain errors to a 
separate destination for later analysis. For more information, see Error Handling in Data. 


e Capture bad data by using error outputs. Send rows that contain errors to a separate destination 
such as an error table or a text file. The error output automatically adds two numeric columns that 
contain the number of the error that caused the row to be rejected, and the ID of the column in which the 
error occurred. 


e Add friendly information to the error outputs. You can make it easier to analyze the error output by 
adding the error message and the column name in addition to the two numeric identifiers that are 
supplied by the error output. For an example of how to add these two additional columns by using 
scripting, see Enhancing an Error Output with the Script Component. 


e Or, get the column names by logging the DiagnosticEx event. This event writes a data flow 
lineage map to the log. You can then look up the column name in this lineage map by using the column 


identifier captured by an error output. For more info, see Error Handling in Data. 


The value of the message column for DiagnosticEx is XML text. To view the message text for a package 
execution, query the catalog.operation_messages (SSISDB Database) view. Note that the DiagnosticEx 
event does not preserve whitespace in its XML output to reduce the size of the log. To improve readability, 
copy the log into an XML editor - in Visual Studio, for example - that supports XML formatting and syntax 
highlighting. 


Troubleshoot Package Execution by Using Operations Reports 


Standard operations reports are available in SQL Server Management Studio to help you monitor Integration 
Services packages that have been deployed to the Integration Services catalog. These package reports help you 
to view package status and history, and, if necessary, identify the cause of failures. 


For more information, see Troubleshooting Reports for Package Execution. 


Troubleshoot Package Execution by Using SSISDB Views 


A number of SSISDB database views are available that you can query to monitor package execution and other 
operations information. For more information, see Monitor Running Packages and Other Operations. 


Troubleshoot Package Execution by Using Logging 


You can track much of what occurs in your running packages by enabling logging. Log providers capture 
information about the specified events for later analysis, and save that information in a database table, a flat file, 
an XML file, or another supported output format. 


e Enable logging. You can refine the logging output by selecting only the events and only the items of 
information that you want to capture. For more information, see Integration Services (SSIS) Logging. 


e Select the package's Diagnostic event to troubleshoot provider issues. There are logging 
messages that help you troubleshoot a package's interaction with external data sources. For more 
information, see Troubleshooting Tools Package Connectivity. 


e Enhance the default logging output. Logging typically appends rows to the logging destination each 
time that a package is run. Although each row of logging output identifies the package by its name and 
unique identifier, and also identifies the execution of the package by a unique ExecutionlD, the large 
quantity of logging output in a single list can become difficult to analyze. 


The following approach is one suggestion for enhancing the default logging output and making it easier 
to generate reports: 


1. Create a parent table that logs each execution of a package. This parent table has only a 
single row for each execution of a package, and uses the ExecutionID to link to the child records in 
the Integration Services logging table. You can use an Execute SQL task at the beginning of each 
package to create this new row and to record the start time. Then you can use another Execute 
SQL task at the end of the package to update the row with the end time, duration, and status. 


2. Add auditing information to the data flow. You can use the Audit transformation to add 
information to rows in the data flow about the package execution that created or modified each 
row. The Audit transformation makes nine pieces of information available, including the 
PackageName and ExecutionInstanceGUID. For more information, see Audit Transformation. If you 
have custom information that you would also like to include in each row for auditing purposes, 
you can add this information to rows in the data flow by using a Derived Column transformation. 


For more information, see Derived Column Transformation. 


3. Consider capturing row count data. Consider creating a separate table for row count 


information, where each instance of package execution is identified by its ExecutionID. Use the Row 
Count transformation to save the row count into a series of variables at critical points in the data 
flow. After the data flow ends, use an Execute SQL task to insert the series of values into a row in 
the table for later analysis and reporting. 


For more information about this approach, see the section, "ETL Auditing and Logging," in the Microsoft 
white paper, Project REAL: Business Intelligence ETL Design Practices. 


Troubleshoot Package Execution by Using Debug Dump Files 


In Integration Services, you can create debug dump files that provide information about the execution of a 
package. For more information, see Generating Dump Files for Package Execution. 


Troubleshoot Run-time Validation Issues 


Sometimes you might not be able to connect to your data sources, or portions of your package cannot be 
validated, until prior tasks in the package have executed. Integration Services includes the following features to 
help you avoid the validation errors that would otherwise result from these conditions: 


e Configure the DelayValidation property on package elements that are not valid when the 
package is loaded. You can set DelayValidation to True on package elements whose configuration is 
not valid, to prevent validation errors when the package is loaded. For example, you may have a Data 
Flow task that uses a destination table that does not exist until an Execute SQL task creates the table at 
run time. The DelayValidation property can be enabled at the package level, or at the level of the 
individual tasks and containers that the package includes. 


The DelayValidation property can be set on a Data Flow task, but not on individual data flow 
components. You can achieve a similar effect by setting the ValidateExternalMetadata property of 
individual data flow components to false. However, when the value of this property is false, the 
component is not aware of changes to the metadata of external data sources. When set to true, the 
ValidateExternalMetadata property can help to avoid blocking issues caused by locking in the database, 
especially when the package is using transactions. 


Troubleshoot Run-time Permissions Issues 


If you encounter errors when trying to run deployed packages by using SQL Server Agent, the accounts used by 
Agent might not have the required permissions. For information on how to troubleshoot packages that are run 
from SQL Server Agent jobs, see An SSIS package does not run when you call the SSIS package from a SQL 
Server Agent job step. For more information on how to run packages from SQL Server Agent jobs, see SQL 
Server Agent Jobs for Packages. 


To connect to Excel or Access data sources, SQL Server Agent requires an account that has permission to read, 
write, create, and delete temporary files in the folder that is specified by the TEMP and TMP environment 
variables. 


Troubleshoot 64-bit Issues 


e Some data providers are not available on the 64-bit platform. In particular, the Microsoft Jet OLE DB 
Provider that is required to connect to Excel or Access data sources is not available in a 64-bit version. 


Troubleshoot Errors without a Description 


If you encounter an Integration Services error that does not have an accompanying description, you can locate 
the description in Integration Services Error and Message Reference by looking up the error by its number. The 
list does not include troubleshooting information at this time. 


Related Tasks 


Debugging Data Flow 


Troubleshooting Reports for Package Execution 
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In the current release of SQL Serverlntegration Services, standard reports are available in SQL Server 
Management Studio to help you monitor and troubleshoot Integration Services packages that have been 
deployed to the Integration Services catalog. Two of these package reports in particular help you to view 
package execution status and identify the cause of execution failures. 


e Integration Services Dashboard - This report provides an overview of all the package executions on 
the SQL Server instance in the past 24 hours. The report displays information such as Status, Operation 
Type, Package Name, etc., for each package. 


The Start Time, End Time, and Duration can be interpreted as follows: 
o If the package is still running, then Duration = current time - Start Time 
o If the package has completed, then Duration = End Time - Start Time 


For each package that has run on the server, the dashboard allows you to "zoom in" to find specific details 
on package execution errors that may have occurred. For example, click Overview to display a high-level 
overview of the status of the tasks in the execution, or All Messages to display the detailed messages 
that were captured as part of the package execution. 


You can filter the table displayed on any page by clicking Filter and then selecting criteria in the Filter 
Settings dialog. The filter criteria available depends on the data being displayed. You can change the sort 
order of the report by clicking the sort icon in the Filter Settings dialog. 


e Activity - All Executions Report - This report displays a summary of all Integration Services 
executions that have been performed on the server. The summary displays information for each 
execution such as status, start time, and end time. Each summary entry includes links to more 
information about the execution including messages generated during execution and performance data. 
As with the Integration Services Dashboard, you can apply a filter to the table to narrow down the 
information displayed. 


Related Content 


Reports for the Integration Services Server 


Troubleshooting Tools for Package Execution 


Generating Dump Files for Package Execution 
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In Integration Services, you can create debug dump files that provide information about the execution of a 
package. The information in these files can help you with troubleshooting package execution issues. 





NOTE 

Debug dump files might contain sensitive information. To help protect sensitive information, you can use an access control 
list (ACL) to restrict access to the files, or copy the files to a folder that has restricted access. For example, before you send 
your debug files to Microsoft support services, we recommend that you remove any sensitive or confidential information. 











When you deploy a project to the Integration Services server, you can create dump files that provide 
information about the execution of the packages contained in the project. When the ISServerExec.exe process 
ends, the dump files are created. You can specify that a dump file is created when errors occur during the 
package execution, by selecting the Dump on errors option in the Execute Package Dialog box. You can also 
use the following stored procedures: 


® catalog.set_execution_parameter_value (SSISDB Database) 


Call this stored procedure to configure a dump file to be created when any error or event occurs, and 
when specific events occur, during a package execution. 


e catalog.create_execution_dump 
Call this stored procedure to cause a running package to pause and create a dump file. 


If you are using the package deployment model, you create the debug dump files by using either the dtexec 
utility or the dtutil utility to specify a debug dump option in the command line. For more information, see 
dtexec Utility and dtutil Utility. For more information about the package deployment model, see Deploy 
Integration Services (SSIS) Projects and Packages and Legacy Package Deployment (SSIS). 


Debug dump file format 

When you specify a debug dump option, Integration Services creates the following debug dump files: 
e A.mdmp debug dump file. This is a binary file. 

e The tmp debug dump file. This is a text formatted file. 


By default, Integration Services stores these files in the folder, <drive>\Program Files\Microsoft SQL 
Server\110\Shared\ErrorDumps. 


The following table describes only certain sections in the tmp file. The .tmp file includes additional data that is 
not listed in the table. 


TYPE OF INFORMATION DESCRIPTION EXAMPLE 


TYPE OF INFORMATION 


Environment 


Dynamic-link library (DLL) path and 


version 


Recent messages 


DESCRIPTION 


Operating system version, memory 
usage data, process ID, and process 
image name. The environment 
information is at the beginning of the 
.tmp file. 


Path and version number of each DLL 
that the system loads during the 
processing of a package. 


Recent messages issued by the system. 
Includes the time, type, description, 
and thread ID of each message. 


EXAMPLE 


# SSIS Textual Dump taken at 
9/13/2007 1:50:34 PM 


#PID 4120 


#lmage Name [C:\Program 
Files\Microsoft SQL 
Server\1 10\DTS\Binn\DTExec.exe] 


# OS major=6 minor=0 build=6000 


# Running on 2 amd64 processors 
under WOW64 


# Memory: 58% in use. Physical: 
845M/2044M Paging: 2404M/4095M 
(avail/total) 


# Loaded Module: 
c:\bb\Sql\DTS\src\bin\debug\i386\DTEx 
ec.exe (10.0.1069.5) 


# Loaded Module: 
C:\Windows\SysWOW64\ntdll.dll 
(6.0.6000.16386) 


# Loaded Module: 
C:\Windows\syswow64\kernel32.dll 
(6.0.6000.16386) 


[M:1] Ring buffer entry: (*pRecord) 


[D:2] 
<< <CRingBufferLogging::RingBufferLo 
ggingRecord> >> ( @ 0282F1A8 ) 


[E:3] Time Stamp: 2007-09-13 
13:50:32.786 (szTimeStamp) 


[E:3] Thread ID: 2368 (ThreadID) 


[E:3] Event Name: OnError 
(EventName) 


[E:3] Source Name: (SourceName) 
[E:3] Source ID: (SourcelD) 
[E:3] Execution ID: (ExecutionGUID) 


[E:3] Data Code: -1073446879 
(DataCode) 


[E:3] Description: The component is 
missing, not registered, not 
upgradeable, or missing required 
interfaces. The contact information for 


this component is "". 


Related information 


Execute Package Dialog Box 


Views (Integration Services Catalog) 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


This section describes the Transact-SQL views that are available for administering Integration Services projects 
that have been deployed to an instance of SQL Server. 


Query the Integration Services views to inspect objects, settings, and operational data that are stored in the 
SSISDB catalog. 


The default name of the catalog is SSISDB. The objects that are stored in the catalog include projects, packages, 
parameters, environments, and operational history. 


You can use the database views and stored procedures directly, or write custom code that calls the managed API. 
Management Studio and the managed API query the views and call the stored procedures that are described in 
this section to perform many of their tasks. 


In This Section 


catalog.catalog_properties (SSISDB Database) 
Displays the properties of the Integration Services catalog. 


catalog.effective_object_permissions (SSISDB Database) 
Displays the effective permissions for the current principal for all objects in the Integration Services catalog. 


catalog.environment_variables (SSISDB Database) 
Displays the environment variable details for all environments in the Integration Services catalog. 


catalog.environments (SSISDB Database) 
Displays the environment details for all environments in the Integration Services catalog. Environments contain 
variables that can be referenced by Integration Services projects. 


catalog.execution_parameter_values (SSISDB Database) 
Displays the actual parameter values that are used by Integration Services packages during an instance of 
execution. 


catalog.executions (SSISDB Database) 
Displays the instances of package execution in the Integration Services catalog. Packages that are executed with 
the Execute Package task run in the same instance of execution as the parent package. 


catalog.explicit_object_permissions (SSISDB Database) 
Displays only the permissions that have been explicitly assigned to the user. 


catalog.extended_operation_info (SSISDB Database) 
Displays extended information for all operations in the Integration Services catalog. 


catalog.folders (SSISDB Database) 
Displays the folders in the Integration Services catalog. 


catalog.object_parameters (SSISDB Database) 
Displays the parameters for all packages and projects in the Integration Services catalog. 


catalog.object_versions (SSISDB Database) 
Displays the versions of objects in the Integration Services catalog. In this release, only versions of projects are 


supported in this view. 


catalog.operation_messages (SSISDB Database) 
Displays messages that are logged during operations in the Integration Services catalog. 


catalog.operations (SSISDB Database) 
Displays the details of all operations in the Integration Services catalog. 


catalog.packages (SSISDB Database) 
Displays the details for all packages that appear in the Integration Services catalog. 


catalog.environment_references (SSISDB Database) 
Displays the environment references for all projects in the Integration Services catalog. 


catalog.projects (SSISDB Database) 
Displays the details for all projects that appear in the Integration Services catalog. 


catalog.validations (SSISDB Database) 
Displays the details of all project and package validations in the Integration Services catalog. 


catalog.master_properties (SSISDB Database) 
Displays the properties of the Integration Services Scale Out Master. 


catalog.worker_agents (SSISDB Database) 
Displays the information of Integration Services Scale Out Worker. 


catalog.catalog_properties (SSISDB Database) 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Displays the properties of the Integration Services catalog. 


COLUMN NAME DATA TYPE 
property_name nvarchar(256) 
property_value nvarchar(256) 

Remarks 


This view displays a row for each catalog property. 
PROPERTY NAME 


DEFAULT_EXECUTION_MODE 


ENCRYPTION_ALGORITHM 


IS_SCALEOUT_ENABLED 


MAX_PROJECT_VERSIONS 


OPERATION_CLEANUP_ENABLED 


RETENTION_WINDOW 


SCHEMA_BUILD 


DESCRIPTION 


The name of the catalog property. 


The value of the catalog property. 


DESCRIPTION 


The server-wide default execution mode for packages - 
Server (0) or Scale Out (1). 


The type of encryption algorithm that is used to encrypt 
sensitive data. The supported values include: DES , 
TRIPLE_DES , TRIPLE_DES_3KEY , DESX , AES_128 , 
AES_192 , and AES_256 . Note: The catalog database must 
be in single-user mode in order to change this property. 


When the value is True , the SSIS Scale Out feature is 
enabled. If you have not enabled Scale Out, this property 
may not appear in the view. 


The number of new project versions that are retained for a 
single project. When version cleanup is enabled, older 
versions beyond this count are deleted. 


When the value is TRUE , operation details and operation 
messages older than RETENTION_WINDOW (days) are 
deleted from the catalog. When the value is FALSE , all 
operation details and operation messages are stored in the 
catalog. Note: a SQL Server job performs the operation 
cleanup. 


The number of days that operation details and operation 
messages are stored in the catalog. When the value is -1 , 
the retention window is infinite. Note: If no cleanup is 
desired, set OPERATION_CLEANUP_ENABLED to FALSE. 


The build number of the SSISDB catalog database schema. 
This number changes whenever the SSISDB catalog is 
created or upgraded. 


PROPERTY NAME 


SCHEMA_VERSION 


VALIDATION_TIMEOUT 


SERVER_CUSTOMIZED_LOGGING_LEVEL 


SERVER_LOGGING_LEVEL 


SERVER_OPERATION_ENCRYPTION_LEVEL 


VERSION_CLEANUP_ENABLED 


Permissions 
This view requires one of the following permissions: 
e Membership to the ssis_admin database role 


e Membership to the sysadmin server role 


DESCRIPTION 


The major version number of the SSISDB catalog database 
schema. This number changes whenever the SSISDB catalog 
is created or the major version is upgraded. 


Validations are stopped if they do not complete in the 
number of seconds specified by this property. 


The default customized logging level for the Integration 
Services server. If you have not created any customized 
logging levels, this property may not appear in the view. 


The default logging level for the Integration Services server. 


When the value is 1 ( PER_EXECUTION ), the certificate and 
symmetric key used for protecting sensitive execution 
parameters and execution logs are created for each 
execution. When the value is 2 ( PER_PROJECT ), the 
certificate and symmetric key are created one time for each 
project. For more info about this property, see the Remarks 
for the SSIS stored procedure catalog.cleanup_server_log. 


When the value is TRUE , only the 
MAX_PROJECT_VERSIONS number of project versions are 
stored in the catalog and all other project versions are 
deleted. When the value is FALSE, all project versions are 
stored in the catalog. Note: a SQL Server job performs the 
operation cleanup. 


catalog.effective_object_permissions (SSISDB 


Database) 
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Applies to: Q sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Displays the effective permissions for the current principal for all objects in the Integration Services catalog. 
COLUMN NAME DATA TYPE DESCRIPTION 


object_type smallint The type of securable object. Securable 
objects types include folder (1 ), 
project ( 2 ), environment ( 3 ), and 
operation ( 4 ). 


object_id bigint The unique identifier (ID) or primary 
key of the object. 
permission_type smallint The type of permission. 
Remarks 


This view displays the permission types listed in the following table: 


PERMISSION_TYPE VALUE PERMISSION NAME PERMISSION DESCRIPTION APPLICABLE OBJECT TYPES 
al READ Allows the principal to read Folder, Project, 
information that is Environment, Operation 


considered part of the 
object, such as properties. It 
does not allow the principal 
to enumerate or read the 
contents of other objects 
contained within the object. 


2) MODIFY Allows the principal to Folder, Project, 
modify information that is Environment, Operation 
considered part of the 
object, such as properties. It 
does not allow the principal 
to modify other objects 
contained within the object. 


3 EXECUTE Allows the principal to Project 
execute all packages in the 
project. 
4 MANAGE_PERMISSIONS Allows the principal to Folder, Project, 
assign permissions to the Environment, Operation 


objects. 


PERMISSION_TYPE VALUE 


100 


101 


102 


103 


104 


PERMISSION NAME 


CREATE_OBJECTS 


READ_OBJECTS 


MODIFY_OBJECTS 


EXECUTE_OBJECTS 


MANAGE_OBJECT_PERMISS 
IONS 


PERMISSION DESCRIPTION 


Allows the principal to 
create objects in the folder. 


Allows the principal to read 
all objects in the folder. 


Allows the principal to 
modify all objects in the 
folder. 


Allows the principal to 
execute all packages from 
all projects in the folder. 


Allows the principal to 
manage permissions on all 
objects in the folder. 


APPLICABLE OBJECT TYPES 


Folder 


Folder 


Folder 


Folder 


Folder 


Only objects on which the caller has permissions are evaluated. The permissions are computed based on the 


following: 
e Explicit permissions 


e Inherited permissions 


e Membership of the principal in roles 


e Membership of the principal in groups 


Permissions 


Users can see effective permissions only for themselves and for roles of which they are members. 


catalog.environment_variables (SSISDB Database) 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Displays the environment variable details for all environments in the Integration Services catalog. 
COLUMN NAME DATA TYPE DESCRIPTION 


variable_id bigint The unique identifier (ID) of the 
environment variable. 


environment_id bigint The unique ID of the environment that 
the variable is associated with. 


name sysname The name of the environment variable. 

description nvarchar(1024) The description of the environment 
variable. 

type nvarchar(128) The data type of the environment 
variable. 

sensitive bit When the value is 1 , the variable is 


sensitive and is encrypted when it is 
stored. When the value is @ , the 
variable is not sensitive and the value 
is stored in plaintext. 


value sql_variant The value of the environment variable. 
When sensitive is @ , the plaintext 
value is shown. When sensitive is 1 , 
the NULL value is displayed. 


Remarks 


This view displays a row for each environment variable in the catalog. 


Permissions 


This view requires one of the following permissions: 
e READ permission on the corresponding environment 
e Membership to the ssis_admin database role 


e Membership to the sysadmin server role 


NOTE 


When you have permission to perform an operation on the server, you also have permission to view information about 


the operation. Row-level security is enforced; only rows that you have permission to view are displayed. 





catalog.environment_references (SSISDB Database) 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Displays the environment references for all projects in the SSISDB catalog. 


COLUMN NAME DATA TYPE DESCRIPTION 

reference_id bigint The unique identifier (ID) of the 
reference. 

project_id bigint The unique ID of the project. 

reference_type char(1) Indicates whether the environment can 


be located in the same folder as the 
project (relative reference) or in a 
different folder (absolute reference). 
When the value is R , the 
environment is located by using a 
relative reference. When the value is 
A , the environment is located by 
using an absolute reference. 


environment_folder_name sysname The name of the folder if the 
environment is located by using an 
absolute reference. 


environment_name sysname The name of the environment that is 
referenced by the project. 


validation_status char(1) The status of the validation. 
last_validation_time datatimeoffset(7) The time of the last validation. 
Remarks 


e This view displays a row for each environment reference in the catalog. 


e A project can have relative or absolute environment references. Relative references refer to the 
environment by name and require that it resides in the same folder as the project. Absolute references 
refer to the environment by name and folder, and may refer to environments that reside in a different 
folder than the project. A project can reference multiple environments. 


Permissions 

This view requires one of the following permissions: 
e READ permission on the corresponding project 
e Membership to the ssis_admin database role 


e Membership to the sysadmin server role. 








NOTE 


If you have READ permission on a project, you also have READ permission on all of the packages and environment 


references associated with that project. Row-level security is enforced; only rows that you have permission to view are 
displayed. 





catalog.environments (SSISDB Database) 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Displays the environment details for all environments in the Integration Services catalog. Environments contain 


variables that can be referenced by Integration Services projects. 


COLUMN NAME 


environment_id 


name 


folder_id 


description 


created_by_sid 


created_by_name 


created_time 


Remarks 


DATA TYPE 


bigint 


sysname 


bigint 


nvarchar(1024) 


varbinary(85) 


nvarchar(128) 


datetimeoffset 


DESCRIPTION 


The unique identifier (ID) of the 
environment. 


The name of the environment. 


The unique ID of the folder in which 
the environment resides. 


The description of the environment. 
This value is optional. 


The security identifier (SID) of the user 
who created the environment. 


The name of the user who created the 
environment. 


The date and time at which the 
environment was created. 


This view displays a row for each environment in the catalog. Environment names are only unique with respect 
to the folder in which they are located. For example, an environment named £1 can exist in more than one 


folder in the catalog, but each folder can have only one environment named £1. 


Permissions 

This view requires one of the following permissions: 
e READ permission on the environment 

e Membership to the ssis_admin database role 


e Membership to the sysadmin server role 





NOTE 


Row-level security is enforced; only rows that you have permission to view are displayed. 





catalog.event_message_context 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Displays information about the conditions that are associated with execution event messages, for executions on 
the Integration Services server. 


COLUMN NAME DATA TYPE DESCRIPTION 
Context_id bigint Unique ID for the error context. 
Event_message_id bigint Unique ID for the message that the 


context relates to. 


Context_depth int As the depth increases, the context is 
further from the error When an error 
occurs, the context depth starts at 1. 
The value of 0 indicates the state of 
the package before execution starts. 


Package_path Nvarchar(max) The package path for the context 
source. 
Context_type smallint The type of object that is the source 


for the context. See the Remarks 
section for a list of context types. 


Context_source_name Nvarchar(4000) The name of the object that is the 
source for the context. 


Context_source_id Nvarchar(38) The unique ID of the object that is the 
source for the context. 


Property_name Nvarchar(4000) The name of the property associated 
with the source of the context. 


Property_value Sql_variant The property value associated with the 
source of the context. 


Remarks 


The following table lists the context types. 


CONTEXT TYPE VALUE TYPE NAME DESCRIPTION 
10 Task State of a task when an error occurred. 
20 Pipeline Error from a pipeline component: 


source, destination, or transformation 
component. 


CONTEXT TYPE VALUE TYPE NAME DESCRIPTION 


30 Sequence State of a sequence. 

40 For Loop State of a For Loop. 

50 Foreach Loop State of a Foreach Loop 

60 Package State of the package when an error 

occurred. 

70 Variable Variable value 

80 Connection manager Properties of a connection manager. 
Permissions 


This view requires one of the following permissions: 
e READ permission on the operation 
e Membership to the ssis_admin database role. 


e Membership to the sysadmin server role. 


catalog.event_messages 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Displays information about messages that were logged during operations. 


COLUMN NAME 


Event_message_ID 


Operation_id 


Message_time 


Message_type 


Message_source_type 


message 


Extended_info_id 


Package_name 


Event_name 


M essage_source_name 


Message_source_id 


Subcomponent_name 


Package_path 


DATA TYPE 


bigint 


bigint 


datetimeoffset(7) 


smallint 


smallint 


nvarchar(max) 


bigint 


nvarchar(260) 


nvarchar(1024) 


nvarchar(4000) 


nvarchar(38) 


nvarchar(4000) 


nvarchar(max) 


DESCRIPTION 


The unique ID of the event message. 


The type of operation. 


For a list of operation types, see 
catalog.operations (SSISDB Database). 


The time the message was created. 


The type of message displayed. For 
more information about message 
types, see catalog.operation_messages 
(SSISDB Database). 


The source of the message. 


The text of the message. 


The ID of additional information that 
relates to the operation message, 
found in the 
catalog.extended_operation_info 
(SSISDB Database) view. 


The name of the package file. 


The run-time event associated with the 
message. 


The package component that is the 
source of the message. 


The unique ID of the source of the 
message. 


The data flow component that is the 
source of the message. 


When messages are returned by the 
Integration Services engine, 
SSIS.Pipeline appears in this column. 


The unique path of the component 
within the package. 


COLUMN NAME DATA TYPE 
Execution_path nvarchar(max) 
threadID int 
Message_code int 


Remarks 


This view displays the following message source types. 


MESSAGE_SOURCE_TYPE 
10 
20 
30 
40 
50 


60 


Permissions 


This view requires one of the following permissions: 
e READ permission on the operation 
e Membership to the ssis_admin database role. 


e Membership to the sysadmin server role. 


See Also 


catalog.event_message_context 


DESCRIPTION 


The full path from the parent package 
to the point in which the component is 
executed. 


This path also captures iterations of a 
component. 


ID for the thread that is executing 
when the message is logged. 


The code associated with the message. 


DESCRIPTION 


Entry APIs, such as T-SQL and CLR Stored procedures 


External process used to run package (ISServerExec.exe) 


Package-level objects 


Control Flow tasks 


Control Flow containers 


Data Flow task 


catalog.executable_statistics 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 
Displays a row for each executable that is run, including each iteration of an executable. 


An executable is a task or container that you add to the control flow of a package. 


COLUMN NAME DATA TYPE DESCRIPTION 

Statistics_id bigint Unique ID of the data. 

Execution_id bigint Unique ID for the instance of the 
execution. 


The catalog.executions view provides 
additional information about 

executions. For more information, see 
catalog.executions (SSISDB Database). 


Executable_id bigint Unique ID for the package component. 


The catalog.executables view provides 
additional information about 
executables. For more information, see 
catalog.executables. 


Execution_path nvarchar(max) The full execution path of the package 
component, including each iteration of 
the component. 


Start_time datetimeoffset(7) The time when the executable enters 
the pre-execute phase. 


End_time datetimeoffset(7) The time when the executable enters 
the post-execute phase. 


Execution_duration int The length of time the executable 
spent in execution. The value is in 
milliseconds. 

Execution_result smallint The following are the possible values: 


0 (Success) 
1 (Failure) 
2 (Completion) 


3 (Cancelled) 


Execution_value sql_variant The value that is returned by the 
execution. This is a user-defined value. 


Permissions 

The view requires one of the following permissions: 
e READ permission on the instance of the execution. 
e Membership to the ssis_admin database role. 


e Membership to the sysadmin server role. 


catalog.executables 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 
This view displays a row for each executable in the specified execution. 


An executable is a task or container that you add to the control flow of a package. 


COLUMN NAME DATA TYPE DESCRIPTION 

executable_id bigint The unique identifier for the 
executable. 

execution_id bigint The unique identifier for the instance 


of execution. 


executable_name nvarchar(4000) The name of the executable. 

executable_guid nvarchar(38) The GUID of the executable. 

package_name nvarchar(260) The name of the package. 

package_path nvarchar(max) The path of the package. 
Permissions 


This view requires one of the following permissions: 
e READ permission on the instance of execution 
e Membership to the ssis_admin database role 


e Membership to the sysadmin server role 


NOTE 


When you have permission to perform an operation on the server, you also have permission to view information about 


the operation. Row-level security is enforced; only rows that you have permission to view are displayed. 





Remarks 


catalog.execution_component_phases 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Displays the time spent by a data flow component in each execution phase. 


COLUMN NAME 
phase_stats_id 


execution_id 


package_name 


task_name 
subcomponent_name 
phase 

start_time 

end_time 


execution_path 


Remarks 


DATA TYPE 


bigint 


bigint 


nvarchar(260) 


nvarchar(4000) 


nvarchar(4000) 


nvarchar(128) 


datetimeoffset(7) 


datetimeoffset(7) 


nvarchar(max) 


DESCRIPTION 


Unique identifier (ID) of the phase. 


Unique ID for the instance of 
execution. 


The name of the first package that was 
started during execution. 


The name of the data flow task. 


The name of the data flow component. 


The name of the execution phase. 


The time when the phase started. 


The time when the phase ended. 


The execution path of the data flow 
task. 


This view displays a row for each execution phase of a data flow component, such as Validate, Pre-Execute, Post- 
Execute, PrimeOutput, and ProcessInput. Each row displays the start and end time for a specific execution phase. 


Example 


The following example uses the catalog.execution_component_phases view to find the total amount of time that 
a specific package has spent executing in all phases (active_time), and the total elapsed time for the package 
(total_time). 





WARNING 


The catalog.execution_component_phases view provides this information when the logging level of the package execution 
is set to Performance or Verbose. For more information, see Enable Logging for Package Execution on the SSIS Server. 








use SSISDB 

select package_name, task_name, subcomponent_name, execution_path, 
SUM(DATEDIFF(ms,start_time,end_time)) as active_time, 
DATEDIFF(ms,min(start_time), max(end_time)) as total_time 

from catalog.execution_component_phases 

where execution_id = 1841 

group by package_name, task_name, subcomponent_name, execution_path 

order by package_name, task_name, subcomponent_name, execution_path 


Permissions 

This view requires one of the following permissions: 
e READ permission on the instance of execution 

e Membership to the ssis_admin database role 


e Membership to the sysadmin server role 


NOTE 


When you have permission to perform an operation on the server, you also have permission to view information about 


the operation. Row-level security is enforced; only rows that you have permission to view are displayed. 





catalog.execution_data_statistics 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


This view displays a row each time a data flow component sends data to a downstream component, for a given 
package execution. The information in this view can be used to compute the data throughput for a component. 


COLUMN NAME 
data_stats_id 


execution_id 


package_name 


task_name 


dataflow_path_id_string 


dataflow_path_name 


source_component_name 


destination_component_name 


rows_sent 


created_time 


execution_path 


Remarks 


DATA TYPE 


bigint 


bigint 


nvarchar(260) 


nvarchar(4000) 


nvarchar(4000) 


nvarchar(4000) 


nvarchar(4000) 


nvarchar(4000) 


bigint 


datatimeoffset(7) 


nvarchar(max) 


DESCRIPTION 


Unique identifier (ID) of the data. 


Unique ID for the instance of 
execution. 


The name of the first package that was 
started during execution. 


The name of the data flow task. 


The identification string of the data 
flow path. 


The name of the data flow path. 


The name of the data flow component 
that sent the data. 


The name of the data flow component 
that received the data. 


The number of rows sent from the 
source component. 


The time when the values were 
obtained. 


The execution path of the component. 


e@ When there are multiple outputs from the component, a row is added for each of the outputs. 


e By default, when an execution is started, the information about the number of rows that are sent is not 


logged. 


@ To view this data for a given package execution, set the logging level to Verbose. For more information, 


see Enable Logging for Package Execution on the SSIS Server. 


Permissions 


This view requires one of the following permissions: 


e READ permission on the instance of execution 
e Membership to the ssis_admin database role 


e Membership to the sysadmin server role 


NOTE 


When you have permission to perform an operation on the server, you also have permission to view information about 


the operation. Row-level security is enforced; only rows that you have permission to view are displayed. 





catalog.execution_data_taps 


11/23/2021 * 2 minutes to read « Edit Online 





Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Displays information for each data tap defined in an execution. 


COLUMN NAME DATA TYPE DESCRIPTION 
data_tap_id bigint Unique identifier (ID) of the data tap. 
execution_id bigint Unique identifier (ID) for the instance 


of execution. 


package_path nvarchar(max) The package path for the data flow 
task where the data is tapped. 


dataflow_path_id_string nvarchar(4000) The identification string of the data 
flow path. 

dataflow_task_guid uniqueidentifier Unique ID of the data flow task. 

max_rows int The number of rows to be captured. If 


this value is not specified then all rows 
will be captured. 


filename nvarchar(4000) The name of the data dump file. For 
more information, see Generating 
Dump Files for Package Execution. 


Permissions 

This view requires one of the following permissions: 
e READ permission on the instance of execution 

e Membership to the ssis_admin database role 


e Membership to the sysadmin server role 


NOTE 


When you have permission to perform an operation on the server, you also have permission to view information about 
the operation. Row-level security is enforced; only rows that you have permission to view are displayed. 











See Also 


Generating Dump Files for Package Execution 


catalog.execution_parameter_values (SSISDB 


Database) 


11/23/2021 + 2 minutes to read * Edit Online 





Applies to: Q sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Displays the actual parameter values that are used by Integration Services packages during an instance of 


execution. 

COLUMN NAME DATA TYPE DESCRIPTION 

execution_parameter_id bigint Unique identifier (ID) of the execution 
parameter. 

execution_id bigint Unique ID for the instance of 
execution. 

object_type smallint When the value is 2 , the parameter 
is a project parameter. When the value 
is 30, the parameter is a package 
parameter. When the value is 5@ , the 
parameter is one of the following: 
LOGGING_LEVEL 
DUMP_ON_ERROR 
DUMP_ON_EVENT 
DUMP_EVENT_CODE 
CALLER_INFO 
SYNCHRONIZED 

parameter_data_type nvarchar(128) The data type of the parameter. 

parameter_name sysname The name of the parameter. 

parameter_value sql_variant The value of the parameter. When 
sensitive is @ , the plaintext value is 
shown. When sensitive is 1 , the 
NULL value is displayed. 

sensitive bit When the value is 1 , the parameter 


value is sensitive. When the value is 
@ , the parameter value is not 
sensitive. 


COLUMN NAME 


required 


value_set 


runtime_override 


Remarks 


DATA TYPE 


bit 


bit 


bit 


DESCRIPTION 


When the value is 1 , the parameter 
value is required in order to start the 
execution. When the value is @ , the 


parameter value is not required to 
start the execution. 


When the value is 1 , the parameter 
value has been assigned. When the 
value is @ , the parameter value has 
not been assigned. 


When the value is 1 , the parameter 
value was changed from the original 
value before the execution was started. 
When the value is @ , the parameter 
value is the original value that was set. 


This view displays a row for each execution parameter in the catalog. An execution parameter value is the value 


that is assigned to a project parameter or package parameter during a single instance of execution. 


Permissions 


This view requires one of the following permissions: 


e READ permission on the instance of execution 


e Membership to the ssis_admin database role 


e Membership to the sysadmin server role 





NOTE 


When you have permission to perform an operation on the server, you also have permission to view information about 


the operation. Row-level security is enforced; only rows that you have permission to view are displayed. 











catalog.execution_property_override_values 


11/23/2021 * 2 minutes to read « Edit Online 





Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Displays the property override values that were set during execution of the package. 


COLUMN NAME DATA TYPE DESCRIPTION 

property_id bigint Unique ID for the property override 
value. 

execution_id bigint Unique ID for the instance of 
execution. 

property_path nvarchar(4000) The path to the property in the 
package. 

property_value nvarchar(max) The override value of the property. 

sensitive bit When the value is 1, the property is 


sensitive and is encrypted when it is 
stored. When the value is 0, the 
property is not sensitive and the value 
is stored in plaintext. 


Remarks 


This view displays a row for each execution in which property values were overridden using the Property 
overrides section in the Advanced tab of the Execute Package dialog. The path to the property is derived 
from the Package Path property of the package task. 


Permissions 

This view requires one of the following permissions: 
e READ permission on the instance of execution 

e Membership to the ssis_admin database role 


e Membership to the sysadmin server role 





NOTE 


When you have permission to perform an operation on the server, you also have permission to view information about 
the operation. Row-level security is enforced; only rows that you have permission to view are displayed. 








catalog.executions (SSISDB Database) 


11/23/2021 * 2 minutes to read « Edit Online 





Applies to: Q@ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Displays the instances of package execution in the Integration Services catalog. Packages that are executed with 
the Execute Package task run in the same instance of execution as the parent package. 


COLUMN NAME DATA TYPE DESCRIPTION 


execution_id bigint The unique identifier (ID) for the 
instance of execution. 


folder_name sysname(nvarchar(128)) The name of the folder that contains 
the project. 

project_name sysname(nvarchar(128)) The name of the project. 

package_name nvarchar(260) The name of the first package that was 


started during execution. 


reference_id bigint The environment that is referenced by 
the instance of execution. 


reference_type char(1) Indicates whether the environment can 

be located in the same folder as the 
project (relative reference) or in a 
different folder (absolute reference). 
When the value is R , the 
environment is located by using a 
relative reference. When the value is 

A , the environment is located by 
using an absolute reference. 


environment_folder_name nvarchar(128) The name of the folder that contains 
the environment. 


environment_name nvarchar(128) The name of the environment that was 
referenced during execution. 


project_Isn bigint The version of the project that 
corresponds with the instance of 
execution. This number is not 
guaranteed to be sequential. 


executed_as_sid varbinary(85) The SID of the user who started the 
instance of execution. 


executed_as_name nvarchar(128) The name of the database principal 
that was used to start the instance of 
execution. 


COLUMN NAME 


use32bitruntime 


object_type 


object_id 


status 


start_time 


end_time 


caller_sid 


caller_name 


process_id 


stopped_by_sid 


stopped_by_name 


total_physical_ memory_kb 


available_physical_memory_kb 


total_page_file_kb 


DATA TYPE 


bit 


smallint 


bigint 


int 


datetimeoffset 


datetimeoffsset 


varbinary(85) 


nvarchar(128) 


int 


varbinary(85) 


nvarchar(128) 


bigint 


bigint 


bigint 


DESCRIPTION 


Indicates if the 32-bit runtime is used 
to run the package on a 64-bit 
operating system. When the value is 
1 , the execution is performed with 
the 32-bit runtime. When the value is 
@ , the execution is performed with 
the 64-bit runtime. 


The type of object. The object may be 
a project ( 2@ ) or a package ( 38 ). 


The ID of the object affected by the 
operation. 


The status of the operation. The 
possible values are created (1 ), 
running ( 2 ), canceled ( 3 ), failed ( 4 
), pending (5 ), ended unexpectedly ( 
6 ), succeeded ( 7 ), stopping ( 8 ), 
and completed ( 9 ). 


The time when the instance of 
execution was started. 


The time when the instance of 
execution ended. 


The security ID (SID) of the user if 
Windows Authentication was used to 
log on. 


The name of the account that 
performed the operation. 


The process ID of the external process, 
if applicable. 


The security ID (SID) of the user who 
stopped the instance of execution. 


The name of the user who stopped the 
instance of execution. 


The total physical memory (in 
megabytes) on the server when the 
execution is started. 


The available physical memory (in 
megabytes) on the server when the 
execution is started. 


The total page memory (in megabytes) 
on the server when the execution is 
started. 


COLUMN NAME DATA TYPE DESCRIPTION 


available_page_file_kb bigint The available page memory (in 
megabytes) on the server when the 
execution is started. 


cpu_count int The number of logical CPUs on the 
server when the execution is started. 


server_name nvarchar(128) The Windows server and instance 
information for a specified instance of 
SQL Server. 

machine_name nvarchar(128) The computer name on which the 


server instance is running. 


dump_id uniqueidentifier The ID of an execution dump. 


Remarks 


This view displays a row for each instance of execution in the catalog. 


Permissions 
This view requires one of the following permissions: 
e READ permission on the instance of execution 


e Membership to the ssis_admin database role 


e Membership to the sysadmin server role 





NOTE 


Row-level security is enforced; only rows that you have permission to view are displayed. 





catalog.explicit_object_permissions (SSISDB 


Dyeir-leye\-) 


11/23/2021 * 2 minutes to read « Edit Online 





Applies to: Q sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Displays only the permissions that have been explicitly assigned to the user. 


COLUMN NAME DATA TYPE DESCRIPTION 


object_type smallint The type of securable object. Securable 
objects types include folder (1 ), 
project ( 2 ), environment ( 3 ), and 
operation ( 4 ). 


object_id bigint The unique identifier (ID) or primary 
key of the secured object. 


principal_id int The ID of the database principal. 
permission_type smallint The type of permission. 
is_deny bit Indicates whether the permission has 


been denied or granted. When the 
value is 1 , the permission has been 
denied. When the value is @ , the 
permission has not been denied. 


grantor_id int The ID of the principal who granted 
the permission. 


Remarks 


This view displays the permission types listed in the following table: 


PERMISSION_TYPE VALUE PERMISSION NAME PERMISSION DESCRIPTION APPLICABLE OBJECT TYPES 
1 READ Allows the principal to read Folder, Project, 
information that is Environment, Operation 


considered part of the 
object, such as properties. It 
does not allow the principal 
to enumerate or read the 
contents of other objects 
contained within the object. 


PERMISSION_TYPE VALUE 


100 


101 


102 


103 


104 


Permissions 


PERMISSION NAME 


MODIFY 


EXECUTE 


MANAGE_PERMISSIONS 


CREATE_OBJECTS 


READ_OBJECTS 


MODIFY_OBJECTS 


EXECUTE_OBJECTS 


MANAGE_OBJECT_PERMISS 
IONS 


PERMISSION DESCRIPTION 


Allows the principal to 
modify information that is 
considered part of the 
object, such as properties. It 
does not allow the principal 
to modify other objects 
contained within the object. 


Allows the principal to 
execute all packages in the 
project. 


Allows the principal to 
assign permissions to the 
objects. 


Allows the principal to 
create objects in the folder. 


Allows the principal to read 
all objects in the folder. 


Allows the principal to 
modify all objects in the 
folder. 


Allows the principal to 
execute all packages from 
all projects in the folder. 


Allows the principal to 
manage permissions on all 
objects in the folder. 


APPLICABLE OBJECT TYPES 


Folder, Project, 
Environment, Operation 


Project 


Folder, Project, 
Environment, Operation 


Folder 


Folder 


Folder 


Folder 


Folder 


This view does not give a complete view of permissions for the current principal. The user must also check 


whether the principal is a member of roles and groups that have permissions assigned. 


=} f=] (010 R=) 4-010 (210 MO) @\=18-10(0)0 AKO Ss) S)B) 5m DY-lt~]0)-15-) 
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Applies to: Q@ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Displays extended information for all operations in the Integration Services catalog. 
COLUMN NAME DATA TYPE DESCRIPTION 


info_id bigint The unique identifier (ID) of the 
extended information. 


operation_id bigint The unique ID of the operation that 
corresponds to the extended 
information. 

object_name nvarchar(260) The name of the object. 

object_type smallint The type of object affected by the 


operation. The object may be a folder ( 

1@ ), project ( 2@ ), package ( 3@ ), 
environment ( 4@ ), or instance of 
execution ( 52 ). 


reference_id bigint The unique ID of the reference that is 
used in the operation. 


status int The status of the operation. The 
possible values are created (1 ), 
running ( 2 ), canceled ( 3 ), failed ( 4 
), pending (5 ), ended unexpectedly ( 
6 ), succeeded ( 7 ), stopping ( 8 ), 
and completed ( 9 ). 


start_time datetimeoffset(7) The date and time at which the 
operation started. 


end_time datetimeoffset(7) The date and time at which the 
operation ended. 


Remarks 


A single operation can have multiple extended information rows. 


Permissions 

This view requires one of the following permissions: 
e@ READ permission on the operation 

e@ Membership to the ssis_admin database role 


e Membership to the sysadmin server role 








NOTE 


When you have permission to perform an operation on the server, you also have permission to view information about 
the operation. Row-level security is enforced; only rows that you have permission to view are displayed. 








catalog.folders (SSISDB Database) 


11/23/2021 * 2 minutes to read « Edit Online 





Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Displays the folders in the Integration Services catalog. 


COLUMN NAME DATA TYPE DESCRIPTION 

id bigint The unique identifier of the folder. 

name sysname(nvarchar(128) The name of the folder, which is unique 
within the Integration Services catalog. 

description nvarchar(1024) The description of the folder. 


created_by_sid 


created_by_name 


created_time 


Remarks 


varbinary(85) 


nvarchar(128) 


datetimeoffset(7) 


The security identifier (SID) of the user 
who created the folder. 


The name of the user who created the 
folder. 


The date and time at which the folder 
was created. 


This view displays a row for each folder in the catalog. 


Permissions 

This view requires one of the following permissions: 
e READ permission on the folder 

e Membership to the ssis_admin database role 


e Membership to the sysadmin server role 


NOTE 


When you have permission to perform an operation on the server, you also have permission to view information about 


the operation. Row-level security is enforced; only rows that you have permission to view are displayed. 











catalog.object_parameters (SSISDB Database) 


11/23/2021 * 2 minutes to read « Edit Online 





Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Displays the parameters for all packages and projects in the Integration Services catalog. 


COLUMN NAME DATA TYPE DESCRIPTION 

parameter_id bigint The unique identifier (ID) of the 
parameter. 

project_id bigint The unique ID of the project. 

object_type smallint The type of parameter. The value is 


2@ for a project parameter and the 
value is 3@ for a package parameter. 


object_name sysname The name of the corresponding project 
or package. 

parameter_name sysname(nvarchar(128)) The name of the parameter. 

data_type nvarchar(128) The data type of the parameter. 

required bit When the value is 1 , the parameter 


value is required in order to start the 
execution. When the value is @ , the 
parameter value is not required to 
start the execution. 


sensitive bit When the value is 1 , the parameter 
value is sensitive. When the value is 
@ , the parameter value is not 


sensitive. 
description nvarchar(1024) An optional description of the package. 
design_default_value sql_variant The default value for the parameter 


that was assigned during the design of 
the project or package. 


default_value sql_variant The default value that is currently used 
on the server. 


value_type char(1) Indicates the type of parameter value. 
This field displays v when 
parameter_value is a literal value and 
R_ when the value is assigned by 
referencing an environment variable. 


COLUMN NAME 


value_set 


referenced_variable_name 


validation_status 


last_validation_time 


Permissions 


To see rows in this view, you must have one of the following permissions: 


e READ permission on the project 


DATA TYPE 


bit 


nvarchar(128) 


char(1) 


datetimeoffset(7) 


e Membership to the ssis_admin database role 


e Membership in the sysadmin server role. 


DESCRIPTION 


When the value is 1 , the parameter 
value has been assigned. When the 
value is @ , the parameter value has 
not been assigned. 


The name of the environment variable 
that is assigned to the value of the 
parameter. The default value is NULL. 


Identified for informational purposes 
only. Not used in SQL Server 2019 
(15.x). 


Identified for informational purposes 
only. Not used in SQL Server 2019 
(15.x). 


Row-level security is enforced; only rows that you have permission to view are displayed. 


catalog.object_versions (SSISDB Database) 


11/23/2021 * 2 minutes to read « Edit Online 





Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Displays the versions of objects in the Integration Services catalog. In this release, only versions of projects are 
supported in this view. 


COLUMN NAME DATA TYPE DESCRIPTION 


object_version_Isn bigint The unique identifier (ID) of the object 
version. This number is not guaranteed 
to be sequential. 


object_id bigint The unique ID of the object. 


object_type smallint The type of object. A value of 2¢ will 
be displayed for projects. 


object_name sysname(nvarchar(128)) The name of the object. 
description nvarchar(1024) The description of the project. 
created_by nvarchar(128) The name of the user who added the 


object to the catalog. 


created_time datetimeoffset The date and time at which the object 
was added to the catalog. 


restored_by nvarchar(128) The name of the user who restored the 
object. 
last_restored_time datetimeoffset The date and time at which the object 


was last restored. 


Remarks 


This view displays a row for each version of an object in the catalog. 


Permissions 

To see rows in this view, you must have one of the following permissions: 
e READ permission on the object 

e Membership to the ssis_admin database role 


e Membership in the sysadmin server role. 





NOTE 


Row-level security is enforced; only rows that you have permission to view are displayed. 





catalog.operation_messages (SSISDB Database) 


11/23/2021 + 2 minutes to read * Edit Online 





Applies to: Q@ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Displays messages that are logged during operations in the Integration Services catalog. 


COLUMN NAME DATA TYPE DESCRIPTION 

operation_message_id bigint The unique identifier (ID) of the 
message. 

operation_id bigint The unique ID of the operation. 

message_time datetimeoffset(7) The time when the message was 
created. 

message_type smallint The type of message displayed. 

message_source_type smallint The ID of the type of message source. 

message nvarchar(max) The text of the message. 

extended_info_id bigint The ID of additional information that 


relates to the operation message, 
found in the extended_operation_info 
view. 


Remarks 


This view displays a row for each message that is logged during an operation in the catalog. The message can be 
generated by the server, by the package execution process, or by the execution engine. 


This view displays the following message types: 


MESSAGE_TYPE VALUE DESCRIPTION 
“1 Unknown 
120 Error 

110 Warning 

70 Information 
10 Pre-validate 
20 Post-validate 


30 Pre-execute 


MESSAGE_TYPE VALUE DESCRIPTION 


40 Post-execute 
60 Progress 

50 StatusChange 
100 QueryCancel 
130 TaskFailed 

90 Diagnostic 
200 Custom 

140 DiagnosticEx 


Whenever an Execute Package task executes a child package, 
it logs this event. The event message consists of the 
parameter values passed to child packages. 


The value of the message column for DiagnosticEx is XML 


text. 
400 NonDiagnostic 
80 VariableValueChanged 
This view displays the following message source types. 
MESSAGE_SOURCE_TYPE DESCRIPTION 
10 Entry APIs, such as T-SQL and CLR Stored procedures 
20 External process used to run package (ISServerExec.exe) 
30 Package-level objects 
40 Control Flow tasks 
50 Control Flow containers 
60 Data Flow task 


Permissions 


This view requires one of the following permissions: 
e READ permission on the operation 
e Membership to the ssis_admin database role 


e Membership to the sysadmin server role 








NOTE 


When you have permission to perform an operation on the server, you also have permission to view information about 
the operation. Row-level security is enforced; only rows that you have permission to view are displayed. 








catalog.operations (SSISDB Database) 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Displays the details of all operations in the Integration Services catalog. 


COLUMN NAME 


operation_id 


operation_type 


created_time 


object_type 


object_id 


object_name 


status 


start_time 


end_time 


caller_sid 


caller_name 


process_id 


stopped_by_sid 


DATA TYPE 


bigint 


smallint 


datetimeoffset 


smallint 


bigint 


nvarchar(260) 


int 


datetimeoffset 


datetimeoffsset 


varbinary(85) 


nvarchar(128) 


int 


varbinary(85) 


DESCRIPTION 


The unique identifier (ID) of the 
operation. 


The type of operation. 


The time when the operation was 
created. 


The type of object affected by the 
operation. The object may be a folder ( 

1@ ), project ( 2@ ), package ( 3@ ), 
environment ( 4@ ), or instance of 
execution ( 52 ). 


The ID of the object affected by the 
operation. 


The name of the object. 


The status of the operation. The 
possible values are created (1 ), 
running ( 2 ), canceled ( 3 ), failed ( 4 
), pending (5 ), ended unexpectedly ( 

6 ), succeeded ( 7 ), stopping ( 8 ), 
and completed ( 9 ). 


The time when the operation started. 


The time when the operation ended. 


The security ID (SID) of the user if 
Windows Authentication was used to 
log on. 


The name of the account that 
performed the operation. 


The process ID of the external process, 
if applicable. 


The SID of the user who stopped the 
operation. 


COLUMN NAME 


stopped_by_name 


server_name 


machine_name 


Remarks 


DATA TYPE 


nvarchar(128) 


nvarchar(128) 


nvarchar(128) 


DESCRIPTION 


The name of the user who stopped the 
operation. 


The Windows server and instance 
information for a specified instance of 
SQL Server. 


The computer name on which the 
server instance is running. 


This view displays one row for each operation in the Integration Services catalog. It allows the administrator to 


enumerate all the logical operations that were performed on the server, such as deploying a project or executing 


a package. 


This view displays the following operation types, as listed in the operation_type column: 


OPERATION_TYPE VALUE 


101 


106 


200 


202 


300 


OPERATION_TYPE 
DESCRIPTION 


Integration Services 
initialization 


Retention window 


(SQL Agent job) 


MaxProjectVersion 


(SQL Agent job) 


deploy_project 


(Stored procedure) 


restore_project 


(Stored procedure) 


create_execution and 
start_execution 


(Stored procedures) 


stop_operation 


(Stored procedure) 


validate_project 


(Stored procedure) 


OBJECT_NAME 


OBJECT_ID DESCRIPTION DESCRIPTION 
NULL NULL 
NULL NULL 
NULL NULL 
Project ID Project name 
Project ID Project name 
Project ID NULL 
Project ID NULL 
Project ID Project name 


OPERATION_TYPE OBJECT_NAME 
OPERATION_TYPE VALUE DESCRIPTION OBJECT_ID DESCRIPTION DESCRIPTION 


301 validate_package Project ID Package name 


(Stored procedure) 


1000 configure_catalog NULL NULL 


(Stored procedure) 


Permissions 

This view requires one of the following permissions: 
e READ permission on the operation 

e Membership to the ssis_admin database role 


e Membership to the sysadmin server role 


NOTE 


When you have permission to perform an operation on the server, you also have permission to view information about 


the operation. Row-level security is enforced; only rows that you have permission to view are displayed. 





catalog.packages (SSISDB Database) 


11/23/2021 * 2 minutes to read « Edit Online 





Applies to: Q@ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Displays the details for all packages that appear in the SSISDB catalog. 


COLUMN NAME 


package_id 


name 


package_guid 


description 


package_format_version 


version_major 
version_minor 
version_build 


version_comments 


version_guid 


project_id 


entry_point 


validation_status 


last_validation_time 


Remarks 


DATA TYPE 


bigint 


nvarchar(256) 


uniqueidentifier 


nvarchar(1024) 


int 


int 


int 


int 


nvarchar(1024) 


uniqueidentifier 


bigint 


bit 


char(1) 


datetimeoffset(7) 


This view displays a row for each package in the catalog. 


DESCRIPTION 


The unique identifier (ID) of the 
package. 


The unique name of the package. 


The globally unique identifier (GUID) 
that identifies the package. 


An optional description of the package. 


The version of SQL Server that was 
used to develop the package. 


The major version of the package. 


The minor version of the package. 


The build version of the package. 


Optional comments on the version of 
the package. 


The GUID that uniquely identifies the 
version of the package. 


The unique ID of the project. 


The value of 1. signifies that the 
package is meant to be started 
directly. The value of @ signifies that 
the package is meant to be started by 
another package with the Execute 
Package task. The default value is 1 . 


The status of the validation. 


The time of the last validation. 


Permissions 

This view requires one of the following permissions: 
e READ permission on the corresponding project 
e Membership to the ssis_admin database role 


e Membership to the sysadmin server role. 





NOTE 


If you have READ permission on a project, you also have READ permission on all of the packages and environment 
references associated with that project. Row-level security is enforced; only rows that you have permission to view are 
displayed. 








catalog.projects (SSISDB Database) 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Displays the details for all projects that appear in the SSISDB catalog. 


COLUMN NAME 


project_id 


folder_id 


name 
description 


project_format_version 


deployed_by_sid 


deployed_by_name 


last_deployed_time 


created_time 


object_version_Isn 


validation_status 


last_validation_time 


Remarks 


DATA TYPE 


bigint 


bigint 


sysname 


nvarchar(1024) 


int 


varbinary(85) 


nvarchar(128) 


datetimeoffset(7) 


datetimeoffset(7) 


bigint 


char(1) 


datetimeoffset(7) 


This view displays a row for each project in the catalog. 


Permissions 


This view requires one of the following permissions: 


e@ READ permission on the project 


e Membership to the ssis_admin database role 


DESCRIPTION 


The unique identifier (ID) of the 
project. 


The unique ID of the folder where the 
project resides. 


The name of the project. 


The optional description of the project. 


The version of SQL Server that was 
used to develop the project. 


The security identifier (SID) of the user 
who installed the project. 


The name of the user who installed the 
project. 


The date and time at which the project 
was deployed or redeployed. 


The date and time at which the project 
was created. 


The version of the project. This number 
is not guaranteed to be sequential. 


The validation status. 


The time of the last validation. 





e Membership to the sysadmin server role. 


NOTE 


If you have READ permission on a project, you also have READ permission on all of the packages and environment 


references associated with that project. Row-level security is enforced; only rows that you have permission to view are 
displayed. 








catalog.validations (SSISDB Database) 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Displays the details of all project and package validations in the Integration Services catalog. 


COLUMN NAME 


validation_id 


environment_scope 


validate_type 


folder_name 


project_name 


project_Isn 


use32bitruntime 


reference_id 


operation_type 


DATA TYPE 


bigint 


Char(1) 


Char(1) 


nvarchar(128) 


nvarchar(128) 


bigint 


bit 


bigint 


smallint 


DESCRIPTION 


The unique identifier (ID) of the 
validation. 


Indicates the environment references 
that are considered by the validation. 
When the value is A , all environment 
references associated with the project 
are included in the validation. When 
the value is s , only asingle 
environment reference is included. 
When the value is D , no environment 
references are included and each 
parameter must have a literal default 
value in order to pass validation. 


The type of validation to perform. The 
possible types of validation are 
dependency validation ( D ) or full 
validation ( F ). Package validation is 
always full validation. 


The name of the folder that contains 
the corresponding project. 


The name of the project. 


The version of the project that is 
validated against. 


Indicates if the 32-bit runtime is used 
to run the package on a 64-bit 
operating system. When the value is 
1 , the execution is performed with 
the 32-bit runtime. When the value is 
@ , the execution is performed with 
the 64-bit runtime. 


Unique ID of the project-environment 
reference that is used by the project to 
reference an environment. 


The type of operation. The operations 
displayed in this view include project 
validation ( 30@ ) and package 
validation ( 301 ). 


COLUMN NAME 


object_name 


object_type 


object_id 


start_time 


end_time 


status 


caller_sid 


caller_name 


process_id 


stopped_by_sid 


stopped_by_name 


server_name 


machine_name 


dump_id 


DATA TYPE 


nvarhcar(260) 


smallint 


bigint 


datetimeoffset(7) 


datetimeoffsset(7) 


int 


varbinary(85) 


nvarchar(128) 


int 


varbinary(85) 


nvarchar(128) 


nvarchar(128) 


nvarchar(128) 


uniqueidentifier 


DESCRIPTION 


The name of the object. 


The type of object. The object may be 
a project ( 2@ ) or a package ( 3¢ ). 


The ID of the object affected by the 
operation. 


The time when the operation started. 


The time when the operation ended. 


The status of the operation. The 
possible values are created (1 ), 
running ( 2 ), canceled ( 3 ), failed ( 4 
), pending (5 ), ended unexpectedly ( 
6 ), succeeded ( 7 ), stopping ( 8 ), 
and completed ( 9 ). 


The security ID (SID) of the user if 
Windows Authentication was used to 
log on. 


The name of the account that 
performed the operation. 


The process ID of the external process, 
if applicable. 


The SID of the user who stopped the 
operation. 


The name of the user who stopped the 
operation. 


The Windows server and instance 
information for a specified instance of 
SQL Server. 


The computer name on which the 
server instance is running. 


The ID of the execution dump. 


Remarks 


This view displays one row for each validation in the Integration Services catalog. 


Permissions 


This view requires one of the following permissions: 


e READ permission on the corresponding operation 


e Membership to the ssis_admin database role 


e Membership to the sysadmin server role 








NOTE 


When you have permission to perform an operation on the server, you also have permission to view information about 


the operation. Row-level security is enforced; only rows that you have permission to view are displayed. 








catalog.master_properties (SSISDB Database) 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Displays the properties of the Integration Services Scale Out Master. 


COLUMN NAME DATA TYPE DESCRIPTION 
property_name nvarchar(256) The name of the scale out master 
property. 
property_value nvarchar(max) The value of the scale out master 
property. 
Remarks 


This view displays a row for each scale out master property. The properties displayed by this view include the 
following: 


PROPERTY NAME DESCRIPTION 

CLUSTER_LOGDB_SERVER The SQL Server that log database locates in. 

LAST_ONLINE_TIME The last time when Scale Out Master is online. 

MACHINE_IP The IP of the machine. 

MACHINE_NAME The name of the machine. 

MASTER_ADDRESS The endpoint of Scale Out Master. 

MASTER_SERVICE_PORT The port in the endpoint of Scale Out Master. 

SSLCERT_THUMBPRINT The thumbprint of Scale Out Master certificate. 
Permissions 


All members of public database role have read permission for this view. 


catalog.worker_agents (SSISDB Database) 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Displays the information for the Integration Services Scale Out Worker. 


COLUMN NAME 


DATA TYPE 


DESCRIPTION 


WorkerAgentld uniqueidentifier The worker agent ID of Scale Out 
Worker. 

IsEnabled bit Whether the Scale Out Worker is 
enabled. 

DisplayName nvarchar(256) The display name of Scale Out Worker. 

Description nvarchar(256) The description of Scale Out Worker. 

MachineName nvarchar(256) The machine name for Scale Out 
Worker. 

Tags nvarchar(max) The tags of Scale Out Worker. 

UserAccount nvarchar(256) The user account running the Scale 
Out Worker service. 

LastOnlineTime datetimeoffset(7) The last time that the Scale Out 
Worker is online. 

Remarks 


This view displays a row for each Scale Out Worker connecting to the Scale Out Master working with the SSISDB 
catalog. 


Permissions 

This view requires one of the following permissions: 

e Membership to the ssis_admin database role 

e Membership to the ssis_cluster_executor database role 


e Membership to the sysadmin server role 


Stored Procedures (Integration Services Catalog) 


11/23/2021 * 4 minutes to read « Edit Online 





Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 
Applies to: @sal Server (all supported versions) 


This section describes the Transact-SQL stored procedures that are available for administering Integration 
Services projects that have been deployed to an instance of SQL Server. 


Call the Integration Services stored procedures to add, remove, modify, or execute objects that are stored in the 
SSISDB catalog. 


The default name of the catalog is SSISDB. The objects that are stored in the catalog include projects, packages, 
parameters, environments, and operational history. 


You can use the database views and stored procedures directly, or write custom code that calls the managed API. 
Management Studio and the managed API query the views and call the stored procedures that are described in 
this section to perform many of their tasks. 


In This Section 


catalog.add_data_tap 
Adds a data tap on the output of a component in a package data flow. 


catalog.add_data_tap_by_guid 
Adds a data tap to a specific data flow path in a package data flow. 


catalog.check_schema_version 
Determines whether the SSISDB catalog schema and the Integration Services binaries (ISServerExec and 
SQLCLR assembly) are compatible. 


catalog.clear_object_parameter_value (SSISDB Database) 
Clears the value of a parameter for an existing Integration Services project or package that is stored on the 
server. 


catalog.configure_catalog (SSISDB Database) 
Configures the Integration Services catalog by setting a catalog property to a specified value. 


catalog.create_environment (SSISDB Database) 


Creates an environment in the Integration Services catalog. 


catalog.create_environment_reference (SSISDB Database) 


Creates an environment reference for a project in the Integration Services catalog. 


catalog.create_environment_variable (SSISDB Database) 
Create an environment variable in the Integration Services catalog. 


catalog.create_execution (SSISDB Database) 
Creates an instance of execution in the Integration Services catalog. 


catalog.create_execution_dump 
Causes a running package to pause and create a dump file. 


catalog.create_folder (SSISDB Database) 


Creates a folder in the Integration Services catalog. 


catalog.delete_environment (SSISDB Database) 
Deletes an environment from a folder in the Integration Services catalog. 


catalog.delete_environment_reference (SSISDB Database) 
Deletes an environment reference from a project in the Integration Services catalog. 


catalog.delete_environment_variable (SSISDB Database) 


Deletes an environment variable from an environment in the Integration Services catalog. 


catalog.delete_folder (SSISDB Database) 
Deletes a folder from the Integration Services catalog. 


catalog.delete_project (SSISDB Database) 
Deletes an existing project from a folder in the Integration Services catalog. 


catalog.deny_permission (SSISDB Database) 
Denies a permission on a securable object in the Integration Services catalog. 


catalog.deploy_project (SSISDB Database) 
Deploys a project to a folder in the Integration Services catalog or updates an existing project that has been 
deployed previously. 


catalog.get_parameter_values (SSISDB Database) 
Resolves and retrieves the default parameter values from a project and corresponding packages in the 
Integration Services catalog. 


catalog.get_project (SSISDB Database) 
Retrieves the properties of an existing project in the Integration Services catalog. 


catalog.grant_permission (SSISDB Database) 
Grants a permission on a securable object in the Integration Services catalog. 


catalog.move_environment (SSISDB Database) 
Moves an environment from one folder to another within the Integration Services catalog. 


catalog.move_project ((SSISDB Database) 
Moves a project from one folder to another within the Integration Services catalog. 


catalog.remove_data_tap 
Removes a data tap from a component output that is in an execution. 


catalog.rename_environment (SSISDB Database) 
Renames an environment in the Integration Services catalog. 


catalog.rename_folder (SSISDB Database) 
Renames a folder in the Integration Services catalog. 


catalog.restore_project (SSISDB Database) 
Restores a project in the Integration Services catalog to a previous version. 


catalog.revoke_permission (SSISDB Database) 
Revokes a permission on a securable object in the Integration Services catalog. 


catalog.set_environment_property (SSISDB Database) 
Sets the property of an environment in the Integration Services catalog. 


catalog.set_environment_reference_type (SSISDB Database) 


Sets the reference type and environment name associated with an existing environment reference for a project 


in the Integration Services catalog. 


catalog.set_environment_variable_property (SSISDB Database) 
Sets the property of an environment variable in the Integration Services catalog. 


catalog.set_environment_variable_protection (SSISDB Database) 
Sets the sensitivity bit of an environment variable in the Integration Services catalog. 


catalog.set_environment_variable_value (SSISDB Database) 
Sets the value of an environment variable in the Integration Services catalog. 


catalog.set_execution_parameter_value (SSISDB Database) 
Sets the value of a parameter for an instance of execution in the Integration Services catalog. 


catalog.set_execution_property_override_value 
Sets the value of a property for an instance of execution in the Integration Services catalog. 


catalog.set_folder_description (SSISDB Database) 
Sets the description of a folder in the Integration Services catalog. 


catalog.set_object_parameter_value (SSISDB Database) 
Sets the value of a parameter in the Integration Services catalog. Associates the value to an environment 
variable or assigns a literal value that will be used by default if no other values are assigned. 


catalog.start_execution (SSISDB Database) 
Starts an instance of execution in the Integration Services catalog. 


catalog.startup 
Performs maintenance of the state of operations for the SSISDB catalog. 


catalog.stop_operation (SSISDB Database) 
Stops a validation or instance of execution in the Integration Services catalog. 


catalog.validate_package (SSISDB Database) 
Asynchronously validates a package in the Integration Services catalog. 


catalog.validate_project (SSISDB Database) 
Asynchronously validates a project in the Integration Services catalog. 


catalog.add_execution_worker (SSISDB Database) 
Adds a Integration Services Scale Out Worker to an instance of execution in Scale Out. 


catalog.enable_worker_agent (SSISDB Database) 
Enable a Scale Out Worker for Scale Out Master working with this Integration Services catalog. 


catalog.disable_worker_agent (SSISDB Database) 
Disable a Scale Out Worker for Scale Out Master working with this Integration Services catalog. 


catalog.add_data_tap 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 
Applies to: @sal Server (all supported versions) 


Adds a data tap on the output of a component in a package data flow, for an instance of the execution. 


Syntax 


catalog.add_data_tap [ @execution_id = ] execution_id 

» [ @task_package_path = ] task_package_path 

» [| @dataflow_path_id_string = ] dataflow_path_id_string 
» [ @data_filename = ] data_filename 

» [ @max_rows = ] max_rows 

» [ @data_tap_id = ] data_tap_id OUTPUT 


Arguments 


[ @execution_id = ] execution_id 
The execution ID for the execution that contains the package. The execution_idis a bigint. 


[ @task_package_path = ] task_package_path 

The package path for the data flow task. The PackagePath property for the data flow task specifies the path. 
The path is case-sensitive. To locate the package path, in SQL Server Data Tools right-click the Data Flow task, 
and then click Properties. The PackagePath property appears in the Properties window. 


The task_package_path is a nvarchar(max). 


[ @dataflow_path_id_string = ] dataflow_path_id_string 
The identification string for the data flow path. A path connects two data flow components. The 
IdentificationString property for the path specifies the string. 


To locate the identification string, in SQL Server Data Tools right-click the path between two data flow 
components and then click Properties. The IdentificationString property appears in the Properties window. 


The dataflow_path_id_stringis anvarchar(4000). 


[ @data_filename = ] data_filename 

The name of the file that stores the tapped data. If the data flow task executes inside a Foreach Loop or a For 
Loop container, separate files store tapped data for each iteration of the loop. Each file is prefixed with a number 
that corresponds to an iteration. 


By default, the file is stored in the < drive>:\Program Files\Microsoft SQL Server\130\DTS\DataDumps folder. 
The data_filename is anvarchar(4000). 


[ @max_rows = ] Max_rows 
The number of rows that are captured during the data tap. If this value is not specified, all rows are captured. The 
max_rows is an int. 


[ @data_tap_id = ] data_tap_id 
Returns the ID of the data tap. The data_tap_idis a bigint. 


Example 


In the following example, a data tap is created on the data flow path, 

‘Paths[OLE DB Source.OLE DB Source Output] , in the data flow task, \Package\Data Flow Task . The tapped data is 
stored in the outpute.txt file in the DataDumps folder (< drive>:\Program Files\Microsoft SQL 
Server\130\DTS\DataDumps). 


Declare @execution_id bigint 
Exec SSISDB.Catalog.create_execution @folder_name='Packages' ,@project_name='SSISPackages', 
@package_name='Package.dtsx' ,@reference_id=Null, @use32bitruntime=False, @execution_id=@execution_id OUTPUT 


Exec SSISDB.Catalog.set_execution_parameter_value @execution_id,5@, ‘LOGGING_LEVEL', @ 


Exec SSISDB.Catalog.add_data_tap @execution_id, @task_package path='\Package\Data Flow Task’, 
@dataflow_path_id_string = 'Paths[OLE DB Source.OLE DB Source Output]', @data_filename = ‘output@.txt' 


Exec SSISDB.Catalog.start_execution @execution_id 


«| BE P| 


Remarks 


To add data taps, the instance of the execution must be in the created state (a value of 1 in the status column of 
the catalog.operations (SSISDB Database)view) . The state value changes once you run the execution. You can 
create an execution by calling catalog.create_execution (SSISDB Database). 


The following are considerations for the add_data_tap stored procedure. 


e If an execution contains a parent package and one or more child packages, you need to add a data tap for 
each package that you want to tap data for. 


e If a package contains more than one data flow task with the same name, the task_package_path uniquely 
identifies the data flow task that contains the component output that is tapped. 


e When you add data tap, it is not validated before the package is run. 


e It is recommended that you limit the number of rows that are captured during the data tap, to avoid 
generating large data files. If the machine on which the stored procedure is executed, runs out of storage 
space for the data files, the package stops running and an error message is written to a log. 


e Running the add_data_tap stored procedure impacts the performance of the package. It is recommended 
that you run the stored procedure only to troubleshoot data issues. 


@ Toaccess the file that stores the tapped data, you must be an administrator on the machine on which the 
stored procedure is run. You must also be the user who started the execution that contains the package 
with the data tap. 


Return Codes 


0 (success) 


When the stored procedure fails, it throws an error. 


Result Set 


None 


Permissions 


This stored procedure requires one of the following permissions: 


e MODIFY permissions on the instance of execution 
e Membership to the ssis_admin database role 


e Membership to the sysadmin server role 


Errors and Warnings 


The following list describes conditions that cause the stored procedure to fail. 
e The user does not have MODIFY permissions. 
e The data tap for the specified component, in the specified package, has already been added. 


e The value specified for the number of rows to capture, is not valid. 
Requirements 


External Resources 


Blog entry, SSIS 2012: A Peek to Data Taps, on rafael-salas.com. 


See Also 


catalog.add_data_tap_by_guid 


catalog.add_data_tap_by_guid 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 
Applies to: @ sal Server (all supported versions) 


Adds a data tap to a specific data flow path in a package data flow, for an instance of the execution. 


Syntax 


catalog.add_data_tap_by_guid [ @execution_id = ] execution_id 
» [ @dataflow_task_guid = ] dataflow_task_guid 

» [| @dataflow_path_id_string = ] dataflow_path_id_string 

» [ @data_filename = ] data_filename 

» [ @max_rows = ] max_rows 

» [ @data_tap_id = ] data_tap_id 


Arguments 


[ @execution_id = ] execution_id 
The execution ID for the execution that contains the package. The execution_idis a bigint. 


[ @dataflow_task_guid = ] dataflow_task_guid 
The ID for the data task flow in the package that contains the data flow path to be tapped. The 
dataflow_task_guid is auniqueidentifier. 


[ @dataflow_path_id_string = ] dataflow_path_id_string 
The identification string for the data flow path. A path connects two data flow components. The 
IdentificationString property for the path specifies the string. 


To locate the identification string, in SQL Server Data Tools right-click the path between two data flow 
components and then click Properties. The IdentificationString property appears in the Properties window. 


The dataflow_path_id_stringis anvarchar(4000). 


[ @data_filename = ] data_filename 

The name of the file that stores the tapped data. If the data flow task executes inside a Foreach Loop or a For 
Loop container, separate files store tapped data for each iteration of the loop. Each file is prefixed with a number 
that corresponds to an iteration. Data tap files are written to the folder "<SQL Server installation 
folder>\130\DTS\". The data_filename is a nvarchar(4000). 


[ @max_rows = ] max_rows 
The number of rows that are captured during the data tap. If this value is not specified, all rows are captured. The 
max_rows is an int. 


[ @data_tap_id = ] data_tap_id 
The ID of the data tap. The data_tap_idis a bigint. 


Example 


In the following example, a data tap is created on the data flow path, 
Paths[SRC DimDCVentor.OLE DB Source Output] , in the data flow task {D978A2E4-E@5D-4374-9B@5-50178A8817E8} . The 


tapped data is stored in the DCVendorOutput.csv file. 


exec catalog.add_data_tap_by_ guid @execution_id, 
"{D978A2E4-E@5D-4374-9B@5-50178A8817E8}' , 
"Paths[SRC DimDCVentor.OLE DB Source Output]', 
"D:\demos\datafiles\DCVendorOutput.csv' 


Remarks 


To add data taps, the instance of the execution must be in the created state (a value of 1 in the status column of 
the catalog.operations (SSISDB Database)view) . The state value changes once you run the execution. You can 
create an execution by calling catalog.create_execution (SSISDB Database). 


The following are considerations for the add_data_tap_by_guid stored procedure. 
e When you add a data tap, it is not validated before the package is run. 


e It is recommended that you limit the number of rows that are captured during the data tap, to avoid 
generating large data files. If the machine on which the stored procedure is executed, runs out of storage 
space for the data files, the stored procedure stops running. 


e Running the add_data_tap_by_guid stored procedure impacts the performance of the package. It is 
recommended that you run the stored procedure only to troubleshoot data issues. 


e To access the file that stores the tapped data, you must have administrator permissions on the machine 
on which the stored procedure Is run, or you must be the user that started the execution that contains the 
package with the data tap. 


Return Codes 


O (success) 


When the stored procedure fails, it throws an error. 


Result Set 


None 


Permissions 

This stored procedure requires one of the following permissions: 
e MODIFY permissions on the instance of execution 

e Membership to the ssis_admin database role 


e Membership to the sysadmin server role 


Errors and Warnings 

The following list describes conditions that cause the stored procedure to fail. 

e The user does not have MODIFY permissions. 

e The data tap for the specified component, in the specified package, has already been added. 


e The value specified for the number of rows to capture, is not valid. 


Requirements 


See Also 


catalog.add_data_tap 


catalog.add_execution_worker (SSISDB Database) 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 
Applies to: @ sal Server 2017 (14.x) and later 


Adds a Integration Services Scale Out Worker to an instance of execution in Scale Out. 


Syntax 


catalog.add_execution_worker [ @execution_id = ] execution_id, [ @workeragent_id = ] workeragent_id 


Arguments 


[ @execution_id = ] execution_id 
The unique identifier for the instance of execution. The execution_id is bigint. 


[@workeragent_id = ] workeragent_id 
The worker agent id of a Scale Out Worker. The workeragent_idis uniqueldentifier. 


Return Code Value 


O (success) 


Result Sets 


None 


Permissions 

This stored procedure requires one of the following permissions: 
e READ and MODIFY permissions on the instance of execution 
e Membership to the ssis_admin database role 


e Membership to the sysadmin server role 


Errors and Warnings 

The following list describes some conditions that may raise an error or warning: 
e The user does not have the appropriate permissions. 

e The execution identifier is not valid. 

e The worker agent id is not valid. 


e The execution is not in Scale Out. 


See Also 


Execute packages in Scale Out. 


catalog.check_schema_version 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 
Applies to: @ sal Server (all supported versions) 


Determines whether the SSISDB catalog schema and the Integration Services binaries (ISServerExec and 
SQLCLR assembly) are compatible. 


The ISServerExec.exc logs an error message when the schema and the binaries are incompatible. 


The SSISDB schema version is incremented when the schema changes during the application of patches and 
during upgrades. It is recommended that you run this stored procedure after an SSISDB backup has been 
restored to ensure that the schema and binaries are compatible. 


Syntax 


catalog.check_schema_version [ @use32bitruntime = ] use32bitruntime 


Arguments 


[ @use32bitruntime= ] use32bitruntime 
When the parameter is set to 1, the 32-bit version of dtexec is called. The use32bitruntime is an int. 


Return Code Value 


Returns O for success. 


Result Set 


Returns a table that has the following format: 


COLUMN NAME DATA TYPE DESCRIPTION 
SERVER_BUILD decimal SQL Server version. For example, a 
server running SQL Server 2014 is 
14.0.3335.7. 
SCHEMA_VERSION tinyint SQL Server version number. For 


example, SQL Server 2017 and 2019 
are 6 and 7 respectively. 


SCHEMA_BUILD string Schema build. 
ASSEMBLY_BUILD string Assembly build. 
SHARED_COMPONENT_VERSION string Shared component version. 


Permissions 


This stored procedure requires the following permission: 


e Membership to the ssis_admin database role. 


catalog.clear_object_parameter_value (SSISDB 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 
Applies to: @ sal Server (all supported versions) 


Clears the value of a parameter for an existing Integration Services project or package that is stored on the 
server. 


Syntax 


catalog.clear_object_parameter [ @folder_name = ] folder_name 
» [ @project_name = ] project_name 
» [ @object_type = ] object_type 
» [ @object_name = ] object_name 
» [ @parameter_ name = ] parameter_name 


Arguments 


[ @folder_name = ] fo/der_name 
The name of the folder that contains the project. The fo/der_name is nvarchar(128). 


[ @project_name = ] project_name 
The name of project. The project_name is nvarchar(128). 


[ @object_type = ] object_type 
The type of object. Valid values include 2e for aprojectand 3e for a package. The object_typeis smalllnt. 


[ @ object __name = ] object_name 
The name of the package. The object_name is nvarchar(260). 


[ @parameter_ name = ] parameter_name 


The name of the parameter. The parameter_ name is nvarchar(128). 


Return Code Value 


0 (success) 


Result Sets 


None 


Permissions 
This stored procedure requires one of the following permissions: 
e@ READ and MODIFY permissions on the project 


e Membership to the ssis_admin database role 


e Membership to the sysadmin server role 


Errors and Warnings 


The following list describes some conditions that may cause the clear_object_parameter stored procedure to 
raise an error: 


e An invalid object type is specified or the object name cannot be found in the project. 
e The project does not exist, the project is not accessible, or the project name is invalid 
e Aninvalid parameter name is specified. 


e The user does not have the appropriate permissions. 


f-} f=] (e1e Kee)a)i(6[01-Wer-] 8-1 (010M Oss) D) 5 BY-]F-]0)-\~)) 


11/23/2021 * 2 minutes to read « Edit Online 





Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 
Applies to: @ sal Server (all supported versions) 


Configures the Integration Services catalog by setting a catalog property to a specified value. 


Syntax 


catalog.configure_catalog [ @property_name = ] property_name , [ @property_value = ] property_value 


Arguments 


[ @property_name = ] property_name 
The name of the catalog property. The property_name is nvarchar(255). For more information about available 
properties, see catalog.catalog_properties (SSISDB Database). 


[ @property_value = ] property_value 
The value of the catalog property. The property_va/ueis nvarchar(255). For more information about property 
values, see catalog.catalog_properties (SSISDB Database) 


Return Code Values 


0 (success) or 1 (failure) 


Result Sets 


None 


Remarks 
This stored procedure determines whether the property_va/ue is valid for each property_name. 


This stored procedure can be performed only when there are no active executions, such as pending, queued, 
running, and paused executions. 


While the catalog is being configured, all other catalog stored procedures fail with the error message "Server is 
currently being configured." 


When the catalog is configured, an entry is written to the operation log. 


Permissions 
This stored procedure requires one of the following permissions: 
e Membership to the ssis_admin database role 


e Membership to the sysadmin server role 


Errors and Warnings 
The following list describes some conditions that may raise an error or warning: 
e The property does not exist 


e The property value is invalid 


catalog.create_customized_logging_level 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 
Applies to: @ sal Server 2016 (13.x) and later 


Creates a new customized logging level. For more info about customized logging levels, see Integration Services 
(SSIS) Logging. 


Syntax 


catalog.create_customized_logging level [ @level_name = ] level_name 
» [ @level_description = ] level_description 
» L @profile_value = ] profile_value 
» [ @events_value = ] events_value 
» [ @level_id = ] level_id OUT 


Arguments 


[ @level_name = ] /eve/_name 


The name for the new existing customized logging level. 
The /evel_ name is nvarchar(128). 


[ @level_description = ] /evel_ description 
The description for the new existing customized logging level. 


The /evel_description is nvarchar(max). 


[ @profile_value = ] profile_value 
The statistics that you want the new customized logging level to log. 


Valid values for statistics include the following. These values correspond to the values on the Statistics tab of 
the Customized Logging Level Management dialog box. 


e Execution = 0 

e Volume = 1 

e@ Performance = 2 

The profile_value is a bigint. 


[ @events_value = ] events_value 
The events that you want the new customized logging level to log. 


Valid values for events include the following. These values correspond to the values on the Events tab of the 
Customized Logging Level Management dialog box. 


EVENTS WITHOUT EVENT CONTEXT 


OnVariableValueChanged = 0 
OnExecutionStatusChanged = 1 
OnPreExecute = 2 
OnPostExecute = 3 
OnPreValidate = 4 
OnPostValidate = 5 
OnWarning = 6 
OnInformation = 7 

OnError = 8 

OnTaskFailed = 9 

OnProgress = 10 
OnQueryCancel = 11 
OnBreakpointHit = 12 
OnCustomEvent = 13 
Diagnostic = 14 

DiagnosticEx = 15 


NonDiagnostic = 16 


The events_value is a bigint. 


[ @level_id = ] /evel_id OUT 
The id of the new customized logging level. 


The /evel_idis a bigint. 


Remarks 


To combine multiple values in Transact-SQL for the profile_value or events_va/ue argument, follow this example. 


EVENTS WITH EVENT CONTEXT 


OnVariableValueChanged_IncludeContext = 32 
OnExecutionStatusChanged_IncludeContext = 33 
OnPreExecute_IncludeContext = 34 
OnPostExecute_IncludeContext = 35 
OnPreValidate_IncludeContext = 36 
OnPostValidate_IncludeContext = 37 
OnWarning_IncludeContext = 38 
OnInformation_IncludeContext = 39 
OnError_IncludeContext = 40 
OnTaskFailed_IncludeContext = 41 
OnProgress_IncludeContext = 42 
OnQueryCancel_IncludeContext= 43 
OnBreakpointHit_IncludeContext = 44 
OnCustomEvent_IncludeContext = 45 
Diagnostic_IncludeContext = 46 
DiagnosticEx_IncludeContext = 47 


NonDiagnostic_IncludeContext = 48 


To capture the OnError (8) and DiagnosticEx (15) events, the formula to calculate events_value is 


28 + 2°15 = 33024. 


Return Codes 


0 (success) 


When the stored procedure fails, it throws an error. 


Result Set 


None 


Permissions 


This stored procedure requires one of the following permissions: 
e Membership in the ssis_admin database role 


e Membership in the sysadmin server role 


Errors and Warnings 
The following list describes conditions that cause the stored procedure to fail. 


e The user does not have the required permissions. 


catalog.create_environment (SSISDB Database) 
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Applies to: Q sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 
Applies to: @sal Server (all supported versions) 


Creates an environment in the Integration Services catalog. 


Syntax 


catalog.create_environment [ @folder_name = ] folder_name 
» L @environment_name = ] environment_name 
[ , [ @environment_description = ] environment_description ] 


Arguments 


[@folder_name =] fo/der_name 
The name of the folder to contain the environment. The fo/der_name is nvarchar(128). 


[@environment_name =] environment_name 


The name of the environment. The environment_name is nvarchar(128). 


[@environment_description=] environment_description 
An optional description of the environment. The environment_description is nvarchar(1024). 


Return Code Value 


O (success) 


Result Sets 


None 


Permissions 

This stored procedure requires one of the following permissions: 
e READ and MODIFY permissions on the folder 

e Membership to the ssis_admin database role 

e database role 


e Membership to the sysadmin server role 


Errors and Warnings 
The following list describes some conditions that may raise an error or warning: 
e The folder name cannot be found 


e Anenvironment that has the same name already exists in the specified folder 


Remarks 


The environment name must be unique within the folder. 


catalog.create_environment_reference (SSISDB 


Database) 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 
Applies to: @ sal Server (all supported versions) 


Creates an environment reference for a project in the Integration Services catalog. 


Syntax 


catalog.create_environment_reference [ @folder_name = ] folder_name 
» L @project_name = ] project_name 
» L @environment_name = ] environment_name 
» L @reference_type = ] reference_type 
[ . [ @environment_folder_name = ] environment_folder_name ] 
[ , [ @reference_id = ] reference_id OUTPUT ] 


Arguments 


[ @folder_name = ] folder_name 
The name of the folder of the project that is referencing the environment. The fo/der_name is nvarchar(128). 


[ @project_name = ] project_name 
The name of the project that is referencing the environment. The project_name is nvarchar(128). 


[ @environment_name = ] environment_name 
The name of the environment being referenced. The environment_name is nvarchar(128). 


[ @reference_type = ] reference_type 

Indicates whether the environment can be located in the same folder as the project (relative reference) or ina 
different folder (absolute reference). Use the value R to indicate a relative reference. Use the value A to 
indicate an absolute reference. The reference_typeis char(1). 


[ @environment_folder_name = ] environment_folder_name 
The name of the folder in which the environment that being referenced is located. This value is required for 
absolute references. The environment_folder_name is nvarchar(128). 


[ @reference_id = ] reference_id 
Returns the unique identifier for the new reference. This parameter is optional. The reference_idis bigint. 


Return Code Value 


O (success) 


Result Sets 


None 


Permissions 


This stored procedure requires one of the following permissions: 
e READ and MODIFY permissions on the project, and READ permission on the environment 
e Membership to the ssis_admin database role 


e Membership to the sysadmin server role 


Errors and Warnings 

The following list describes some conditions that may raise an error or warning: 
e The folder name is not valid 

e The project name is not valid 

e The user does not appropriate permissions 


e An absolute reference is specified by using the a character in the reference_/ocation parameter, but the 


name of the folder was not specified with the environment. folder_name parameter. 


Remarks 


A project can have relative or absolute environment references. Relative references refer to the environment by 
name and require that it resides in the same folder as the project. Absolute references refer to the environment 
by name and folder, and may refer to environments that reside in a different folder than the project. A project 
can reference multiple environments. 


catalog.create_environment_variable (SSISDB 


Database) 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 
Applies to: @sal Server (all supported versions) 


Create an environment variable in the Integration Services catalog. 


Syntax 


catalog.create_environment_variable [ @folder_name = ] folder_name 
» [ @environment_name = ] environment_name 
» [ @variable_name = ] variable_name 
» [ @data_type = ] data_type 
» [ @sensitive = ] sensitive 
» [ @value = ] value 
» [ @description = ] description 


Arguments 


[@folder_name =] fo/der_name 
The name of the folder that contains the environment. The fo/der_name is nvarchar(128). 


[@environment_name =] environment_name 


The name of the environment. The environment_name is nvarchar(128). 


[@variable_name =] variable_name 


The name of the environment variable. The variable_name is nvarchar(128). 


[@data_type =] data_type 

The data type of the variable. Supported environment variable data types include Boolean, Byte, DateTime, 
Double, Int16, Int32, Int64, Single, String, UInt32, and UInt64. Unsupported environment variable data 
types include Char, DBNull, Object, and Sbyte. The data type of the data_type parameter is nvarchar(128). 


[@sensitive =] sensitive 

Indicates whether the variable contains a sensitive value or not. Use a value of 1 to indicate that the value of 
the environment variable is sensitive or a value of @ to indicate that it is not. A sensitive value is encrypted 
when it is stored. A value that is not sensitive is stored in plaintext.Sensitive is bit. 


[@value =] va/ue 
The value of the environment variable. The va/ue is sql_variant. 


[@description =] description 


The description of the environment variable. The va/ue is nvarchar(1024). 


Return Code Value 


0 (success) 


Result Sets 


None 


Permissions 

This stored procedure requires one of the following permissions: 
e READ and MODIFY permissions on the environment 

e Membership to the ssis_admin database role 


e Membership to the sysadmin server role 


Errors and Warnings 

The following list describes some conditions that may raise an error or warning: 

e The folder name, environment name, or environment variable name is not valid 
e The variable name already exists in the environment 


e The user does not have the appropriate permissions 


Remarks 


An environment variable can be used to efficiently assign a value to a project parameter or package parameter 
for use in the execution of a package. Environment variables enable the organization of parameter values. 


Variable names must be unique within an environment. 


The stored procedure validates the data type of the variable to make sure it is supported by the Integration 


Services catalog. 





TIP 
Consider using the Int16 data type in Integration Services instead of the unsupported Sbyte data type. 





The value passed to this stored procedure with the va/ve parameter is converted from an Integration Services 
data type to a SQL Server data type according to the following table: 


INTEGRATION SERVICES DATA TYPE SQL SERVER DATA TYPE 

Boolean bit 

Byte binary, varbinary 

DateTime datetime, datetime2, datetimeoffset, smalldatetime 

Double Exact numeric: decimal, numeric; Approximate numeric: 
float, real 

Int16 smallint 

Int32 int 


Int64 bigint 


INTEGRATION SERVICES DATA TYPE 


Single 


String 


UInt32 


UInt64 


SQL SERVER DATA TYPE 


Exact numeric: decimal, numeric; Approximate numeric: 
float, real 


varchar, nvarchar, char 


int (int is the closest available mapping to Uint32.) 


bigint (int is the closest available mapping to Uint64.) 


catalog.create_execution (SSISDB Database) 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 
Applies to: @sal Server (all supported versions) 
Creates an instance of execution in the Integration Services catalog. 


This stored procedure uses the default server logging level. 


Syntax 


catalog.create_execution [ @folder_name = ] folder_name 
» L @project_name = ] project_name 

» L @package_name = ] package_name 

» L @reference_id = ] reference_id ] 

» L @use32bitruntime = ] use32bitruntime ] 

» [ @runinscaleout = ] runinscaleout ] 


[oe le le 


» [ @useanyworker = ] useanyworker ] 
» L @execution_id = ] execution_id OUTPUT 


Arguments 


[@folder_name =] fo/der_name 
The name of the folder that contains the package that is to be executed. The fo/der_name is nvarchar(128). 


[@project_name =] project_name 
The name of the project that contains the package that is to be executed. The project_name is nvarchar(128). 


[@package_name =] package_name 
The name of the package that is to be executed. The package_name is nvarchar(260). 


[@reference_id =] reference_id 
A unique identifier for an environment reference. This parameter is optional. The reference_idis bigint. 


[@use32bitruntime =] use32bitruntime 

Indicates if the 32-bit runtime should be used to run the package on a 64-bit operating system. Use the value of 
1 to execute the package with the 32-bit runtime when running on a 64-bit operating system. Use the value of 0 
to execute the package with the 64-bit runtime when running on a 64-bit operating system. This parameter is 
optional. The Use32bitruntime is bit. 


[@runinscaleout =] runinscaleout 

Indicate whether the execution is in Scale Out. Use the value of 1 to execute the package in Scale Out. Use the 
value of 0 to execute the package without Scale Out. This parameter is optional. If not specified, its value is set to 
DEFAULT_EXECUTION_MODE in [SSISDB].[catalog].[catalog_properties]. The runinsca/eout is bit. 


[@useanyworker =] useanyworker 
Indicate whether any Scale Out Worker is allowed to do the execution. 


e Use the value of 1 to execute the package with any Scale Out Worker. When you set @useanyworker to 
true, any worker whose maximum task count (as specified in the worker configuration file) is not yet 
reached is available to run the package. For info about the worker configuration file, see Integration 


Services (SSIS) Scale Out Worker. 


e Use the value of 0 to indicate that not all Scale Out Workers are allowed to execute the package. When 
you set @useanyworker to false, you have to specify the workers that are allowed to run the package by 
using Scale Out Manager or by calling the stored procedure [catalog]. [add_execution_worker] . If you 
specify a worker that's already running another package, the worker finishes running the current package 
before it requests another execution. 


This parameter is optional. If not specified, its value is set to 1. The useanyworker is bit. 


[@execution_id =] execution_id 


Returns the unique identifier for an instance of execution. The execution_id'is bigint. 


Remarks 


An execution is used to specify the parameter values that are a package uses during a single instance of package 
execution. 


If an environment reference is specified with the reference_id parameter, the stored procedure populates the 
project and package parameters with literal values or referenced values from the corresponding environment 
variables. If environment reference is specified, default parameter values are used during package execution. To 
determine exactly which values are used for a particular instance of execution, use the execution_id output 
parameter value from this stored procedure and query the execution_parameter_values view. 


Only packages that are marked as entry point packages can be specified in an execution. If a package that is not 
an entry point is specified, the execution fails. 


Example 


The following example calls catalog.create_execution to create an instance of execution for the Child1.dtsx 
package, which is not in Scale Out. Integration Services Project1 contains the package. The example calls 
catalog.set_execution_parameter_value to set values for the Parameter1, Parameter2, and LOGGING_LEVEL 
parameters. The example calls catalog.start_execution to start an instance of execution. 


Declare @execution_id bigint 

EXEC [SSISDB].[catalog].[create_execution] @package_name=N'Child1.dtsx', @execution_id=@execution_id OUTPUT, 
@folder_name=N'TestDeply4', @project_name=N'Integration Services Project1', @use32bitruntime=False, 
@reference_id=Null 

Select @execution_id 

DECLARE @var@ sql_variant = N'Child1.dtsx' 

EXEC [SSISDB].[catalog].[set_execution_parameter_value] @execution_id, @object_type=20, 
@parameter_name=N'Parameter1', @parameter_value=@vare 
DECLARE @vari1 sql_variant = N'Child2.dtsx' 

EXEC [SSISDB].[catalog].[set_execution_parameter_value] @execution_id, @object_type=20, 
@parameter_name=N'Parameter2', @parameter_value=@var1 
DECLARE @var2 smallint = 1 

EXEC [SSISDB].[catalog].[set_execution_parameter_value] @execution_id, @object_type=50, 
@parameter_name=N'LOGGING_LEVEL', @parameter_value=@var2 

EXEC [SSISDB].[catalog].[start_execution] @execution_id 

GO 








Return Code Value 


0 (success) 


Result Sets 


None 


Permissions 


This stored procedure requires one of the following permissions: 


e READ and EXECUTE permissions on the project and, if applicable, READ permissions on the referenced 
environment 


e Membership to the ssis_admin database role 

e Membership to the sysadmin server role 

If @runinscaleout is 1, the stored procedure requires one of the following permissions: 
e Membership to the ssis_admin database role 

e Membership to the ssis_cluster_executor database role 


e Membership to the sysadmin server role 


Errors and Warnings 


The following list describes some conditions that can raise an error or warning: 
e The package does not exist. 

e The user does not have the appropriate permissions. 

e The environment reference, reference_id, is not valid. 

@ The package that is specified is not an entry point package. 


e The data type of the referenced environment variable is different from the data type of the project or 
package parameter. 


e The project or package contains parameters that require values, but no values have been assigned. 


e The referenced environment variables cannot be found in the environment that the environment 
reference, reference_id, specifies. 


See Also 


catalog.start_execution (SSISDB Database) 
catalog.set_execution_parameter_value (SSISDB Database) 
catalog.add_execution_worker (SSISDB Database) 


catalog.create_execution_dump 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 
Applies to: @ sal Server (all supported versions) 


Causes a running package to pause and create a dump file. The file is stored in the <drive>:\Program 
Files\Microsoft SQL Server\130\Shared\ErrorDumps folder. 


Syntax 


catalog.create_execution_dump [ @execution_id = ] execution_id 


Arguments 


[ @execution_id = ] execution_id 
The execution ID for the running package. The execution_idis bigint. 


Example 


In the following example, the running package with an execution ID of 88 is prompted to create a dump file. 


EXEC create_execution_dump @execution_id = 88 


Return Codes 


O (success) 


When the stored procedure fails, it throws an error. 


Result Set 


None 


Permissions 


This stored procedure requires users to be members of the ssis_admin database role. 


Errors and Warnings 

The following list describes conditions that cause the stored procedure to fail. 
e Aninvalid execution ID is specified. 

e The package has already completed. 


e@ The package is currently creating a dump file. 


See Also 


Generating Dump Files for Package Execution 


catalog.create_folder (SSISDB Database) 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 
Applies to: @ sal Server (all supported versions) 


Creates a folder in the Integration Services catalog. 


Syntax 


catalog.create_folder [ @folder_name = ] folder_name, [ @folder_id = ] folder_id OUTPUT 


Arguments 


[@folder_name =] fo/der_name 
The name of the new folder. The fo/der_name is nvarchar(128). 


[@folder_name =] folder_id 
The unique identifier (ID) of the folder. The fo/der_id is bigint. 


Return Code Value 


The folder identifier is returned. 


Result Sets 


None 


Permissions 
This stored procedure requires one of the following permissions: 
e Membership to the ssis_admin database role 


e Membership to the sysadmin server role 


Errors and Warnings 


If a folder with the same name already exists, the stored procedure returns an error . 


catalog.delete_customized_logging_level 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Deletes an existing customized logging level. For more info about customized logging levels, see Integration 
Services (SSIS) Logging. 


Syntax 


catalog.delete_customized_logging level [ @level_name = ] level_name 


Arguments 


[ @level_name = ] /eve/_name 
The name of the existing customized logging level to delete. 


The /evel_ name is nvarchar(128). 
Remarks 


Return Codes 


0 (success) 


When the stored procedure fails, it throws an error. 


Result Set 


None 


Permissions 
This stored procedure requires one of the following permissions: 
e Membership in the ssis_admin database role 


e Membership in the sysadmin server role 


Errors and Warnings 
The following list describes conditions that cause the stored procedure to fail. 


e The user does not have the required permissions. 


catalog.delete_environment (SSISDB Database) 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 
Applies to: @sal Server (all supported versions) 


Deletes an environment from a folder in the Integration Services catalog. 


Syntax 


catalog.delete_environment [ @folder_name = ] folder_name , [ @environment_name = ] environment_name 


Arguments 


[ @folder_name = ] folder_name 
The name of the folder that contains the environment. The fo/der_name is nvarchar(128). 


[ @environment_name = ] environment_name 
The name of the environment that is to be deleted. The environment_name is nvarchar(128). 


Return Code Value 


O (success) 


Result Sets 


None 


Permissions 

This stored procedure requires one of the following permissions: 
e READ and MODIFY permissions on the environment 

e Membership to the ssis_admin database role 


e Membership to the sysadmin server role 


Errors and Warnings 
The following list describes some conditions that may raise an error or warning: 
e The specified environment does not exist 


e The user does not have the appropriate permissions 


catalog.delete_environment_reference (SSISDB 


Dyir-lere\-) 
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Applies to: Q sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 
Applies to: Q sal Server (all supported versions) 


Deletes an environment reference from a project in the Integration Services catalog. 


Syntax 


catalog.delete_environment_reference [ @reference_id = ] reference_id 


Arguments 


[ @reference_id = ] reference_id 
The unique identifier of the environment reference. The reference_idis bigint. 


Return Code Value 


O (success) 


Result Sets 


None 


Permissions 

This stored procedure requires one of the following permissions: 
e MODIFY permission on the project 

e Membership to the ssis_admin database role 


e Membership to the sysadmin server role 


Errors and Warnings 
The following list describes some conditions that may raise an error or warning: 
e The environment reference identifier is not valid 


e The user does not have the appropriate permissions 


catalog.delete_environment_variable (SSISDB 


Dyeir-leye\-) 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 
Applies to: @ sal Server (all supported versions) 


Deletes an environment variable from an environment in the Integration Services catalog. 


Syntax 


catalog.delete_environment_variable [ @folder_name = ] folder_name 
» [ @environment_name = ] environment_name 
» [ @variable_name = ] variable_name 


Arguments 


[ @folder_name = ] folder_name 
The name of the folder that contains the environment. The fo/der_name is nvarchar(128). 


[ @environment_name = ] environment_name 


The name of the environment that contains the variable. The environment_name is nvarchar(128). 


[ @variable_name = ] variable_name 
The name of the variable that is to be deleted. The variab/e_name is nvarchar(128). 


Return Code Value 


0 (success) 


Result Sets 


None 


Permissions 

This stored procedure requires one of the following permissions: 
e READ and MODIFY permissions on the environment 

e Membership to the ssis_admin database role 


e Membership to the sysadmin server role 


Errors and Warnings 
The following list describes some conditions that may raise an error or warning: 
e@ The environment name is not valid 


e The environment variable does not exist 


catalog.delete_folder (SSISDB Database) 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 
Applies to: @ sal Server (all supported versions) 


Deletes a folder from the Integration Services catalog. 


Syntax 


catalog.delete_folder [ @folder_name = ] folder_name 


Arguments 


[ @folder_name = ] folder_name 
The name of the folder that is to be deleted. The fo/der_name is nvarchar(128). 


Return Code Value 


None 


Result Sets 


None 


Permissions 
This stored procedure requires one of the following permissions: 
e Membership to the ssis_admin database role 


e Membership to the sysadmin server role 


Errors and Warnings 


Returns a message to confirm the deletion of the folder. 
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Applies to: Q sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 
Applies to: @sal Server (all supported versions) 


Deletes an existing project from a folder in the Integration Services catalog. 


Syntax 


catalog.delete_project [ @folder_name = ] folder_name , [ @project_name = ] project_name 


Arguments 


[ @folder_name = ] folder_name 
The name of the folder that contains the project. fo/der_name is nvarchar(128). 


[ @project_name = ] project_name 
The name of the project that is to be deleted. project_name is nvarchar(128). 


Return Code Value 


O (success) 


Result Sets 


None 


Permissions 

This stored procedure requires one of the following permissions: 
e READ and MODIFY permissions on the project 

e Membership to the ssis_admin database role 


e Membership to the sysadmin server role 


Errors and Warnings 


The following list describes some conditions that may cause the delete_project stored procedure to raise an 
error: 


e The project does not exist 
e The folder does not exist 


e The user does not have the appropriate permissions 


Remarks 


All objects and environment references of the corresponding project are deleted along with the project. 
However, the versions of the project and the relevant operations records are retained until the next time the 


operation cleanup job runs. 


catalog.deny_permission (SSISDB Database) 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 
Applies to: @sal Server (all supported versions) 


Denies a permission on a securable object in the Integration Services catalog. 


Syntax 


catalog.deny_permission [ @object_type = ] object_type 
» [ @object_id = ] object_id 
» [ @principal_id = ] principal_id 
» [ @permission_type = ] permission_type 


Arguments 


[ @object_type = ] object_type 
The type of securable object. Securable objects types include folder ( 1 ), project ( 2 ), environment ( 3 ), and 
operation ( 4 ).The object_type is smallint. 


[ @object_id = ] object_id 
The unique identifier (ID) or primary key of the securable object. The object_idis bigint. 


[ @principal_id = ] principal_id 
The ID of the principal who is to be denied. The principal_idis int. 


[ @permission_type = ] permission_type 


The type of permission that is to be denied. The permission_type is smallint. 


Return Code Values 


0 (success) 

1 (object_class is not valid) 
2 (object_id does not exist) 
3 (principal does not exist) 
A (permission is not valid) 


5 (other error) 


Result Sets 


None 


Permissions 


This stored procedure requires one of the following permissions: 


e@ MANAGE_PERMISSIONS permission on the object 


e Membership to the ssis_admin database role 


e Membership to the sysadmin server role 


Remarks 


This stored procedure allows you to deny the permission types described in the following table: 


PERMISSION_TYPE VALUE 


100 


101 


102 


103 


104 


PERMISSION NAME 


READ 


MODIFY 


EXECUTE 


MANAGE_PERMISSIONS 


CREATE_OBJECTS 


READ_OBJECTS 


MODIFY_OBJECTS 


EXECUTE_OBJECTS 


MANAGE_OBJECT_PERMISS 
IONS 


Errors and Warnings 


PERMISSION DESCRIPTION 


Allows the principal to read 
information that is 
considered part of the 
object, such as properties. It 
does not allow the principal 
to enumerate or read the 
contents of other objects 
contained within the object. 


Allows the principal to 
modify information that is 
considered part of the 
object, such as properties. It 
does not allow the principal 
to modify other objects 
contained within the object. 


Allows the principal to 
execute all packages in the 
project. 


Allows the principal to 
assign permissions to the 
objects. 


Allows the principal to 
create objects in the folder. 


Allows the principal to read 
all objects in the folder. 


Allows the principal to 
modify all objects in the 
folder. 


Allows the principal to 
execute all packages from 
all projects in the folder. 


Allows the principal to 
manage permissions on all 
objects in the folder. 


The following list describes some conditions that may raise an error or warning: 


APPLICABLE OBJECT TYPES 


Folder, Project, 
Environment, Operation 


Folder, Project, 
Environment, Operation 


Project 


Folder, Project, 
Environment, Operation 


Folder 


Folder 


Folder 


Folder 


Folder 


e If permission_type is specified, the procedure denies the specified permission that is explicitly assigned to 


the specified principal for the specified object. Even if there are no such instances, the procedure still 
returns a success code value ( @ ). 


e If permission_type is omitted, the procedure denies all permissions for the specified principal to the 
specified object. 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 
Applies to: @ sal Server (all supported versions) 


Deploys one or more packages to a folder in the Integration Services catalog or updates an existing package 
that has been deployed previously. 


Syntax 


catalog.deploy_packages [ @folder_name = ] folder_name 
» [ @project_name = ] project_name 
» [ @packages_table = ] packages_table 
[, [ @operation_id OUTPUT = ] operation_id OUTPUT] 


Arguments 


[ @folder_name = ] fo/der_name 
The name of the folder. The fo/der_name is nvarchar(128). 


[ @project_name = ] project_name 
The name of the project in the folder. The project_name is nvarchar(128). 


[ @packages_table = ] packages_table 
The binary contents of Integration Services package (.dtsx) file(s). The packages_table is [catalog]. 
[Package_Table_Type] 


[ @operation_id = ] operation_id 


Returns the unique identifier for the deployment operation. The operation_id is bigint. 


Return Code Value 


0 (success) 


Result Sets 


None 


Permissions 
This stored procedure requires one of the following permissions: 


e@ CREATE_OBJECTS permissions on the project or MODIFY permissions on the package to update a 
package. 


e Membership to the ssis_admin database role 


e Membership to the sysadmin server role 


Errors and Warnings 


The following list describes some conditions that may cause this stored procedure to raise an error: 


e Aparameter refers to an object that does not exist, a parameter tries to create an object that already 


exists, or a parameter is invalid in some other way. 


e The user does not have sufficient permissions 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 
Applies to: @sal Server (all supported versions) 
Deploys a project to a folder in the Integration Services catalog or updates an existing project that has been 


deployed previously. 


Syntax 


catalog.deploy_project [@folder_name =] folder_name 
» [ @project_name = ] project_name 
» L @project_stream = ] projectstream 
[ , [ @operation_id = ] operation_id OUTPUT ] 


Arguments 


[@folder_name =] fo/der_name 
The name of the folder where the project is deployed. The fo/der_name is nvarchar(128). 


[@project_name =] project_name 
The name of the new or updated project in the folder. The project_name is nvarchar(128). 


[@projectstream =] projectstream 
The binary contents of an Integration Services project deployment file (.ispac extension). 


You can use a SELECT statement with the OPENROWSET function and the BULK rowset provider to retrieve the 
binary contents of the file. For an example, see Deploy Integration Services (SSIS) Projects and Packages. For 
more information about OPENROWSET, see OPENROWSET (Transact-SQL). 


The projectstream is varbinary(MAX) 
[@operation_id =] operation_id 


Returns the unique identifier for the deployment operation. The operation_idis bigint. 


Return Code Value 


O (success) 


Result Sets 


None 


Permissions 


This stored procedure requires one of the following permissions: 


e@ CREATE_OBJECTS permissions on the folder to deploy a new project or MODIFY permissions on the 
project to update a project 


e@ Membership to the ssis_admin database role 


e Membership to the sysadmin server role 


Errors and Warnings 


The following list describes some conditions that may cause this stored procedure to raise an error: 


e A parameter refers to an object that does not exist, a parameter tries to create an object that already 


exists, or a parameter is invalid in some other way 


e The value of the parameter @project_name does not match the name of the project in the deployment 
file 


e@ The user does not have sufficient permissions 


Remarks 


During a project deployment or update, the stored procedure does not check the protection level of individual 


packages in the project. 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Disable a Scale Out Worker for Scale Out Master working with this Integration Services catalog. 


Syntax 


catalog.disable_ worker_agent [ @WorkerAgentId = ] WorkerAgentId 


Arguments 


[@WorkerAgentld =] WorkerAgentid The worker agent ID of Scale Out Worker. The WorkerAgentid is 
uniqueidentifier. 


Example 


This example disables the Scale Out Worker on MachineA. 


SELECT WorkerAgentId, MachineName FROM [catalog].[worker_agents] 
GO 

-- Result: -- 

-- WorkerAgentId MachineName -- 

-- 6583054A-E915-4C2A-80E4-C765E79EF61D MachineA == 


EXEC [catalog].[disable_worker_agent] '6583054A-E915-4C2A-80E4-C765E79EF61D' 
GO 


Return Code Value 


0 (success) 


Result Sets 


None 


Permissions 
This stored procedure requires one of the following permissions: 
e Membership to the ssis_admin database role 


e Membership to the sysadmin server role 


Errors and Warnings 


If the worker agent ID is not valid, the stored procedure returns an error. 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Enable a Scale Out Worker for Scale Out Master working with this Integration Services catalog. 


Syntax 


catalog.enable_worker_agent [ @WorkerAgentId = ] WorkerAgentId 


Arguments 


[@WorkerAgentld =] WorkerAgentid The worker agent ID of Scale Out Worker. The WorkerAgentid is 
uniqueidentifier. 


Example 


This example enables the Scale Out Worker on MachineA. 


SELECT WorkerAgentId, MachineName FROM [catalog].[worker_agents] 
GO 

-- Result: -- 

-- WorkerAgentId MachineName -- 

-- 6583054A-E915-4C2A-80E4-C765E79EF61D MachineA == 


EXEC [catalog].[enable_worker_agent] '6583054A-E915-4C2A-80E4-C765E79EF61D' 
GO 


Return Code Value 


0 (success) 


Result Sets 


None 


Permissions 
This stored procedure requires one of the following permissions: 
e Membership to the ssis_admin database role 


e Membership to the sysadmin server role 


Errors and Warnings 


If the worker agent ID is not valid, the stored procedure returns an error. 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 
Applies to: @ sal Server (all supported versions) 


Resolves and retrieves the default parameter values from a project and corresponding packages in the 
Integration Services catalog. 


Syntax 


catalog.get_parameter_values [ @folder_name = ] folder_name 
» L @project_name = ] project_name 
» L @package_name = ] package_name 
[ , [ @reference_id = ] reference_id ] 


Arguments 


[ @folder_name = ] folder_name 
The name of the folder that contains the project. The fo/der_name is nvarchar(128). 


[ @project_name = ] project_name 
The name of the project where the parameters resides. The project_name is nvarchar(128). 


[ @package_name = ] package_name 
The name of the package. Specify the package name to retrieve all project parameters and the parameters from 
a specific package. The package_name is nvarchar(260). 


[ @reference_id = ] reference_id 
The unique identifier of an environment reference. This parameter is optional. The reference_id is bigint. 


Return Code Value 


0 (success) 


Result Sets 


Returns a table that has the following format: 


COLUMN NAME DATA TYPE DESCRIPTION 


object_type smallint The type of parameter. The value is 
2@ for a project parameter and the 
value is 3@ for a package parameter. 


parameter_data_type nvarchar(128) The data type of the parameter. 


parameter_name sysname The name of the parameter. 


COLUMN NAME DATA TYPE DESCRIPTION 
parameter_value sql_variant The value of the parameter. 


sensitive bit When the value is 1 , the parameter 
value is sensitive. When the value is 
@ , the parameter value is not 
sensitive. 


required bit When the value is 1 , the parameter 
value is required in order to start the 
execution. When the value is @ , the 


parameter value is not required to 
start the execution. 


value_set bit When the value is 1 , the parameter 
value has been assigned. When the 
value is @ , the parameter value has 
not been assigned. 





NOTE 


Literal values are displayed in plaintext. NULL is displayed in place of sensitive values. 





Permissions 

This stored procedure requires one of the following permissions: 

e READ permissions on the project and, if applicable, READ permission on the referenced environment 
e Membership to the ssis_admin database role 


e Membership to the sysadmin server role 


Errors and Warnings 


The following list describes some conditions that may raise an error or warning: 
e@ The package cannot be found in the specified folder or project 
e The user does not have the appropriate permissions 


e The specified environment reference does not exist 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 
Applies to: @sal Server (all supported versions) 


Retrieves the binary stream of a project that has been deployed to the Integration Services server. 


Syntax 


catalog.get_project [ @folder_name = ] folder_name , [ @project_name = ] project_name 


Arguments 


[ @folder_name = ] folder_name 
The name of the folder that contains the project. fo/der_name is nvarchar(128). 


[ @project_name = ] project_name 


The name of the project. project_name is nvarchar(128). 


Return Code Value 


O (success) 


Result Sets 


The binary stream of the project is returned as varbinary(MAX). No results are returned if the folder or project 
is not found. 


Permissions 

This stored procedure requires one of the following permissions: 
e READ permissions on the project 

e Membership to the ssis_admin database role 


e Membership to the sysadmin server role 


Errors and Warnings 

The following list describes some conditions that may cause the get_project stored procedure to raise an error: 
e The project does not exist 

e The folder does not exist 


e@ The user does not have the appropriate permissions 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 
Applies to: @sal Server (all supported versions) 


Grants a permission on a securable object in the Integration Services catalog. 


Syntax 


catalog.grant_permission [ @object_type = ] object_type 
» [ @object_id = ] object_id 
» [ @principal_id = ] principal_id 
» [ @permission_type = ] permission_type 


Arguments 


[ @object_type = ] object_type 
The type of securable object. Securable objects types include folder ( 1 ), project ( 2 ), environment ( 3 ), and 
operation ( 4 ).The object_type is smallint. 


[ @object_id = ] object_id 
The unique identifier (ID) of the securable object. The object_idis bigint. 


[ @principal_id = ] principal_id 
The ID of the principal to be granted permission. The principal_idis int. 


[ @permission_type = ] permission_type 
The type of permission to be granted. The permission_typeis smallint. 


Return Code Values 


0 (success) 

1 (object_class is invalid) 

2 (object_id does not exist) 
3 (principal does not exist) 
A (permission is invalid) 


5 (other error) 


Result Sets 


None 


Permissions 


This stored procedure requires one of the following permissions: 


e ASSIGN_PERMISSIONS permissions on the object 


e Membership to the ssis_admin database role 


e Membership to the sysadmin server role 


This procedure cannot be called by logins that were authenticated by SQL Server. It cannot be called by the sa 


login. 


Remarks 


This stored procedure allows you to grant the permission types described in the following table: 


PERMISSION_TYPE VALUE 


100 


101 


102 


103 


104 


PERMISSION NAME 


READ 


MODIFY 


EXECUTE 


MANAGE_PERMISSIONS 


CREATE_OBJECTS 


READ_OBJECTS 


MODIFY_OBJECTS 


EXECUTE_OBJECTS 


MANAGE_OBJECT_PERMISS 
IONS 


Errors and Warnings 


PERMISSION DESCRIPTION 


Allows the principal to read 
information that is 
considered part of the 
object, such as properties. It 
does not allow the principal 
to enumerate or read the 
contents of other objects 
contained within the object. 


Allows the principal to 
modify information that is 
considered part of the 
object, such as properties. It 
does not allow the principal 
to modify other objects 
contained within the object. 


Allows the principal to 
execute all packages in the 
project. 


Allows the principal to 
assign permissions to the 
objects. 


Allows the principal to 
create objects in the folder. 


Allows the principal to read 
all objects in the folder. 


Allows the principal to 
modify all objects in the 
folder. 


Allows the principal to 
execute all packages from 
all projects in the folder. 


Allows the principal to 
manage permissions on all 
objects in the folder. 


APPLICABLE OBJECT TYPES 


Folder, Project, 
Environment, Operation 


Folder, Project, 
Environment, Operation 


Project 


Folder, Project, 
Environment, Operation 


Folder 


Folder 


Folder 


Folder 


Folder 


See the Return Code Values section for relevant errors and messages. 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 
Applies to: @ sal Server (all supported versions) 


Moves an environment from one folder to another within the Integration Services catalog. 


Syntax 


catalog.move_environment [ @source_folder = ] source_folder 
» [ @environment_name = ] environment_name 
» [ @destination_folder = ] destination_folder 


Arguments 


[ @source_folder = ] source_folder 
The name of the source folder, where the environment resides before the move. The source_folder is 
nvarchar(128). 


[ @environment_name = ] environment_name 


The name of the environment that is to be moved. The environment_name is nvarchar(128). 


[ @destination_folder = ] destination_folder 
The name of the destination folder, where the environment resides after the move. The destination_folder is 
nvarchar(128). 


Return Code Value 


0 (success) 


Result Sets 


None 


Permissions 

This stored procedure requires one of the following permissions: 
e READ and MODIFY permissions on the environment 

e Membership to the ssis_admin database role 


e Membership to the sysadmin server role 


Errors and Warnings 
The following list describes some conditions that may raise an error or warning: 
e@ The environment does not exist in the source folder 


e The destination folder already has an environment with the same name 


e The user does not have the appropriate permissions 


Remarks 


Environment references from projects do not follow the environment during the move. Environment references 
must be updated accordingly. This stored procedure will succeed even if environment references are broken by 
moving an environment. Environment references must be updated after this stored procedure completes. 





NOTE 

A project can have relative or absolute environment references. Relative references refer to the environment by name, and 
these references require that the environment reside in the same folder as the project. Absolute references refer to the 
environment by name and folder, and these references refer to environments that reside in a different folder from that of 


the project. 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 
Applies to: @sal Server (all supported versions) 


Moves a project from one folder to another within the Integration Services catalog. 


Syntax 


catalog.move_project [ @source_folder = ] source_folder 
» [ @project_name = ] project_name 
» [ @destination_folder = ] destination_folder 


Arguments 


[ @source_folder = ] source_folder 
The name of the source folder, where the project resides before the move. The source_fo/der is nvarchar(128). 


[ @project_name = ] project_name 
The name of the project that is to be moved. The project_name is nvarchar(128). 


[ @destination_folder = ] destination_folder 
The name of the destionation folder, where the project resides after the move. The destination_folder is 
nvarchar(128). 


Return Code Value 


O (success) 


Result Sets 


None 


Permissions 


This stored procedure requires one of the following permissions: 


e READ and MODIFY permissions on the project that you want to move and CREATE_OBJECTS permission 
on the destination folder 


e Membership to the ssis_admin database role 


e Membership to the sysadmin server role 


Errors and Warnings 
The following list describes some conditions that may cause this stored procedure to raise an error: 
e@ The project does not exist 


e The source folder does not exist 


e The destination folder does not exist or the destination folder already contains a project with the same 


name 


e The user does not have the appropriate permissions 


Remarks 


When a project is moved from a source folder to a destination folder, the project in the source folder and 
corresponding environment references are deleted. In the destination folder, an identical project and 
environment references are created. Relative environment references will resolve to a different folder after the 


move. Absolute references will resolve to the same folder after the move. 


NOTE 
A project can have relative or absolute environment references. Relative references refer to the environment by name, and 
these references require that the environment reside in the same folder as the project. Absolute references refer to the 


environment by name and folder, and these references refer to environments that reside in a different folder from that of 


the project. 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 
Applies to: @ sal Server (all supported versions) 


Removes a data tap from a component output that is in an execution. The unique identifier for the data tap is 
associated with an instance of the execution. 


Syntax 


catalog.remove_data_tap [ @data_tap_id = ] data_tap_id 


Arguments 

[ @data_tap_id = ] data_tap_id 

The unique identifier for the data tap that is created by using the catalog.add_data_tap stored procedure. The 
data_tap_idis bigint. 


Remarks 


e When a package contains more than one data flow tasks that have the same name, the data tap is added 
to the first data flow task with the given name. 


e To remove data taps, the instance of the execution must be in the created state (a value of 1 in the status 


column of the catalog.operations (SSISDB Database)view) . 


Return Codes 


0 (success) 


When the stored procedure fails, it throws an error. 


Result Set 


None 


Permissions 

This stored procedure requires one of the following permissions: 
e MODIFY permissions on the instance of execution 

e Membership to the ssis_admin database role 


e Membership to the sysadmin server role 


Errors and Warnings 


The following list describes conditions that cause the stored procedure to fail. 


e The user does not have MODIFY permissions. 


See Also 


catalog.add_data_tap 
catalog.add_data_tap_by_guid 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 
Renames an existing customized logging level. For more info about customized logging levels, see Integration 


Services (SSIS) Logging. 


Syntax 


catalog.rename_customized_logging level [ @old_name = ] old_name 
» [ @new_name = ] new_name 


Arguments 


[ @old_name = ] o/d_name 
The name of the existing customized logging level to rename. 


The o/d_name is nvarchar(128). 


[ @new_name = ] new_name 
The new name for the specified customized logging level. 


The new_name is nvarchar(128). 
Remarks 


Return Codes 


O (success) 


When the stored procedure fails, it throws an error. 


Result Set 


None 


Permissions 
This stored procedure requires one of the following permissions: 
e@ Membership in the ssis_admin database role 


e Membership in the sysadmin server role 


Errors and Warnings 
The following list describes conditions that cause the stored procedure to fail. 


e The user does not have the required permissions. 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 
Applies to: @ sal Server (all supported versions) 


Renames an environment in the Integration Services catalog. 


Syntax 


catalog.rename_environment [ @folder_name = ] folder_name 
» L @environment_name = ] environment_name 
» [ @new_environment_name= ] new_environment_name 


Arguments 


[ @folder_name = ] fo/der_name 
The name of the folder that contains the environment. The fo/der_name is nvarchar(128). 


[ @environment_name = ] environment_name 


The original name of the environment. The environment_name is nvarchar(128). 


[ @new_environment_name = ] new_environment_name 


The new name of the environment. The new_environment_name is nvarchar(128). 


Return Code Value 


O (success) 


Result Sets 


None 


Permissions 

This stored procedure requires one of the following permissions: 
e MODIFY permissions on the environment 

e Membership to the ssis_admin database role 


e Membership to the sysadmin server role 


Errors and Warnings 
The following list describes some conditions that may raise an error or warning: 
e The original environment name is not valid 


e The new name has already been used on an existing environment 


Remarks 


Environment references from projects are not automatically updated when you rename the environment. 
Environment references must be updated accordingly. This stored procedure will succeed even if environment 
references are broken by changing the environment name. Environment references must be updated after this 


stored procedure completes. 





NOTE 
When an environment reference is not valid, validation and execution of the corresponding packages that use those 


references will fail. 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 
Applies to: @sal Server (all supported versions) 


Renames a folder in the Integration Services catalog. 


Syntax 


catalog.rename_folder [ @old_name = ] old_name , [ @new_name = ] new_name 


Arguments 


[ @old_name = ] o/d_name 
The original name of the folder. The o/d_name is nvarchar(128). 


[ @new_name = ] new_name 
The new name of the folder. The new_name is nvarchar(128). 


Return Code Value 


None 


Result Sets 


None 


Permissions 
This stored procedure requires one of the following permissions: 
e Membership to the ssis_admin database role 


e Membership to the sysadmin server role 


Errors and Warnings 
The following list describes some conditions that may raise an error or warning: 
e The original folder name is not valid 


e The new name has already been used on an existing folder 
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Applies to: Q@ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 
Applies to: @ sal Server (all supported versions) 


Restores a project in the Integration Services catalog to a previous version. 


Syntax 


catalog.restore_project [ @folder_name = ] folder_name 
» [ @project_name = ] project _name 
» [ @object_version_lsn = ] object_version_lsn 


Arguments 


[ @folder_name = ] folder_name 
The name of the folder that contains the project. The fo/der_name is nvarchar(128). 


[ @project name = ] project_name 
The name of the project. The project_name is nvarchar(128). 


[ @object_version_Isn = ] object_version_Ilsn 
The version of the project. The object_version_/sn is bigint. 


Return Code Value 


O (success) 


Result Sets 


Project details are returned as varbinary(MAX) as part of the result set if the project_name is found. 


NO RESULT SET is returned if the project cannot be restored to the specified folder. 


Permissions 

This stored procedure requires one of the following permissions: 
e READ and MODIFY permissions on the project 

e Membership to the ssis_admin database role 


e Membership to the sysadmin server role 


Errors and Warnings 
The following list describes some conditions that may raise an error or warning: 


e The project version does not exist or does not match the project name 


e The project does not exist 


e The user does not have the appropriate permissions 


Remarks 

When a project is restored, all parameters are assigned default values and all environment references remain 
unchanged. The maximum number of project versions that are retained in the catalog is determined by the 
catalog property MAX_VERSIONS_PER_PROJECT, as shown in the catalog_property view. 





WARNING 


Environment references may no longer be valid after a project has been restored. 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 
Applies to: @ sal Server (all supported versions) 


Revokes a permission on a securable object in the Integration Services catalog. 


Syntax 


catalog.revoke_permission [ @object_type = ] object_type 
» [ @object_id = ] object_id 
» [ @principal_id = ] principal_id 
» [ @permission_type = ] permission_type 


Arguments 


[ @object_type = ] object_type 
The type of securable object. Securable objects types include folder ( 1 ), project ( 2 ), environment ( 3 ), and 
operation ( 4 ).The object_type is smallint. 


[ @object_id = ] object_id 
The unique identitifier (ID) of the securable object. The object_id is bigint. 


[ @principal_id = ] principal_id 
The ID of the principal to be revoked permission. The principal_idis int. 


[ @permission_type = ] permission_type 
The type of permission. The permission_type is smallint. 


Return Code Values 


0 (success) 

1 (object_class is not valid) 
2 (object_id does not exist) 
3 (principal does not exist) 
A (permission is not valid) 


5 (other error) 


Result Sets 


None 


Permissions 


This stored procedure requires one of the following permissions: 


e ASSIGN_PERMISSIONS permissions on the object 


e Membership to the ssis_admin database role 


e Membership to the sysadmin server role 


Remarks 


If permission_type is specified, the stored procedure removes the permission that is explicitly assigned to the 


principal for the object. Even if there are no such instances, the procedure returns a success code value ( @ ). If 


permission_type is omitted, the stored procedure removes all permissions of the principal to the object. 








NOTE 


specified permission. 


The principal may still have the specified permission on the object if the principal is a member of a role that has the 


This stored procedure allows you to revoke the permission types described in the following table: 


PERMISSION_TYPE VALUE 


100 


101 


102 


PERMISSION NAME 


READ 


MODIFY 


EXECUTE 


MANAGE_PERMISSIONS 


CREATE_OBJECTS 


READ_OBJECTS 


MODIFY_OBJECTS 


PERMISSION DESCRIPTION 


Allows the principal to read 
information that is 
considered part of the 
object, such as properties. It 
does not allow the principal 
to enumerate or read the 
contents of other objects 
contained within the object. 


Allows the principal to 
modify information that is 
considered part of the 
object, such as properties. It 
does not allow the principal 
to modify other objects 
contained within the object. 


Allows the principal to 
execute all packages in the 
project. 


Allows the principal to 
assign permissions to the 
objects. 


Allows the principal to 
create objects in the folder. 


Allows the principal to read 
all objects in the folder. 


Allows the principal to 
modify all objects in the 
folder. 


APPLICABLE OBJECT TYPES 


Folder, Project, 
Environment, Operation 


Folder, Project, 
Environment, Operation 


Project 


Folder, Project, 
Environment, Operation 


Folder 


Folder 


Folder 





PERMISSION_TYPE VALUE 


103 


104 


PERMISSION NAME 


EXECUTE_OBJECTS 


MANAGE_OBJECT_PERMISS 
IONS 


PERMISSION DESCRIPTION 


Allows the principal to 
execute all packages from 
all projects in the folder. 


Allows the principal to 
manage permissions on all 
objects in the folder. 


APPLICABLE OBJECT TYPES 


Folder 


Folder 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Changes the description of an existing customized logging level. For more info about customized logging levels, 
see Integration Services (SSIS) Logging. 


Syntax 


catalog.set_customized_logging level_description [ @level_name = ] level_name 
» [ @level_description = ] level_description 


Arguments 


[ @level_name = ] /eve/_name 


The name of an existing customized logging level. 
The /evel_ name is nvarchar(128). 


[ @level_description = ] /evel_ description 
The new description for the specified customized logging level. 


The /evel_description is nvarchar(1024). 
Remarks 


Return Codes 


O (success) 


When the stored procedure fails, it throws an error. 


Result Set 


None 


Permissions 
This stored procedure requires one of the following permissions: 
e Membership in the ssis_admin database role 


e Membership in the sysadmin server role 


Errors and Warnings 
The following list describes conditions that cause the stored procedure to fail. 


e The user does not have the required permissions. 


catalog.set_customized_logging_level_value 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Changes the statistics or the events logged by an existing customized logging level. For more info about 
customized logging levels, see Integration Services (SSIS) Logging. 


Syntax 


catalog.set_customized_logging level_value [ @level_name = ] level_name 
» L @property_name = ] property_name 
» L @property_value = ] property_value 


Arguments 


[ @level_name = ] /evel_ name 


The name of an existing customized logging level. 
The /evel_ name is nvarchar(128). 


[ @property_name = ] property_name 
The name of the property to change. Valid values are PROFILE and EVENTS. 


The property_nameis nvarchar(128). 


[ @property_value = ] property_value 
The new value for the specified property of the specified customized logging level. 


For a list of valid values for profile and events, see catalog.create_customized_logging_level. 


The property_value is a bigint. 
Remarks 


Return Codes 


0 (success) 


When the stored procedure fails, it throws an error. 


Result Set 


None 


Permissions 
This stored procedure requires one of the following permissions: 
e Membership in the ssis_admin database role 


e Membership in the sysadmin server role 


Errors and Warnings 


The following list describes conditions that cause the stored procedure to fail. 


e The user does not have the required permissions. 


catalog.set_environment_property (SSISDB 
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Applies to: Q sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 
Applies to: @ sal Server (all supported versions) 


Sets the property of an environment in the Integration Services catalog. 


Syntax 


catalog.set_environment_property [ @folder_name = ] folder_name 
» [ @environment_name = ] environment_name 
» [ @property_name = ] property_name 
» [ @property_value = ] property_value 


Arguments 


[ @folder_name = ] fo/der_name 
The name of the folder that contains the environment. The fo/der_name is nvarchar(128). 


[ @environment_name = ] environment_name 
The name of the environment. The environment_name is nvarchar(128). 


[ @property_name = ] property_name 
The name of an environment property. The property_name is nvarchar(128). 


[ @property_value = ] property_value 


The value of the environment property. The property_value is nvarchar(1024). 


Return Code Value 


0 (success) 


Result Sets 


None 


Permissions 

This stored procedure requires one of the following permissions: 
e@ READ and MODIFY permissions on the environment 

e Membership to the ssis_admin database role 


e Membership to the sysadmin server role 


Errors and Warnings 


The following list describes some conditions that may raise an error or warning: 


e The folder name is not valid 
e The property name is not valid 


e The environment name is not valid 


Remarks 


In this release, only the Description property can be set. The property value for the Description property 


cannot exceed 4000 characters. 


catalog.set_environment_reference_type (SSISDB 
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Applies to: Q sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 
Applies to: @sal Server (all supported versions) 


Sets the reference type and environment name associated with an existing environment reference for a project 
in the Integration Services catalog. 


Syntax 


catalog.set_environment_reference_location [ @reference_id = reference_id 
» [ @reference_type = ] reference_type 
[ , [ @environment_folder_name = ] environment_folder_name ] 


Arguments 


[ @reference_id = ] reference_id 
The unique identifier of the environment reference that is to be updated. The reference_idis bigint. 


[ @reference_type = ] reference_type 

Indicates whether the environment can be located in the same folder as the project (relative reference) or ina 
different folder (absolute reference). Use the value rR to indicate a relative reference. Use the value A to 
indicate an absolute reference. The reference_type is char(1). 


[ @environment_folder_name = ] environment_folder_name 
The folder in which the environment is located. This value is required for absolute references. The 
environment. folder_name is nvarchar(128). 


Return Code Value 


O (success) 


Result Sets 


None 


Permissions 

This stored procedure requires one of the following permissions: 

e READ and MODIFY permissions on the project, and READ permission on the environment 
e Membership to the ssis_admin database role 


e Membership to the sysadmin server role 


Errors and Warnings 


The following list describes some conditions that may raise an error or warning: 
@ The folder name, environment name, or reference ID is not valid 
e The user does not appropriate permissions 


e An absolute reference is specified by using the a character in the reference_/ocation parameter, but the 


name of the folder was not specified with the environment_folder_name parameter. 


Remarks 


A project can have relative or absolute environment references. Relative references refer to the environment by 
name and require that it resides in the same folder as the project. Absolute references refer to the environment 
by name and folder, and may refer to environments that reside in a different folder than the project. A project 


can reference multiple environments. 





IMPORTANT 
If a relative reference is specified, the environment_folder_name parameter value is not used, and the environment folder 
name is automatically set to NULL. If an absolute reference is specified, the environment folder name must be provided in 


the environment_folder_name parameter. 











catalog.set_environment_variable_property (SSISDB 
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Applies to: Q sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 
Applies to: @sal Server (all supported versions) 


Sets the property of an environment variable in the Integration Services catalog. 


Syntax 


catalog.set_environment_variable_property [ @folder_name = ] folder_name 
» [ @environment_name = ] environment_name 
» [ @variable_name = ] variable_name 
» [ @property_name = ] property_name 
» L @property_value = ] property_value 


Arguments 


[ @folder_name = ] folder_name 
The name of the folder that contains the environment. The fo/der_name is nvarchar(128). 


[ @environment_name = ] environment_name 


The name of the environment. The environment_name is nvarchar(128). 


[ @variable_name = ] variable_name 


The name of the environment variable. The variable_nameis nvarchar(128). 


[ @property_name = ] property_name 
The name of the environment variable property. The property_name is nvarchar(128). 


[ @property_value = ] property_value 
The value of the environment variable property. The property_va/ue is nvarchar(4000). 


Return Code Value 


0 (success) 


Result Sets 


None 


Permissions 

This stored procedure requires one of the following permissions: 
e READ and MODIFY permissions on the environment 

e Membership to the ssis_admin database role 


e Membership to the sysadmin server role 


Errors and Warnings 

The following list describes some conditions that may raise an error or warning: 
e The folder name is not valid 

e The environment name is not valid 


The environment variable name is not valid 


e The environment variable property name is not valid 


The user does not have the appropriate permissions 


Remarks 


In this release, only the Description property can be set. The property value for the Description property 
cannot exceed 4000 characters. 


catalog.set_environment_variable_protection 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 
Applies to: @ sal Server (all supported versions) 


Sets the sensitivity bit of an environment variable in the Integration Services catalog. 


Syntax 


catalog.set_environment_variable_ protection [ @folder_name = ] folder_name 
» [ @environment_name = ] environment_name 
» [ @variable_name = ] variable_name 
» [ @sensitive = ] sensitive 


Arguments 


[ @folder_name = ] fo/der_name 
The name of the folder that contains the environment. The fo/der_name is nvarchar(128). 


[ @environment_name = ] environment_name 
The name of the environment. The environment_name is nvarchar(128). 


[ @variable_name = ] variable_name 


The name of the environment variable. The variable_name is nvarchar(128). 


[ @sensitive = ] sensitive 

Indicates whether the variable contains a sensitive value or not. Use a value of 1 to indicate that the value of 
the environment variable is sensitive or a value of @ to indicate that it is not. A sensitive value is encrypted 
when it is stored. A value that is not sensitive is stored in plaintext. The sensitive parameter is bit. 


Return Code Value 


0 (success) 


Result Sets 


None 


Permissions 

This stored procedure requires one of the following permissions: 
e@ READ and MODIFY permissions on the environment 

e Membership to the ssis_admin database role 


e Membership to the sysadmin server role 


Errors and Warnings 
The following list describes some conditions that may raise an error or warning: 


e The folder name is not valid 
e The environment name is not valid 
e The environment variable name is not valid 


e The user does not have the appropriate permissions 


catalog.set_environment_variable_value (SSISDB 
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Applies to: Q sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 
Applies to: @ sal Server (all supported versions) 


Sets the value of an environment variable in the Integration Services catalog. 


Syntax 


catalog.set_environment_variable value [ @folder_name = ] folder_name 
» [ @environment_name = ] environment_name 
» [ @variable_name = ] variable _name 
» [ @value = ] value 


Arguments 


[ @folder_name = ] fo/der_name 
The name of the folder that contains the environment. The fo/der_name is nvarchar(128). 


[ @environment_name = ] environment_name 
The name of the environment. The environment_name is nvarchar(128). 


[ @variable name = ] variable_name 
The name of the environment variable. The variable_name is nvarchar(128). 


[ @value = ] va/ue 


The value of the environment variable. The va/ue is sql_variant. 


Return Code Value 


0 (success) 


Result Sets 


None 


Permissions 

This stored procedure requires one of the following permissions: 
e@ READ and MODIFY permissions on the environment 

e Membership to the ssis_admin database role 


e Membership to the sysadmin server role 


Errors and Warnings 


The following list describes some conditions that may raise an error or warning: 


The folder name is not valid 
The environment name is not valid 
The environment variable name is not valid 


The user does not have appropriate permissions 


catalog.set_execution_parameter_value (SSISDB 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 
Applies to: @ sal Server (all supported versions) 
Sets the value of a parameter for an instance of execution in the Integration Services catalog. 


A parameter value cannot be changed after an instance of execution has started. 


Syntax 


catalog.set_execution_parameter_value [ @execution_id = execution_id 
» [ @object_type = ] object_type 
» [ @parameter_name = ] parameter_name 
» [ @parameter_value = ] parameter_value 


Arguments 


[ @execution_id = ] execution_id 
The unique identifier for the instance of execution. The execution_id is bigint. 


[ @object_type = ] object_type 
The type of parameter. 


For the following parameters, set object_type to 50 

e LOGGING_LEVEL 

e CUSTOMIZED_LOGGING_LEVEL 

e DUMP_ON_ERROR 

e DUMP_ON_EVENT 

e@ DUMP_EVENT_CODE 

e CALLER_INFO 

e SYNCHRONIZED 

Use the value 20 to indicate a project parameter or the value 3e to indicate a package parameter. 
The object_type is smallint. 


[ @parameter_name = ] parameter_name 


The name of the parameter. The parameter_name is nvarchar(128). 


[ @parameter_value = ] parameter_value 
The value of the parameter. The parameter_val/ue is sql_variant. 


Remarks 


To find out the parameter values that were used for a given execution, query the 


catalog.execution_parameter_values view. 


To specify the scope of information that is logged during a package execution, set parameter_name to 


LOGGING_LEVEL and set parameter_va/ue to one of the following values. 


Set the object_type parameter to 50. 


VALUE 


100 


DESCRIPTION 


None 


Logging is turned off. Only the package execution status is 
logged. 


Basic 


All events are logged, except custom and diagnostic events. 
This is the default value. 


Performance 


Only performance statistics, and OnError and OnWarning 
events, are logged. 


Verbose 


All events are logged, including custom and diagnostic 
events. 

Custom events include those events that are logged by 
Integration Services tasks. For more information, see 
Custom Messages for Logging 


Runtime lineage 


Collects the data required to track lineage in the data flow. 


Custom logging level 


Specify the settings in the CUSTOMIZED_LOGGING_LEVEL 
parameter. For more info about the values that you can 
specify, see catalog.create_customized_logging_level. 


For more info about customized logging levels, see Enable 
Logging for Package Execution on the SSIS Server. 


To specify that the Integration Services server generates dump files when any error occurs during a package 


execution, set the following parameter values for an execution instance that hasn't run. 


PARAMETER 


execution_id 


object_type 


parameter_name 


parameter_value 


VALUE 


The unique identifier for the instance of execution 


50 


‘DUMP_ON_ERROR 


To specify that the Integration Services server generates dump files when events occur during a package 
execution, set the following parameter values for an execution instance that hasn't run. 


PARAMETER VALUE 

execution_id The unique identifier for the instance of execution 
object_type 50 

parameter_name ‘DUMP_ON_EVENT 

parameter_value 1 


To specify the events during package execution that cause the Integration Services server to generate dump 
files, set the following parameter values for an execution instance that hasn't run. Separate multiple event codes 
using a semi-colon. 


PARAMETER VALUE 
execution_id The unique identifier for the instance of execution 
object_type 50 
parameter_name DUMP_EVENT_CODE 
parameter_value One or more event codes 
Examples 


A. Generate dump files for errors 


The following example specifies that the Integration Services server generates dump files when any error occurs 
during a package execution. 


exec catalog.create_execution 'TR2','Recurring ETL’, ‘Dim_DCVendor.dtsx',NULL, @,@execution_id out 
exec catalog.set_execution_parameter_value @execution_id, 50, 'DUMP_ON_ERROR’,1 


B. Generate dump files for events 


The following example specifies that the Integration Services server generates dump files when events occur 
during a package execution, and specifies the event that causes the server to generate the files. 


exec catalog.create_execution 'TR2', ‘Recurring ETL', ‘'Dim_DCVendor.dtsx',NULL, @,@execution_id out 
exec catalog.set_execution_parameter_value @execution_id, 50, 'DUMP_ON_EVENT',1 


declare @event_code nvarchar(5@) 


set @event_code = '@xC@2@801C' 
exec catalog.set_execution_parameter_value @execution_id, 50, 'DUMP_EVENT_CODE', @event_code 


Return Code Value 


O (success) 


Result Sets 


None 


Permissions 

This stored procedure requires one of the following permissions: 
e READ and MODIFY permissions on the instance of execution 
e Membership to the ssis_admin database role 


e Membership to the sysadmin server role 


Errors and Warnings 


The following list describes some conditions that may raise an error or warning: 
e The user does not have the appropriate permissions 

e The execution identifier is not valid 

e The parameter name is not valid 


e The data type of the parameter value does not match the data type of the parameter 


See Also 


catalog.execution_parameter_values (SSISDB Database) 
Generating Dump Files for Package Execution 


catalog.set_execution_property_override_value 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 
Applies to: @ sal Server (all supported versions) 


Sets the value of a property for an instance of execution in the Integration Services catalog. 


Syntax 


catalog.set_execution_property_override_value [ @execution_id = execution_id 
» L @property_path = ] property_path 
» [ @property_value = ] property_value 
» [ @sensitive = ] sensitive 


Arguments 


[ @execution_id = ] execution_id 
The unique identifier for the instance of execution. The execution_idis bigint. 


[ @property_path = ] property_path 
The path to the property in the package. The property_path is nvarchar(4000). 


[ @property_value = ] property_value 
The override value to assign to the property. The property_va/ue is nvarchar(max). 


[ @sensitive = ] sensitive 
When the value is 1, the property is sensitive and is encrypted when it is stored. When the value is 0, the 
property is not sensitive and the value is stored in plaintext. The sensitive argument is bit. 


Remarks 


This procedure performs the same function as the Property overrides section in the Advanced tab of the 
Execute Package dialog. The path to the property is derived from the Package Path property of the package 
task. 


Return Code Value 


0 (success) 


Result Sets 


None 


Errors and Warnings 
The following list describes some conditions that may raise an error or warning: 
e@ The user does not have the appropriate permissions 


e The execution identifier is not valid 


e The property path is not valid 


@ The data type of the property value does not match the data type of the property 


See Also 


catalog.set_execution_parameter_value (SSISDB Database) 


catalog.set_folder_description (SSISDB Database) 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 
Applies to: @ sal Server (all supported versions) 


Sets the description of a folder in the Integration Services catalog. 


Syntax 


catalog.set_folder_description [ @folder_name = ] folder_name 
» [ @folder_description = ] folder_description 


Arguments 


[ @folder_name = ] fo/der_name 
The name of the folder. The fo/der_name is nvarchar(128). 


[ @folder_description = ] fo/der_description 
The description of the folder. The fo/der_description is nvarchar(MAX). 


Return Code Value 


None 


Result Sets 


None 


Permissions 
This stored procedure requires one of the following permissions: 
e Membership to the ssis_admin database role 


e Membership to the sysadmin server role 


Errors and Warnings 


The stored procedure returns a message to confirm the setting of new folder description. 


catalog.set_object_parameter_value (SSISDB 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 
Applies to: @ sal Server (all supported versions) 


Sets the value of a parameter in the Integration Services catalog. Associates the value to an environment 
variable or assigns a literal value that is used by default when no other values are assigned. 


Syntax 


catalog.set_object_parameter_value [ @object_type = ] object_type 
» [ @folder_name = ] folder_name 
» [ @project_name = ] project_name 
» [ @parameter_name = ] parameter_name 
» [ @parameter_value = ] parameter_value 
[ . [ @object_name = ] object_name ] 
[ . [ @value_type = ] value_type ] 


Arguments 


[@object_type =] object_type 
The type of parameter. Use the value 2@ to indicate a project parameter or the value 3@ to indicate a package 
parameter. The object_type is smallint. 


[@folder_name =] folder_name 
The name of the folder that contains the parameter. The fo/der_name is nvarchar(128). 


[@project_name =] project_name 
The name of the project that contains the parameter. The project_name is nvarchar(128). 


[@parameter_name =] parameter_name 
The name of the parameter. The parameter_name is nvarchar(128). 


[@parameter_value =] parameter_value 
The value of the parameter. The parameter_value is sq\_variant. 


[@object_name =] object_name 
The name of the package. This argument required when the parameter is a package parameter. The object_name 
is nvarchar(260). 


[@value_type =] va/ue_type 

The type of parameter value. Use the character v to indicate that parameter_value is a literal value that is used 
by default when no other values are assigned prior to execution. Use the character R to indicate that 
parameter_value is a referenced value and has been set to the name of an environment variable. This argument 
is optional, the character v is used by default. The va/ue_type is char(1). 


Return Code Value 


0 (success) 


Result Sets 


None 


Permissions 


This stored procedure requires one of the following permissions: 


e READ and MODIFY permissions on the project 


e Membership to the ssis_admin database role 


Membership to the sysadmin server role 


Errors and Warnings 


The following list describes some conditions that may cause the stored procedure to raise an error: 


The parameter type is not valid 

The project name is not valid 

For package parameters, the package name is not valid 
The value type Is not valid 


The user does not have the appropriate permissions 


Remarks 


If no value_type is specified, a literal value for parameter_value is used by default. When a literal value is 
used, the va/ue_setin the object_parameters view is set to 1 .A NULL parameter value is not allowed. 


If value_type contains the character r , which denotes a referenced value, parameter_value refers to the 


name of an environment variable. 


The value 2@ may be used for object_type to denote a project parameter. In this case, a value for 
object_name is not necessary, and any value specified for object_name is ignored. This value is used 
when the user wants to set a project parameter. 


The value 3@ may be used for object_type to denote a package parameter. In this case, a value for 
object_name is used to denote the corresponding package. If ob/ect_name is not specified, the stored 
procedure returns an error and terminates. 


catalog.set_worker_agent_property (SSISDB 
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Applies to: Q sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 
Applies to: @ sal Server (all supported versions) 


Sets the property of a Integration Services Scale Out Worker. 


Syntax 


catalog.set_worker_agent_property [ @WorkerAgentId = ] WorkerAgentId 
» [ @PropertyName = ] PropertyName 
» [ @PropertyValue = ] PropertyValue 


Arguments 


[@WorkerAgentld =] WorkerAgentld 
The worker agent ID of Scale Out Worker. The WorkerAgentid is uniqueidentifier. 


[@PropertyName =] PropertyName 
The name of the property. The PropertyName is nvarchar(256). 


[@PropertyValue =] PropertyValue 
The value of the property. The PropertyValue is nvarchar(max). 


Remarks 


The valid property names are DisplayName, Description, Tags. 


Return Code Value 


0 (success) 


Result Sets 


None 


Permissions 
This stored procedure requires one of the following permissions: 
e Membership to the ssis_admin database role 


e Membership to the sysadmin server role 


Errors and Warnings 


The following list describes some conditions that may raise an error or warning: 


The user does not have the appropriate permissions 
The worker agent ID is not valid. 
The property name is not valid. 


The property value is not valid. 


catalog.startup 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 
Applies to: @ sal Server (all supported versions) 
Performs maintenance of the state of operations for the SSISDB catalog. 


The stored procedure fixes the status of any packages there were running if and when the SSIS server instance 
goes down. 


You have the option of enabling the stored procedure to run automatically each time the SSIS server instance is 
restarted, by selecting the Enable automatic execution of Integration Services stored procedure at 
SQL Server startup option in the Create Catalog dialog box. 


Syntax 


catalog.startup 


Return Code Value 


O (success) 


Result Sets 


None 


Permissions 
This stored procedure requires one of the following permissions: 


e READ and MODIFY permissions on the instance of execution, READ and EXECUTE permissions on the 
project, and if applicable, READ permissions on the referenced environment 


e Membership to the ssis_admin database role 


e Membership to the sysadmin server role 


catalog.start_execution (SSISDB Database) 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 
Applies to: @sal Server (all supported versions) 


Starts an instance of execution in the Integration Services catalog. 


Syntax 


catalog.start_execution [ @execution_id = ] execution_id [, [ @retry_count = ] retry_count] 


Arguments 


[@execution_id =] execution_id 
The unique identifier for the instance of execution. The execution_idis bigint. 


[@retry_count =] retry_count 
The retry count if the execution fails. It takes effect only if the execution is in Scale Out. This parameter is 
optional. If not specified, its value is set to 0. The retry_countis int. 


Remarks 


An execution is used to specify the parameter values that is used by a package during a single instance of 
package execution. After an instance of execution has been created, before it has been started, the 
corresponding project might be redeployed. In this case, the instance of execution references a project that is 
outdated. This invalid reference causes the stored procedure to fail. 


NOTE 


Executions can only be started once. To start an instance of execution, it must be in the created state (a value of 1 in the 
status column of the catalog.operations view). 











Example 


The following example calls catalog.create_execution to create an instance of execution for the Child1.dtsx 
package. Integration Services Project1 contains the package. The example calls 
catalog.set_execution_parameter_value to set values for the Parameter1, Parameter2, and LOGGING_LEVEL 
parameters. The example calls catalog.start_execution to start an instance of execution. 


Declare @execution_id bigint 

EXEC [SSISDB].[catalog].[create_execution] @package_name=N'Child1.dtsx', @execution_id=@execution_id OUTPUT, 
@folder_name=N'TestDeply4', @project_name=N'Integration Services Project1', @use32bitruntime=False, 
@reference_id=Null 

Select @execution_id 

DECLARE @var@ sql_variant = N'Child1.dtsx' 

EXEC [SSISDB].[catalog].[set_execution_parameter_value] @execution_id, @object_type=20, 
@parameter_name=N'Parameter1', @parameter_value=@vara 
DECLARE @vari1 sql_variant = N'Child2.dtsx' 

EXEC [SSISDB].[catalog].[set_execution_parameter_value] @execution_id, @object_type=20, 
@parameter_name=N'Parameter2', @parameter_value=@var1 
DECLARE @var2 smallint = 1 

EXEC [SSISDB].[catalog].[set_execution_parameter_value] @execution_id, @object_type=50, 
@parameter_name=N'LOGGING_LEVEL', @parameter_value=@var2 

EXEC [SSISDB].[catalog].[start_execution] @execution_id 

GO 








Return Code Value 


O (success) 


Result Sets 


None 


Permissions 


This stored procedure requires one of the following permissions: 


e READ and MODIFY permissions on the instance of execution, READ and EXECUTE permissions on the 
project, and if applicable, READ permissions on the referenced environment 


e Membership to the ssis_admin database role 


e Membership to the sysadmin server role 


Errors and Warnings 

The following list describes some conditions that may raise an error or warning: 
e The user does not have the appropriate permissions 

e The execution identifier is not valid 


e The execution has already been started, or it has already been completed; executions can be started only 
once 


@ The environment reference associated with the project is not valid 
e Required parameter values have not been set 


e The project version associated with the instance of execution is outdated; only the most current version of 
a project can be executed 


catalog.stop_operation (SSISDB Database) 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 
Applies to: @ sal Server (all supported versions) 


Stops a validation or instance of execution in the Integration Services catalog. 


Syntax 


catalog.stop_operation [ @operation_id = ] operation_id 


Arguments 


[ @operation_id = ] operation_id 
The unique identifier of the validation or instance of execution. The operation_id is bigint. 


Return Code Value 


O (success) 


Result Sets 


None 


Permissions 

This stored procedure requires one of the following permissions: 

e READ and MODIFY permissions on the validation or instance of execution 
e Membership to the ssis_admin database role 


e Membership to the sysadmin server role 


Errors and Warnings 

The following list describes some conditions that may raise an error or warning: 
e The user does not have the appropriate permissions 

e The operation identifier is not valid 


e@ The operation has already been stopped 


Remarks 


Only one user at a time should stop an operation in Integration Services catalog. If multiple users try to stop the 
operation, the stored procedure will return success (the value @ ) on the first attempt, but subsequent attempts 


will raise an error. 


catalog.update_logdb_info (SSISDB Database) 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 
Applies to: @ sal Server 2017 (14.x) and later 


Update the Integration Services Scale Out Logging information. 


Syntax 


catalog.update_logdb_info [ @server_name = ] server_name, [ @connection_string = ] connection_string 


Arguments 


[ @server_name = ] server_name 
The Sql Server used for Scale Out logging. The server_name is nvarchar. 


[ @connection_string = ] connection_string 


The connection string used for Scale Out logging. The connection_string is nvarchar. 


Return Code Value 


O (success) 


Result Sets 


None 


Permissions 
This stored procedure requires one of the following permissions: 
e Membership to the ssis_admin database role 


e Membership to the sysadmin server role 


catalog.update_master_address (SSISDB Database) 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 
Applies to: @ sal Server 2017 (14.x) and later 


Update the Integration Services Scale Out Master endpoint. 


Syntax 


catalog.update_master_address [ @MasterAddress = ] masterAddress 


Arguments 


[ @MasterAddress = ] masterAddress 
The Scale Out Master endpoint. The masterAddress is nvarchar. 


Return Code Value 


O (success) 


Result Sets 


None 


Permissions 
This stored procedure requires one of the following permissions: 
e Membership to the ssis_admin database role 


e Membership to the sysadmin server role 


catalog.validate_package (SSISDB Database) 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 
Applies to: @ sal Server (all supported versions) 


Asynchronously validates a package in the Integration Services catalog. 


Syntax 


catalog.validate_package [ @folder_name = ] folder_name 
» [ @project_name = ] project_name 
» [ @package_name = ] package_name 
» [ @validation_id = ] validation_id OUTPUT 
[ . [ @use32bitruntime = ] use32bitruntime ] 
[ . [ @environment_scope = ] environment_scope ] 
[ ., [ @reference_id = ] reference_id ] 


Arguments 


[ @folder_name = ] fo/der_name 
The name of the folder that contains the package. The fo/der_name is nvarchar(128). 


[ @project_name = ] project_name 
The name of the project that contains the package. The project_name is nvarchar(128). 


[ @package_name = ] package_name 
The name of the package. The package_name is nvarchar(260). 


[ @validation_id = ] validation_id 
Returns the unique identifier (ID) of the validation. The va/idation_id is bigint. 


[ @use32bitruntime = ] use32bitruntime 

Indicates if the 32-bit runtime should be used to run the package on a 64-bit operating system. Use the value of 
1 to execute the package with the 32-bit runtime when running on a 64-bit operating system. Use the value of 
@ to execute the package with the 64-bit runtime when running on a 64-bit operating system. This parameter 

is optional. The use32bitruntime is bit. 


[ @environment_scope = ] environment_scope 

Indicates the environment references that are considered by the validation. When the value is 4, all 
environment references associated with the project are included in the validation. When the value is s , only a 
single environment reference is included. When the value is bp , no environment references are included and 
each parameter must have a literal default value in order to pass validation. This parameter is optional. The 
character D is used by default. The environment_scope is char(1). 


[ @reference_id = ] reference_id 
The unique ID of the environment reference. This parameter is required only when a single environment 


reference is included in the validation, when environment_scopeis s .The reference_idis bigint. 


Return Code Values 


0 (success) 


Result Sets 


None 


Permissions 

This stored procedure requires one of the following permissions: 

e READ permissions on the project and, if applicable, READ permissions on the referenced environments 
e Membership to the ssis_admin database role 


e Membership to the sysadmin server role 


Errors and Warnings 

The following list describes some conditions that may raise an error or warning: 
e@ The project name or package name is not valid 

e The user does not have the appropriate permissions 


e Oneor more of the referenced environments included in the validation do not contain referenced 
variables 


e The validation of the package fails 
e The environment that is referenced does not exist 
e Referenced variables cannot be found in the referenced environments included in the validation 


e Variables are referenced in the package parameters, but no referenced environments have been included 
in the validation 


Remarks 


Validation helps identify issues that may prevent the package from running successfully. Use the 
catalog.validations or catalog.operations views to monitor for validation status. 


catalog.validate_project (SSISDB Database) 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 
Applies to: @sal Server (all supported versions) 


Asynchronously validates a project in the Integration Services catalog. 


Syntax 


catalog.validate_project [ @folder_name = ] folder_name 
» [ @project_name = ] project_name 
» [ @validate_type = ] validate_type 
» [ @validation_id = ] validation_id OUTPUT 
[ . [ @use32bitruntime = ] use32bitruntime ] 
[ . [ @environment_scope = ] environment_scope ] 
[ ., [ @reference_id = ] reference_id ] 


Arguments 


[ @folder_name = ] fo/der_name 
The name of a folder that contains the project. The fo/der_name is nvarchar(128). 


[ @project_name = ] project_name 
The name of the project. The project_name is nvarchar(128). 


[ @validate_type = ] validate_type 
Indicates the type of validation to perform. Use the character F to perform a full validation. This parameter is 
optional, the character F will be used by default. The va/idate_type is char(1). 


[ @validation_id = ] validation_id 
Returns the unique identifier (ID) of the validation. The va/idation_id is bigint. 


[ @use32bitruntime = ] use32bitruntime 

Indicates if the 32-bit runtime should be used to run the package on a 64-bit operating system. Use the value of 
1 to execute the package with the 32-bit runtime when running on a 64-bit operating system. Use the value of 
@ to execute the package with the 64-bit runtime when running on a 64-bit operating system. This parameter 

is optional. The use32bitruntime is bit. 


[ @environment_scope = ] environment_scope 

Indicates the environment references that are considered by the validation. When the value is A , all 
environment references associated with the project are included in the validation. When the value is s , only a 
single environment reference is included. When the value is Dp , no environment references are included and 
each parameter must have a literal default value in order to pass validation. This parameter is optional, the 
character p will be used by default. The environment_scope is char(1). 


[ @reference_id = ] reference_id 
The unique ID of the environment reference. This parameter is required only when a single environment 
reference is included in the validation, when environment_scopeis s . The reference_idis bigint. 


Return Code Values 


0 (success) 


Result Sets 


Output from the validation steps is returned as different sections of the result set. 


Permissions 

This stored procedure requires one of the following permissions: 

e READ permissions on the project and, if applicable, READ permissions on the referenced environments 
e Membership to the ssis_admin database role 


e Membership to the sysadmin server role 


Errors and Warnings 
The following list provides some conditions that may raise an error or warning: 
e Validation fails for one or more packages in the project 


e Validation fails if one or more of the referenced environments included in the validation do not contain 
referenced variables 


e The specified validate type is not valid 
e The project name or environment reference ID is not valid 


e The user does not have the appropriate permissions 


Remarks 


Validation helps identify issues that will prevent the packages in the project from running successfully. Use the 
catalog.validations or catalog.operations views to monitor for validation status. 


Only environments that are accessible by the user can be used in the validation. Validation output is sent to the 
client as a result set. 


In this release, project validation does not support dependency validation. 


Full validation confirms that all referenced environment variables are found within the referenced environments 
that were included in the validation. Full validation results list environment references that are not valid and 
referenced environment variables that could not be found in any of the referenced environments that were 
included in the validation. 


catalog.cleanup_server_execution_keys 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 
Applies to: @ sal Server (all supported versions) 


Drops certificates and symmetric keys from the SSISDB database. 


Syntax 


catalog.cleanup_server_execution_keys [ @cleanup_flag = ] cleanup_flag , 
[ @delete_batch_size = ] delete_batch_size 


Arguments 


[ @cleanup_flag = ] cleanup_flag 
Indicates whether execution level (1) or project level (2) certificates and symmetric keys are to be dropped. 


Use execution level (1) only when the SERVER_OPERATION_ENCRYPTION_LEVEL is set to PER_EXECUTION (1). 


Use project level (2) only when the SERVER_OPERATION_ENCRYPTION_LEVEL is set to PER_PROJECT (2). 
Certificates and symmetric keys are dropped only for projects that have been deleted and for which the 
operation logs have been cleaned. 


[ @delete_batch_size = ] de/ete_batch_size 
The number of keys and certificates to be dropped. The default value is 1000. 


Return Code Values 


0 for success and 1 for failure. 


Result Sets 


None. 


Permissions 
This stored procedure requires one of the following permissions: 


@ READ and EXECUTE permissions on the project and, if applicable, READ permissions on the referenced 
environment. 


e Membership in the ssis_admin database role. 


e Membership to the sysadmin server role. 


Errors and Warnings 


This stored procedure raises errors in the following scenarios: 


e There are one or more active operations in the SSISDB database. 


The SSISDB database is not in single user mode. 


Remarks 


SQL Server 2012 Service Pack 2 added the SERVER_OPERATION_ENCRYPTION_LEVEL property to the 
internal.catalog_properties table. This property has two possible values: 


PER_EXECUTION (1) - The certificate and symmetric key used for protecting sensitive execution 
parameters and execution logs are created for each execution. This is the default value. You may run into 
performance issues (deadlocks, failed maintenance jobs etc...) in a production environment because 
certificate/keys are generated for each execution. However, this setting provides a higher level of security 
than the other value (2). 


PER_PROJECT (2) - The certificate and symmetric key used for protecting sensitive parameters are 
created for each project. This gives you a better performance than the PER_EXECUTION level because the 
key and certificate are generated once for a project rather than for each execution. 


You have to run the catalog.cleanup_server_log stored procedure before you can change the 
SERVER_OPERATION_ENCRYPTION_LEVEL from 1 to 2 (or) from 2 to 1. Before running this stored procedure, 
do the following things: 


1. 


Ensure that the value of the property OPERATION_CLEANUP_ENABLED is set to TRUE in the 
catalog.catalog_properties (SSISDB Database) table. 


. Set the Integration Services database (SSISDB) to single-user mode. In SQL Server Management Studio, 


launch Database Properties dialog box for SSISDB, switch to the Options tab, and set the Restrict Access 
property to single-user mode (SINGLE_USER). After you run the cleanup_server_log stored procedure, set 
the property value back to the original value. 


. Run the stored procedure catalog.cleanup_server_log. 


. Now, go ahead and change the value for the SERVER_OPERATION_ENCRYPTION_LEVEL property in the 


catalog.catalog_properties (SSISDB Database) table. 


. Run the stored procedure catalog.cleanup_server_execution_keys to clean up certificates keys from the 


SSISDB database. Dropping certificates and keys from the SSISDB database may take a long time, so it 
should be run periodically during off-peak times. 


You can specify the scope or level (execution vs. project) and number of keys to be deleted. The default 
batch size for deletion is 1000. When you set the level to 2, the keys and certificates are deleted only if 
the associated projects have been deleted. 


For more info, see the following Knowledge Base article. FIX: Performance issues when you use SSISDB as your 


deployment store in SQL Server 2012 


Example 


The following example calls the cleanup_server_execution_keys stored procedure. 


USE [SSISDB] 
GO 


DECLARE@return_value int 

EXEC@return_value = [internal].[cleanup_server_execution_keys] 
@cleanup_flag = 1, 

@delete_batch_size = 500 


SELECT'Return Value’ = @return_value 


GO 


catalog.cleanup_server_log 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 
Applies to: @sal Server (all supported versions) 


Cleans up operation logs to bring the SSISDB database into a state that lets you change the value of the 
SERVER_OPERATION_ENCRYPTION_LEVEL property. 


Syntax 


catalog.cleanup_server_log 


Arguments 


None. 


Return Code Values 


0 for success and 1 for failure. 


Result Sets 


None. 


Permissions 
This stored procedure requires one of the following permissions: 


e READ and EXECUTE permissions on the project and, if applicable, READ permissions on the referenced 
environment. 


e Membership in the ssis_admin database role. 


e Membership to the sysadmin server role. 


Errors and Warnings 


This stored procedure raises errors in the following scenarios: 
e There are one or more active operations in the SSISDB database. 


e The SSISDB database is not in single user mode. 


Remarks 


SQL Server 2012 Service Pack 2 added the SERVER_OPERATION_ENCRYPTION_LEVEL property to the 
internal.catalog_properties table. This property has two possible values: 


e PER_EXECUTION (1) - The certificate and symmetric key used for protecting sensitive execution 


parameters and execution logs are created for each execution. You may run into performance issues 


(deadlocks, failed maintenance jobs, etc.) in a production environment because certificate/keys are 
generated for each execution. However, this setting provides a higher level of security than the other 
value (2). 


@ PER_PROJECT (2) - The certificate and symmetric key used for protecting sensitive parameters are 
created for each project. PER_PROJECT (2) is the default value. This setting gives you a better 
performance than the PER_EXECUTION level because the key and certificate are generated once for a 
project rather than for each execution. 


You have to run the catalog.cleanup_server_log stored procedure before you can change the 
SERVER_OPERATION_ENCRYPTION_LEVEL from 2 to 1 or from 1 to 2. Before running this stored procedure, do 
the following things: 


1. Ensure that the value of the property OPERATION_CLEANUP_ENABLED is set to TRUE in the 
catalog.catalog_properties (SSISDB Database) table. 


2. Set the Integration Services database (SSISDB) to single-user mode. In SQL Server Management Studio, 
launch Database Properties dialog box for SSISDB, switch to the Options tab, and set the Restrict Access 
property to single-user mode (SINGLE_USER). After you run the cleanup_server_log stored procedure, set 
the property value back to the original value. 


3. Run the stored procedure catalog.cleanup_server_log. 


4. Now, go ahead and change the value for the SERVER_OPERATION_ENCRYPTION_LEVEL property in the 
catalog.catalog_properties (SSISDB Database) table. 


5. Run the stored procedure catalog.cleanup_server_execution_keys to clean up certificates keys from the 
SSISDB database. Dropping certificates and keys from the SSISDB database may take a long time, so it 
should be run periodically during off-peak times. 


You can specify the scope or level (execution vs. project) and number of keys to be deleted. The default 
batch size for deletion is 1000. When you set the level to 2, the keys and certificates are deleted only if 
the associated projects have been deleted. 


For more info, see the following Knowledge Base article: FIX: Performance issues when you use SSISDB as your 
deployment store in SQL Server 2012 


Example 


The following example calls the cleanup_server_log stored procedure. 


USE [SSISDB] 
GO 


DECLARE@return_value int 

EXEC@return_value = [internal].[cleanup_server_log] 
SELECT'Return Value’ = @return_value 

GO 


Functions - dm_execution_performance_counters 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Returns the performance statistics for an execution that is running on the Integration Services server. 


Syntax 


dm_execution_performance_counters [ @execution_id = ] execution_id 


Arguments 


[ @execution_id = ] execution_id 
The unique identifier of the execution that contains one or more packages. Packages that are executed with the 
Execute Package task, run in the same execution as the parent package. 


If an execution ID is not specified, performance statistics for multiple executions are returned. If you area 
member of the ssis_admin database role, performance statistics for all running executions are returned. If you 
are not a member of the ssis_admin database role, performance statistics for the running executions for which 
you have read permissions, are returned. The execution_id is a BigInt. 


Remarks 
The following table lists the counter name values returned by the dm_execution_performance_counter function. 


COUNTER NAME DESCRIPTION 


BLOB bytes read Number of bytes of binary large object (BLOB) data that the 
data flow engine reads from all sources. 


BLOB bytes written Number of bytes of BLOB data that the data flow engine 
writes to all destinations. 


BLOB files in use Number of BLOB files that the data flow engine is using for 
spooling. 
Buffer memory Amount of memory that is used by the Integration Services 


buffers, including physical and virtual memory. 


Buffers in use Number of buffer objects, of all types, that all data flow 
components and the data flow engine are using. 


Buffers spooled Number of buffers written to the disk. 


Flat buffer memory Amount of memory, in bytes, that is used by all flat buffers. 
Flat buffers are blocks of memory that a component uses to 
store data. 


COUNTER NAME 


Flat buffers in use 


Private buffer memory 


Private buffers in use 


Rows read 


Rows written 


Return 


DESCRIPTION 


Number of flat buffers that the data flow engine uses. All flat 
buffers are private buffers. 


Amount of memory in use by all private buffers. A private 
buffer is a buffer that a transformation uses for temporary 
work. 


A buffer is not private if the data flow engine creates the 
buffer to support the data flow. 


Number of buffers that the transformations use for 
temporary work. 


Total number of rows read by the execution. 


Total number of rows written by the execution. 


The dm_execution_performance_counters function returns a table with the following columns, for a running 


execution. The information returned is for all of the packages contained in the execution. If there are no running 


executions, an empty table is returned. 
COLUMN NAME COLUMN TYPE 


execution_id BigInt 


NULL is not a valid value. 


counter_name nvarchar(128) 


counter_value BigInt 


Examples 


A. Return statistics for a running execution 


DESCRIPTION REMARKS 


Unique identifier for the 
execution that contains the 
package. 


The name of the counter. See the Remarks section of 


values. 


Value returned by the 
counter. 


In the following example, the function returns statistics for a running execution with an ID of 34. 


select * from [catalog].[dm_execution_performance_counters] (34) 


B. Return statistics for all running executions 


In the following example, the function returns statistics for all the executions running on the Integration Services 


server, depending on your permissions. 


select * from [catalog].[dm_execution_performance_counters] (NULL) 


Permissions 


This function requires one of the following permissions: 
e READ and MODIFY permissions on the instance of execution 
e Membership to the ssis_admin database role 


e Membership to the sysadmin server role 


Errors and Warnings 
The following list describes conditions that cause the function to fail. 
e The user does not have MODIFY permissions for the specified execution. 


e The specified execution ID is not valid. 


Errors and Events Reference (Integration Services) 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


This section of the documentation contains information about several errors and events related to Integration 


Services. Cause and resolution information is included for error messages. 


For more information about Integration Services error messages, including a list of most Integration Services 


errors and their descriptions, see Integration Services Error and Message Reference. However, the list currently 


does not include troubleshooting information. 


IMPORTANT 





Many of the error messages that you may see when you are working with Integration Services come from other 
components. These may include OLE DB providers, other database components such as the Database Engine and Analysis 
Services , or other services or components such as the file system, the SMTP server, or Microsoft Message Queueing. To 


find information about these external error messages, see the documentation specific to the component. 





Error Messages 


SYMBOLIC NAME OF ERROR 


DTS_E CACHELOADEDFROMFILE 


DTS_E CANNOTACQUIRECONNECTIONFROMCONNECTION 
MANAGER 


DTS_E CANNOTCONVERTBETWEENUNICODEANDNONUNIC 
ODESTRINGCOLUMN 


DTS_E CANNOTCONVERTBETWEENUNICODEANDNONUNIC 
ODESTRINGCOLUMNS 


DTS_E_CANTINSERTCOLUMNTYPE 


DTS_E CONNECTIONNOTFOUND 


DESCRIPTION 


Indicates that the package cannot run because a Cache 
Transform transformation is trying to write data to the in- 
memory cache. However, a Cache connection manager has 
already loaded a cache file into the in-memory cache. 


Indicates that the package cannot run because a specified 
connection failed. 


Indicates that a data flow component is trying to pass 
Unicode string data to another component that expects 
non-Unicode string data in the corresponding column, or 
vice versa. 


Indicates that a data flow component is trying to pass 
Unicode string data to another component that expects 
non-Unicode string data in the corresponding column, or 
vice versa. 


Indicates that the column cannot be added to the database 
table because the conversion between the Integration 
Services column data type and the database column data 
type is not supported. 


Indicates that the package cannot run because the specified 
connection manager cannot be found. 





SYMBOLIC NAME OF ERROR 


DTS_E_ CONNECTIONREQUIREDFORMETADATA 


DTS_E_MULTIPLECACHEWRITES 


DTS_E_PRODUCTLEVELTOLOW 


DTS_E_READNOTFILLEDCACHE 


DTS_E_UNPROTECTXMLFAILED 


DTS_E_WRITEWHILECACHEINUSE 


DTS_W_EXTERNALMETADATACOLUMNSOUTOFSYNC 


Events (SQLISPackage) 


DESCRIPTION 


Indicates that SSIS Designer must connect to a data source 
to retrieve new or updated metadata for a source or 
destination, and that it is unable to connect to the data 
source. 


Indicates that the package cannot run because a Cache 
Transform transformation is trying to write data to the in- 
memory cache. However, another Cache Transform 
transformation has already written to the in-memory cache. 


Indicates that the package cannot run because the 
appropriate version of SQL Server Integration Services is not 
installed. 


Indicates that a Lookup transformation is trying to read data 
from the in-memory cache at the same time that a Cache 
Transform transformation is writing data to the cache. 


Indicates that the system did not decrypt a protected XML 
node. 


Indicates that a Cache Transform transformation is trying to 
write data to the in-memory cache at the same time that a 
Lookup transformation is reading data from the in-memory 
cache. 


Indicates that the column metadata in the data source does 
not match the column metadata in the source or destination 
component that is connected to the data source. 


For more information, see Events Logged by an Integration Services Package. 


EVENT 


SQLISPackage_12288 


SQLISPackage_12289 


SQLISPACKAGE_12291 


SQLISPackage_12546 


SQLISPackage_12549 


SQLISPackage_12550 


SQLISPackage_12551 


SQLISPackage_12557 


DESCRIPTION 


Indicates that a package started. 


Indicates that a package has finished running successfully. 


Indicates that a package was unable to finish running and 
has stopped. 


Indicates that a task or other executable in a package has 
finished its work. 


Indicates that a warning message was raised in a package. 


Indicates that an error message was raised in a package. 


Indicates that a package did not finish its work and stopped. 


Indicates that a package has finished running. 


Events (SQLISService) 


For more information, see Events Logged by the Integration Services Service. 


EVENT 

SQLISService_256 
SQLISService_257 
SQLISService_258 
SQLISService_259 
SQLISService_260 


SQLISService_272 


SQLISService_273 


SQLISService_274 


See Also 


Integration Services Error and Message Reference 


DESCRIPTION 


Indicates that the service is about to start. 


Indicates that the service has started. 


Indicates that the service is about to stop. 


Indicates that the service has stopped. 


Indicates that the service tried to start, but could not. 


Indicates that the configuration file does not exist at the 
specified location. 


Indicates that the configuration file could not be read or is 
not valid. 


Indicates that the registry entry that contains the location of 
the configuration file does not exist or is empty. 


Integration Services Error and Message Reference 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


The following tables list predefined Integration Services errors, warnings, and informational messages, in 
ascending numerical order within each category, along with their numeric codes and symbolic names. Each of 
these errors is defined as a field in the Microsoft.SqlServer.Dts.Runtime.Hresults class in the 
Microsoft.SqlServer.Dts.Runtime namespace. 


This list may be useful when you encounter an error code without its description. The list does not include 
troubleshooting information at this time. 


This list contains the following groups of messages: 
e Error Messages (DTS_E_*) 

e Warning Messages (DTS_W_*) 

e Informational Messages(DTS_I_*) 

e@ General and Event Messages(DTS_MSG_*) 

e Success Messages(DTS_S_*) 


e Data Flow Component Error Messages (DTSBC_E_*) 





IMPORTANT 


Many of the error messages that you may see while working with Integration Services come from other components. In 
this topic, you will find all the errors raised by Integration Services components. If you do not see your error in the list, the 
error was raised by a component outside Integration Services. These may include OLE DB providers, other database 
components such as the Database Engine and Analysis Services, or other services or components such as the file system, 
the SMTP server, Message Queuing (also known as MSMQ), and so forth. To find information about these external error 
messages, see the documentation specific to the component. 











Error Messages 


The symbolic names of Integration Services error messages begin with DTS_E_. 


HEXADECIMAL CODE DECIMAL CODE SYMBOLIC NAME DESCRIPTION 

0x8002F347 -2147290297 DTS_E_ STOREDPROCSTASK_ Overwriting Stored 
OVERWRITINGSPATDESTIN Procedure "%1" at 
ATION destination. 

0x8020837E -2145352834 DTS_E_ ADOSRCUNKNOWN The data type "%1" found 
TYPEMAPPEDTONTEXT on column "%2" is not 


supported for the %3. This 
column will be converted to 
DT_NTEXT. 


HEXADECIMAL CODE 


0x8020838C 


0xC0000032 


0xC0000033 


0xC0000034 


0xC0000035 


OxCOO060AB 


0xC0008445 


0xC000931A 


OxCO00F427 


DECIMAL CODE 


-2145352820 


-1073741774 


-1073741773 


-1073741772 


-1073741771 


-1073717077 


-1073707963 


-1073704166 


-1073679321 


SYMBOLIC NAME 


DTS_E_XMLSRCSCHEMACO 
LUMNNOTINEXTERNALMET 
ADATA 


DTS_E_NOTINITIALIZED 


DTS_E_EXPIRED 


DTS_E_NEGATIVEVALUESN 
OTALLOWED 


DTS_E_NEGATIVEINDEXNOT 
ALLOWED 


DTS_E_INVALIDSSISSERVER 
NAME 


DTS_E_SCRIPTMIGRATIONF 
AILED64BIT 


DTS_E_COMMANDDESTINA 
TIONADAPTERSTATIC_ERRO 
RSINCOMMAND 


DTS_E_SSISSTANDALONEN 
OTINSTALLED 


DESCRIPTION 


The column %1 in table %2 
in the XML schema does 

not have a mapping in the 
external metadata columns. 


An internal object or 
variable was not initialized. 
This is an internal product 
error. This error is returned 
when a variable should 
have a valid value but does 
not. 


Integration Services 
evaluation period has 
expired. 


This property cannot be 
assigned a negative value. 
This error occurs when a 
negative value is assigned 
to a property that can only 
contain positive values, 
such >as the COUNT 


property. 


Indexes cannot be negative. 
This error occurs when a 
negative value is used as an 
index to a collection. 


Invalid server name "%1". 
SSIS service does not 
support multi-instance, use 
just server name instead of 
"server name\instance". 


Migration for VSA scripts 
can not be done on 64 bit 
platforms due to lack of 
Visual Tools for Applications 
designer support. Run the 
migration under WOW64 
on >64 bit platforms. 


The command execution 
generated errors. 


To run a SSIS package 
outside of SQL Server Data 
Tools (SSDT) you must 
install %1 of Integration 
Services or higher. 


HEXADECIMAL CODE 


0xC0010001 


0xC0010003 


0xC0010004 


0xC0010006 


0xC0010007 


0xC0010008 


0xC0010009 


0xC001000A 


0xC001000C 


DECIMAL CODE 


-1073676287 


-1073676285 


-1073676284 


-1073676282 


-1073676281 


-1073676280 


-1073676279 


-1073676278 


-1073676276 


SYMBOLIC NAME 


DTS_E_VARIABLENOTFOUN 
D 


DTS_E_VARIABLEREADONLY 


DTS_E_MANAGEDCOMPON 
ENTSTORENOTFOUND 


DTS_E_PACKAGENAMETOO 
LONG 


DTS_E_PACKAGEDESCRIPTI 
ONTOOLONG 


DTS_E_VERCOMMENTSTOO 
LONG 


DTS_E_ELEMENTNOTFOUN 
D 


DTS_E_PACKAGENOTFOUN 
D 


DTS_E_INVALIDVARIABLEVA 
LUE 


DESCRIPTION 


The variable cannot be 
found. This occurs when an 
attempt is made to retrieve 
a variable from the 
Variables collection on a 
container during execution 
of the package, >and the 
variable is not there. The 
variable name may have 
changed or the variable is 
not being created. 


Error trying to write to a 
read-only variable, "%1". 


Unable to find the 
directories containing Tasks 
and Data Flow Task 
components. Check the 
integrity of your installation. 


Package name is too long. 
The limit is 128 characters. 
Shorten the package name. 


Package description is too 
long. The limit is 1024 
characters. Shorten the 
package description. 


VersionComments property 
is too long. The limit is 
1024 characters. Try 
shortening the 
VersionComments. 


The element cannot be 
found in a collection. This 
error happens when you try 
to retrieve an element from 
a collection on a container 
during execution of the 
package and >the element 
is not there. 


The specified package could 
not be loaded from the SQL 
Server database. 


The variable value 
assignment is not valid. This 
error happens when the 
client or a task assigns a 
runtime object to a variable 
value. 


HEXADECIMAL CODE 


0xC001000D 


0xC001000E 


0xC001000F 


0xC0010010 


0xC0010011 


0xC0010013 


0xC0010014 


DECIMAL CODE 


-1073676275 


-1073676274 


-1073676273 


-1073676272 


-1073676271 


-1073676269 


-1073676268 


SYMBOLIC NAME 


DTS_E_RESERVEDNAMESPA 
CE 


DTS_E_CONNECTIONNOTF 
OUND 


DTS_E_64BITVARIABLERECA 
ST 


DTS_E_CANTCHANGEREAD 
ONLYATRUNTIME 


DTS_E_VARIABLEINVALIDC 
ONTAINERREF 


DTS_E_INVALIDVARVALUE 


DTS_E_GENERICERROR 


DESCRIPTION 


Error assigning namespace 
to the variable. The 
namespace "System" is 
reserved for system use. 
This error happens when a 
component or task 
attempts to create a 
variable >with a namespace 
of "System". 


The connection "%1" is not 
found. This error is thrown 
by Connections collection 
when the specific 
connection element is not 
found. 


The variable "%1" is a 64-bit 
integer variable, which is 
not supported on this 
operating system. The 
variable has been recast to 
32-bit integer. 


An attempt change to a 
read-only attribute on 
variable "%1" occurred. This 
error happens when a read- 
only attribute for a variable 
is being changed at 
>runtime. Read-only 
attributes can be changed 
only at design time. 


Invalid attempt to set a 
variable to a container 
reference. Variables are not 
allowed to reference 
containers. 


Assigning invalid value or 
object to variable "%1". This 
error happens when a value 
is not appropriate for 
variables. 


One or more error 
occurred. There should be 
more specific errors 
preceding this one that 
explains the details of the 
errors. This message is used 
as a return value from 
>functions that encounter 
errors. 


HEXADECIMAL CODE 


0xC0010016 


0xC0010017 


0xC0010018 


0xC0010019 


0xC0010020 


0xC0010021 


0xC0010022 


0xC0010023 


0xC0010025 


0xC0010026 


0xC0010027 


DECIMAL CODE 


-1073676266 


-1073676265 


-1073676264 


-1073676263 


-1073676256 


-1073676255 


-1073676254 


-1073676253 


-1073676251 


-1073676250 


-1073676249 


SYMBOLIC NAME 


DTS_E_INVALIDARRAYVALU 
E 


DTS_E_UNSUPPORTEDARRA 
YTYPE 


DTS_E_PERSISTENCEERROR 


DTS_E_INVALIDNODE 


DTS_E_ERRORLOADINGTAS 
K 


DTS_E_ERRORELEMENTNOT 
INCOLL 


DTS_E_MISSINGOBJECTDAT 
A 


DTS_E_VARIABLENOTFOUN 
DINCOLL 


DTS_E_HASEMPTYTASKHOS 
TS 


DTS_E_TASKISEMPTY 


DTS_E_ERRORLOADINGTAS 
KNOCONTACT 


DESCRIPTION 


Error getting or setting an 

array value. The type "%1" 
is not allowed. This occurs 

when loading an array into 
a variable. 


Unsupported type in array. 
This happens when saving 
an array of unsupported 
types into a variable. 


Error loading value "%1" 
from node "%2". 


Node "%1" is not a valid 
node. This happens when 
saving fails. 


Failed to load task "%1", 
type "%2". The contact 
information for this task is 
"%3". 


Element "%1" does not exist 
in collection "%2". 


The ObjectData element is 
missing in the XML block of 
a hosted object. This occurs 
when the XML parser 
attempts to locate the data 
element for an object and it 
cannot >be found. 


The variable "%1" cannot be 
found. This error occurs 
when an attempt to retrieve 
a variable from a variables 
collection on a container 
during execution of the 

> package occurs, and the 
variable is not there. A 
variable name may have 
changed or the variable is 
not being created. 


The package cannot execute 
because it contains tasks 
that failed to load. 


The task has failed to load. 
The contact information for 
this task is "%1". 


Error loading task "%1". 


HEXADECIMAL CODE 


0xC0010028 


0xC0010200 


0xC0010201 


0xC0010202 


0xC0010203 


0xC0010204 


0xC0010205 


0xC0010206 


0xC0011001 


0xC0011002 


DECIMAL CODE 


-1073676248 


-1073675776 


-1073675775 


-1073675774 


-1073675773 


-1073675772 


-1073675771 


-1073675770 


-1073672191 


-1073672190 


SYMBOLIC NAME 


DTS_E_ERRORATLOADTASK 


DTS_E_MULTIPLECACHEWR 
ITES 


DTS_E_SETCACHEFORINSER 
TFAILED 


DTS_E_SETCACHEFORFILLFA 
ILED 


DTS_E_READUNINITIALIZED 
CACHE 


DTS_E_SETCACHEFORREAD 
FAILED 


DTS_E_READNOTFILLEDCAC 
HE 


DTS_E_WRITEWHILECACHEI 
NUSE 


DTS_E_CANTLOADFROMN 
ODE 


DTS_E_LOPENPACKAGEFILE 


DESCRIPTION 


Error loading task. This 
happens when loading a 
task from XML fails. 


The %1 cannot write to the 
cache because %2 has 
already written to it. 


Failed to prepare the cache 
for new data. 


Failed to mark the cache as 
filled with data. 


The cache is not initialized 
and cannot be read by %1. 


Failed to prepare the cache 
for providing data. 


The cache is being written 
to by %1, and cannot be 
read by %2. 


The cache is being read 
from %1 and cannot be 
written to by %2. 


The runtime object cannot 
be loaded from the 
specified XML node. This 
happens when trying to 
load a package or other 
object from an XML node 
that is not of the correct 
>type, such as a non-SSIS 
XML node. 


Failed to open package file 
"%1" due to error 
0x%2!8.8X! "%3". This 
happens when loading a 
package and the file cannot 
be opened or loaded 
correctly into the XML 
>document. This can be the 
result of either providing an 
incorrect file name was 
specified when calling 
LoadPackage or the XML 
file was specified and has an 
incorrect format. 


HEXADECIMAL CODE 


0xC0011003 


0xC0011004 


0xC0011005 


0xC0011006 


0xC0011007 


0xC0011008 


DECIMAL CODE 


-1073672189 


-1073672188 


-1073672187 


-1073672186 


-1073672185 


-1073672184 


SYMBOLIC NAME 


DTS_E_LOADPACKAGEXML 


DTS_E_LOADPACKAGEXMLF 
ILE 


DTS_E_OPENFILE 


DTS_E_UNABLETODECODEB 
INARYFORMAT 


DTS_E_FUNDAMENTALLOA 
DINGERROR 


DTS_E_LLOADFROMXML 


DESCRIPTION 


Failed to load XML due to 
error 0x%1!8.8X! "%2". This 
happens when loading a 
package and the file cannot 
be opened or loaded 
correctly into XML 
document. This can be the 
>result of either providing 
an incorrect file name to the 
LoadPackage method or the 
XML file specified having an 
incorrect format. 


Failed to load XML from 
package file "%1" due to 
error 0x%2!8.8X! "%3". This 
happens when loading a 
package and the file cannot 
be opened or loaded 
correctly into an >XML 
document. This can be the 
result of either providing an 
incorrect file name to the 
LoadPackage method or the 
XML file specified having an 
incorrect format. 


Failed to open package file. 
This happens when loading 
a package and the file 
cannot be opened or 
loaded correctly into an 
XML document. This can be 
the result of either 

> providing an incorrect file 
name to the LoadPackage 
method or the XML file 
specified having an 
incorrect format. 


Unable to decode a binary 
format in the package. 


Unable to load the package 
as XML because of package 
does not have a valid XML 
format. A specific XML 
parser error will be posted. 


Error loading from XML. No 
further detailed error 
information can be specified 
for this problem because no 
Events object was passed 
where detailed error 
information can be >stored. 


HEXADECIMAL CODE 


0xC0011009 


0xC001100D 


0xC001100E 


0xC001100F 


0xC001200D 


0xC0012018 


0xC0012019 


0xC001201B 


0xC0012021 


0xC0012022 


0xC0012023 


0xC0012024 


DECIMAL CODE 


-1073672183 


-1073672179 


-1073672178 


-1073672177 


-1073668083 


-1073668072 


-1073668071 


-1073668069 


-1073668063 


-1073668062 


-1073668061 


-1073668060 


SYMBOLIC NAME 


DTS_E_XMLDOMERROR 


DTS_E_CANNOTLOADOLDP 
ACKAGES 


DTS_E_SAVEFILE 


DTS_E_SAVEPACKAGEFILE 


DTS_E_IDTSNAMENOTSUPP 
ORTED 


DTS_E_CONFIGFORMATINV 
ALID_PACKAGEDELIMITER 


DTS_E_CONFIGFORMATINV 
ALID 


DTS_E_CONFIGFILEFAILEDE 
XPORT 


DTS_E_PROPERTIESCOLLEC 
TIONREADONLY 


DTS_E_DTRXMLSAVEFAILUR 
E 


DTS_E_FAILPACKAGEONFAI 
LURENA 


DTS_E_TASKPRODUCTLEVEL 


DESCRIPTION 


Cannot create an instance 
of the XML Document 
Object Model. MSXML may 
not be registered. 


The package cannot be 
loaded. This occurs when 
attempting to load an older 
version package, or the 
package file refers to an 
invalid structured object. 


Failed to save package file. 


Failed to save package file 
"%1" with error 0x%2!8.8X! 
"%3". 


The object must inherit 
from IDTSName100 and 
does not. 


The configuration entry, 
"%1", has an incorrect 
format because it does not 
begin with package 
delimiter. There was no 
"\package" delimiter. 


The configuration entry 
"%1" had an incorrect 
format. This can occur 
because of a missing 
delimiter or formatting 
errors, like an invalid array 
delimiter. 


Failure exporting 
configuration file. 


Properties collection cannot 
be modified. 


Unable to save 
configuration file. The file 
may be read only. 


FailPackageOnFailure 
property is not applicable 
to the package container. 


The task "%1" cannot run 
on installed %2 of 
Integration Services. It 
requires %3 or higher. 


HEXADECIMAL CODE 


0xC0012029 


0xC0012037 


0xC0012049 


0xC0012050 


0xC0013001 


0xC0013002 


0xC0013003 


0xC0013004 


0xC0014003 


0xC0014004 


DECIMAL CODE 


-1073668055 


-1073668041 


-1073668023 


-1073668016 


-1073663999 


-1073663998 


-1073663997 


-1073663996 


-1073659901 


-1073659900 


SYMBOLIC NAME 


DTS_E_UNABLETOSAVETOFI 
LE 


DTS_E_CONFIGTYPECONVE 
RSIONFAILED 


DTS_E_CONFIGFAILED 


DTS_E_REMOTEPACKAGEVA 
LIDATION 


DTS_E_FAILTOCREATEMUTE 
X 


DTS_E_MUTEXOWNBY DIFF 
USER 


DTS_E_WAITFORMUTEXFAIL 
ED 


DTS_E_FAILTORELEASEMUT 
EX 


DTS_E_INVALIDTASKPOINTE 
R 


DTS_E_ALREADYADDED 


DESCRIPTION 


Unable to save xml to "%1". 
The file may be read only. 


Failed to convert a type in 
the configuration "%1" for 
the package path "%2". This 
happens when a 
configuration value cannot 
be converted from a string 
to the > appropriate 
destination type. Check the 
configuration value to 
ensure it can be converted 
to the type of the 
destination property or 
variable. 


Configuration failure. This is 
a generic warning for all 
configuration types. Other 
warnings should precede 
this with more information. 


Package failed validation 
from the ExecutePackage 
task. The package cannot 
run. 


Failed to create mutex "%1" 
with error 0x%2!8.8X!. 


Mutex "%1" already exists 
and is owned by another 
user. 


Failed to acquire mutex 
"%1" with error 0x%2!8.8X!. 


Failed to release mutex "%1" 
with error 0x%2!8.8X!. 


The wrappers task pointer is 
not valid. The wrapper has 
an invalid pointer to a task. 


The executable has been 
added to the Executables 
collection of another 
container. This occurs when 
a client tries to add an 
executable to more than 
one Executables > collection. 
You need to remove the 
executable from the current 
Executables collection 
before attempting to add it. 


HEXADECIMAL CODE 


0xC0014005 


0xC0014006 


0xC0014007 


0xC0014008 


0xC0014009 


0xC001400A 


0xC001400B 


0xC001400C 


0xC001400D 


DECIMAL CODE 


-1073659899 


-1073659898 


-1073659897 


-1073659896 


-1073659895 


-1073659894 


-1073659893 


-1073659892 


-1073659891 


SYMBOLIC NAME 


DTS_E_UNKNOWNCONNEC 
TIONMANAGERTY PE 


DTS_E_COLLECTIONCOULD 
NTADD 


DTS_E_ODBCERRORENV 


DTS_E_ODBCERRORDBC 


DTS_E_ODBCERRORCONNE 
CT 


DTS_E_CONNECTIONMANA 
GERQUALIFIERALREADYSET 


DTS_E_CONNECTIONMANA 
GERQUALIFIERNOTSET 


DTS_E_CONNECTIONMANA 
GERQUALIFIERNOTSUPPOR 
TED 


DTS_E_CANNOTCLONECON 
NECTIONMANAGER 


DESCRIPTION 


The connection type "%1" 
specified for connection 
manager "%2" is not 
recognized as a valid 
connection manager type. 
This error is returned when 
an attempt >is made to 
create a connection 
manager for an unknown 
connection type. Check the 
spelling in the connection 
type name. 


An object was created but 
the attempt to add it toa 
collection failed. This can 
occur due to an out-of- 
memory condition. 


There was an error creating 
an Open Database 
Connectivity (ODBC) 
environment. 


There was an error creating 
an Open Database 
Connectivity (ODBC) 
database connection. 


There was an error trying to 
establish an Open Database 
Connectivity (ODBC) 
connection with the 
database server. 


The qualifier is already set 
on this instance of the 
connection manager. The 
qualifier may be set once 
per instance. 


The qualifier has not been 
set on this instance of the 
connection manager. 
Setting the qualifier is 
required to complete 
initialization. 


This connection manager 
does not support 
specification of qualifiers. 


Connection manager 
"0x%1" cannot be cloned 
for out-of- process 
execution. 


HEXADECIMAL CODE 


0xC001400E 


0xC001400F 


0xC0014010 


0xC0014011 


0xC0014012 


0xC0014013 


0xC0014014 


0xC0014015 


0xC0014016 


DECIMAL CODE 


-1073659890 


-1073659889 


-1073659888 


-1073659887 


-1073659886 


-1073659885 


-1073659884 


-1073659883 


-1073659882 


SYMBOLIC NAME 


DTS_E_NOSQLPROFILERDLL 


DTS_E_LOGFAILED 


DTS_E_LOGPROVIDERFAILE 
D 


DTS_E_SAVETOSQLSERVER_ 
OLEDB 


DTS_E_LOADFROMSQLSER 
VER_OLEDB 


DTS_E_REMOVEFROMSQLS 
ERVER_OLEDB 


DTS_E_EXISTSONSQLSERVE 
R_OLEDB 


DTS_E_CONNECTIONSTRIN 
G 


DTS_E_FROMEXECISNOTCHI 
LD 


DESCRIPTION 


The log provider for SQL 
Server Profiler was unable 
to load pfclnt.dll. Please 
check that SQL Server 
Profiler is installed. 


The SSIS logging 
infrastructure failed with 
error code 0x%1!8.8X!. This 
error indicates that this 
logging error is not 
attributable to a specific log 
provider. 


The SSIS logging provider 
"%1" failed with error code 
0x%2!8.8X! (%3). This 
indicates a logging error 
attributable to the specified 
log provider. 


The SaveToSQLServer 
method has encountered 
OLE DB error code 
0x%1!8.8X! (%2). The SQL 
statement that was issued 
has failed. 


The LoadFromSQLServer 
method has encountered 
OLE DB error code 
0x%1!8.8X! (%2). The SQL 
statement that was issued 
has failed. 


The RemoveFromSQLServer 
method encountered OLE 
DB error code 0x%1!8.8X! 
(%2) The SQL statement 
that was issued has failed. 


The ExistsOnSQLServer 
method has encountered 
OLE DB error code 
0x%1!8.8X! (%2). The SQL 
statement issued has failed. 


OLE DB has failed making a 
database connection when 
using the supplied 
connection string. 


When adding a precedence 
constraint, a From 
executable was specified 
that is not a child of this 
container. 


HEXADECIMAL CODE 


0xC0014017 


0xC0014018 


0xC0014019 


0xC001401A 


0xC001401B 


0xC001401C 


0xC001401D 


0xC001401E 


DECIMAL CODE 


-1073659881 


-1073659880 


-1073659879 


-1073659878 


-1073659877 


-1073659876 


-1073659875 


-1073659874 


SYMBOLIC NAME 


DTS_E_TOEXECISNOTCHILD 


DTS_E_ODBCTRANSACTION 
ENLIST 


DTS_E_CONNECTIONOFFLI 
NE 


DTS_E_BEGINTRANSACTION 


DTS_E_SETQUALIFIERDESIG 
NTIMEONLY 


DTS_E_SQLPERSISTENCEVER 
SION 


DTS_E_CONNECTIONVALID 
ATIONFAILED 


DTS_E_INVALIDFILENAMEIN 
CONNECTION 


DESCRIPTION 


When adding a precedence 
constraint, the To 
executable specified is not a 
child of this container. 


There was an error trying 
enlist an ODBC connection 
in a transaction. The 
SQLSetConnectAttr failed to 
set the 
SQL_ATTR_ENLIST_IN_DTC 
attribute. 


The connection manager 
"%1" will not acquire a 
connection because the 
package OfflineMode 
property is TRUE. When the 
OfflineMode is TRUE, 
connections cannot be 
acquired. > 


The SSIS Runtime has failed 
to start the distributed 
transaction due to error 
0x%1!8.8X! "%2". The DTC 
transaction failed to start. 
This could occur because 
the MSDTC >Service is not 
running. 


The SetQualifier method 
cannot be called on a 
connection manager during 
package execution. This 
method is used at design- 
time only. 


Storing or modifying 
packages in SQL Server 
requires the SSIS runtime 
and database to be the 
same version. Storing 
packages in earlier versions 
is not supported. 


Connection "%1" failed 
validation. 


The file name "%1" specified 
in the connection was not 
valid. 


HEXADECIMAL CODE 


0xC001401F 


0xC0014020 


0xC0014021 


0xC0014022 


0xC0014023 


0xC0014024 


0xC0014025 


DECIMAL CODE 


-1073659873 


-1073659872 


-1073659871 


-1073659870 


-1073659869 


-1073659868 


-1073659867 


SYMBOLIC NAME 


DTS_E_MULTIPLEFILESONRE 
TAINEDCONNECTION 


DTS_E_ODBCERROR 


DTS_E_PRECEDENCECONST 
RAINT 


DTS_E_FAILEDPOPNATIVEFE 
E 


DTS_E_GETENUMERATOR 


DTS_E_CANTGETCERTDATA 


DTS_E_CANTCREATECERTCO 
NTEXT 


DESCRIPTION 


Multiple file names cannot 
be specified on a 
connection when the Retain 
property is TRUE. Vertical 
bars were found on the 
connection string, meaning 
>multiple file names are 
being specified and, in 
addition, the Retain 
property is TRUE. 


An ODBC error %1!d! has 
occurred. 


There was an error in the 
precedence constraint 
between "%1" and "%2". 


Failed to populate the 
ForEachEnumerator|nfos 
collection with native 
ForEachEnumerators with 
the following error code: 
%1. 


The GetEnumerator method 
of the ForEach Enumerator 
has failed with error 
0x%1!8.8X! "%2". This 
occurs when the ForEach 
Enumerator cannot 
enumerate. 


The raw certificate data 
cannot be obtained from 
the supplied certificate 
object (error: %1). This 
occurs when 
CPackage::put_CertificateOb 
ject cannot instantiate the 
>ManagedHelper object, 
when the ManagedHelper 
object fails, or when the 
ManagedHelper object 
returns a malformed array. 


Failed to create certificate 
context (error: %1). This 
occurs in 
CPackage::put_CertificateOb 
ject or 
CPackage::LoadFromXML 
when the corresponding 
CryptoAPI function > fails. 


HEXADECIMAL CODE 


0xC0014026 


0xC0014027 


0xC0014028 


0xC0014029 


0xC001402A 


0xC001402B 


0xC001402C 


0xC001402D 


DECIMAL CODE 


-1073659866 


-1073659865 


-1073659864 


-1073659863 


-1073659862 


-1073659861 


-1073659860 


-1073659859 


SYMBOLIC NAME 


DTS_E_CANTOPENCERTSTO 
RE 


DTS_E_CANTFINDCERTBYN 
AME 


DTS_E_CANTFINDCERTBYH 
ASH 


DTS_E_INVALIDCERTHASHF 
ORMAT 


DTS_E_CANTACCESSARRAY 
DATA 


DTS_E_CREATEMANAGEDH 
ELPERFAILED 


DTS_E_OLEDBTRANSACTIO 
NENLIST 


DTS_E_SIGNPACKAGEFAILE 
D 


DESCRIPTION 


Opening MY certificate 
store failed with error 

"%1" This occurs in 
CPackage::LoadUserCertifica 
teByName and 
CPackage::LoadUserCertifica 
teByHash. 


The certificate specified by 
name in MY store cannot 
be found (error: %1). This 
occurs in 
CPackage::LoadUserCertifica 
teByName. 


Unable to find the specified 
certificate by hash in "MY" 
store (error: %1). Occurs in 
CPackage::LoadUserCertifica 
teByHash. 


The hash value is not a 
one-dimensional array of 
bytes (error: %1). This 
occurs in 
CPackage::LoadUserCertifica 
teByHash. 


The data in the array 
cannot be accessed (error: 
%1). This error can occur 
wherever 
GetDataFromSafeArray is 
called. 


The SSIS managed helper 
object failed during creation 
with error 0x%1!8.8X! "%2". 
This occurs whenever 
CoCreatelnstance 
CLSID_DTSManagedHelper 
fails. 


The SSIS Runtime has failed 
to enlist the OLE DB 
connection in a distributed 
transaction with error 
0x%1!8.8X! "%2". 


Package signing failed with 
error 0x%1!8.8X! "%2". This 
occurs when the 
ManagedHelperSignDocum 
ent method fails. 


HEXADECIMAL CODE 


0xC001402E 


0xC001402F 


0xC0014030 


0xC0014031 


0xC0014032 


0xC0014033 


0xC0014034 


0xC0014035 


DECIMAL CODE 


-1073659858 


-1073659857 


-1073659856 


-1073659855 


-1073659854 


-1073659853 


-1073659852 


-1073659851 


SYMBOLIC NAME 


DTS_E_CHECKENVELOPEFAI 
LED 


DTS_E_GETXMLSOURCEFAIL 
ED 


DTS_E_PACKAGEVERIFICATI 
ONFAILED 


DTS_E_GETKEYFROMCERTF 
AILED 


DTS_E_INVALIDSIGNATURE 


DTS_E_UNTRUSTEDSIGNAT 
URE 


DTS_E_TRANSACTIONENLIS 
TNOTSUPPORTED 


DTS_E_PACKAGEPROTECT 


DESCRIPTION 


Failed to check for XML 
signature envelope in 
package XML with error 
0x%1!8.8X! "%2". This 
occurs in 
CPackage::LoadFromXML. 


Failed to obtain XML source 
from XML DOM object with 
error 0x%1!8.8X! "%2". This 
occurs when 
IXMLDOMDocument::get_x 
ml fails. 


The cryptographic signature 
of the package failed 
verification due to error 
0x%1!8.8X! "%2". This 
occurs when the signature 
verification operation fails. 


Failed to obtain 
cryptographic key pair 
associated with the 
specified certificate with 
error 0x%1!8.8X! "%2". 
Verify that you have the key 
pair for which the 

> certificate was issued. This 
error usually occurs when 
trying to sign a document 
using a certificate for which 
the person does not have 
the private key. 


The digital signature is not 
valid. The contents of the 
package have been 
modified. 


The digital signature is valid; 
however the signer is not 
trusted and, therefore, 
authenticity cannot be 
guaranteed. 


The connection does not 
support enlisting in 
distributed transaction. 


Failed to apply package 
protection with error 
0x%1!8.8X! "%2". This error 
occurs when saving to Xml. 


HEXADECIMAL CODE 


0xC0014036 


0xC0014037 


0xC0014038 


0xC0014039 


0xC001403A 


0xC001403B 


0xC001403C 


0xC001403D 


DECIMAL CODE 


-1073659850 


-1073659849 


-1073659848 


-1073659847 


-1073659846 


-1073659845 


-1073659844 


-1073659843 


SYMBOLIC NAME 


DTS_E_PACKAGEUNPROTEC 
T 


DTS_E_PACKAGEPASSWOR 
D 


DTS_E_DUPLICATECONSTR 


AINT 


DTS_E_PACKAGELOADFAILE 
D 


DTS_E_PACKAGEOBJECTNO 
TENVELOPED 


DTS_E_JAGGEDEVENTINFO 


DTS_E_GETPACKAGEINFOS 


DTS_E_UNKNOWNLOGPRO 
VIDERTYPE 


DESCRIPTION 


Failed to remove package 
protection with error 
0x%1!8.8X! "%2". This 
occurs in the 
CPackage::LoadFromXML 
method. 


The package is encrypted 
with a password. The 
password was not specified, 
or is not correct. 


A precedence constraint 
already exists between the 
specified executables. More 
than one precedence 
constraint is not allowed. 


The package failed to load 
due to error 0x%1!8.8X! 
"%2". This occurs when 
CPackage::LoadFromXML 
fails. 


Failed to find package 
object in signed XML 
envelope with error 
0x%1!8.8X! "%2". This 
occurs when signed XML 
does not contain a SSIS 
package, as expected. 


The lengths of parameter 
names, types, and 
descriptions arrays are not 
equal. The lengths must be 
equal. This occurs when the 
lengths of the arrays are 
mismatched. There >should 
be one entry per parameter 
in each array. 


An OLE DB error 
0x%1!8.8X! (%2) occurred 
while enumerating 
packages. A SQL statement 
was issued and failed. 


The log provider type "%1" 
specified for log provider 
"%2" is not recognized as a 
valid log provider type. This 
error occurs when an 
attempt is made to create a 
>log provider for unknown 
log provider type. Verify the 
spelling in the log provider 
type name. 


HEXADECIMAL CODE 


0xC001403E 


0xC001403F 


0xC0014040 


0xC0014042 


0xC0014043 


0xC0014044 


0xC0014045 


0xC0014046 


0xC0014047 


DECIMAL CODE 


-1073659842 


-1073659841 


-1073659840 


-1073659838 


-1073659837 


-1073659836 


-1073659835 


-1073659834 


-1073659833 


SYMBOLIC NAME 


DTS_E_UNKNOWNLOGPRO 
VIDERTYPENOSUBS 


DTS_E_UNKNOWNCONNEC 
TIONMANAGERTYPENOSU 
BS 


DTS_E_PACKAGEREMOVEFA 
ILED 


DTS_E_FOLDERADDFAILED 


DTS_E_CREATEFOLDERONS 
QLSERVER_OLEDB 


DTS_E_FOLDERRENAMEFAIL 
ED 


DTS_E_RENAMEFOLDERON 
SQLSERVER_OLEDB 


DTS_E_FOLDERDELETEFAILE 
D 


DTS_E_REMOVEFOLDERFR 
OMSQLSERVER_OLEDB 


DESCRIPTION 


The log provider type is not 
recognized as a valid log 
provider type. This error 
occurs when an attempt is 
made to create a log 
provider for unknown log 

> provider type. Verify the 
spelling in the log provider 
type name. 


The connection type 
specified for connection 
manager is not a valid 
connection manager type. 
This error occurs when an 
attempt is made to create a 
>connection manager for 
unknown connection type. 
Verify the spelling of the 
connection type name. 


An error was encountered 
when trying to remove the 
package "%1" from SQL 
Server. 


An error was encountered 
when trying to create a 
folder on SQL Server 
named "%1" in folder "%2". 


The 
CreateFolderOnSQLServer 
method has encountered 
OLE DB error code 
0x%1!8.8X! (%2) The SQL 
statement issued has failed. 


An error occurred when 
renaming folder " %1\\%2" 
to "%1\\%3" on SQL Server. 


The 
RenameFolderOnSQLServer 
method encountered OLE 
DB error code 0x%1!8.8X! 
(%2). The SQL statement 
issued has failed. 


Error deleting SQL Server 
folder "%1". 


The 
RemoveFolderOnSQLServer 
method encountered OLE 
DB error code 0x%1!8.8X! 
(%2). The SQL statement 
issued has failed. 


HEXADECIMAL CODE 


0xC0014048 


0xC0014049 


0xC001404A 


0xC001404B 


0xC001404C 


0xC001404D 


0xC001404E 


0xC001404F 


0xC0014050 


0xC0014051 


DECIMAL CODE 


-1073659832 


-1073659831 


-1073659830 


-1073659829 


-1073659828 


-1073659827 


-1073659826 


-1073659825 


-1073659824 


-1073659823 


SYMBOLIC NAME 


DTS_E_INVALIDPATHTOPAC 
KAGE 


DTS_E_FOLDERNOTFOUND 


DTS_E_FINDFOLDERONSQL 
SERVER_OLEDB 


DTS_E_LOPENLOGFAILED 


DTS_E_GETCONNECTIONIN 
FOS 


DTS_E_VARIABLEDEADLOCK 


DTS_E_NOTDISPENSED 


DTS_E_VARIABLESALREADY 
UNLOCKED 


DTS_E_VARIABLEUNLOCKFA 
ILED 


DTS_E_DISPENSEDREADON 
LY 


DESCRIPTION 


The specified package path 
does not contain a package 
name. This occurs when the 
path does not contain at 
least one backslash or one 
forward slash. 


Cannot find folder "%1". 


While trying to find a folder 
on SQL an OLE DB error 
was encountered with error 
code 0x%1!8.8X! (%2). 


The SSIS logging provider 
has failed to open the log. 
Error code: 0x%1!8.8X!. 


Failed to get 
ConnectionInfos collection 
with error 0x%1!8.8X! "%2". 
This error occurs when the 
call to 
IDTSApplication100::get_Co 
nnection|nfos fails. 


Deadlock detected while 
trying to lock variables. The 
locks cannot be acquired 
after 16 attempts. The locks 
timed out. 


The Variables collection has 
not been returned from the 
VariableDispenser. An 
operation was attempted 
that is only allowed on 
dispensed collections. 


This Variables collection has 
already been unlocked. The 
Unlock method is called 
only once on a dispensed 
Variables collection. 


One or more variables failed 
to unlock. 


The Variables collection was 
returned the from 
VariableDispenser and 
cannot be modified. Items 
cannot be added to or 
removed from dispensed 
collections. 


HEXADECIMAL CODE 


0xC0014052 


0xC0014053 


0xC0014054 


0xC0014055 


0xC0014056 


0xC0014057 


0xC0014059 


0xC001405A 


0xC001405B 


DECIMAL CODE 


-1073659822 


-1073659821 


-1073659820 


-1073659819 


-1073659818 


-1073659817 


-1073659815 


-1073659814 


-1073659813 


SYMBOLIC NAME 


DTS_E_VARIABLEALREADYO 
NREADLIST 


DTS_E_VARIABLEALREADYO 
NWRITELIST 


DTS_E_LOCKVARIABLEFORR 
EAD 


DTS_E_LOCKVARIABLEFOR 
WRITE 


DTS_E_CUSTOMEVENTCON 
FLICT 


DTS_E_EVENTHANDLERNOT 
ALLOWED 


DTS_E_UNSAFEVARIABLESA 
LREADYSET 


DTS_E_INVALIDPARENTPAC 
KAGEPATH 


DTS_E_VARIABLEDEADLOCK 
_READ 


DESCRIPTION 


The variable "%1" is already 
on the read list. A variable 
may only be added once to 
either the read lock list or 
the write lock list. 


The variable "%1" is already 
on the write list. A variable 
may only be added once to 
either the read lock list or 
the write lock list. 


Failed to lock variable "%1" 
for read access with error 
0x%2!8.8X! "%3". 


Failed to lock variable "%1" 
for read/write access with 
error 0x%2!8.8X! "%3". 


The custom event "%1" is 
already declared with a 
different parameter list. A 
task is trying to declare a 
custom event, which 
another task has already 
declared with a >different 
parameter list. 


The task providing the 
custom event "%1" does 
not allow this event to be 
handled in the package. The 
custom event was declared 
with AllowEventHandlers = 
FALSE. 


The VariableDispenser 
received an unsafe Variables 
collection. This operation 
cannot be repeated. 


GetPackagePath was called 
on the ForEachEnumerator 
but there was no 
ForEachLoop package path 
specified. 


A deadlock was detected 

while trying to lock variable 
"%1" for read access. A lock 
could not be acquired after 
16 attempts and timed out. 


HEXADECIMAL CODE 


0xC001405C 


0xC001405D 


0xC001405E 


0xC001405F 


0xC0014060 


0xC0014061 


0xC0014062 


0xC0014063 


DECIMAL CODE 


-1073659812 


-1073659811 


-1073659810 


-1073659809 


-1073659808 


-1073659807 


-1073659806 


-1073659805 


SYMBOLIC NAME 


DTS_E_VARIABLEDEADLOCK 
_READWRITE 


DTS_E_VARIABLEDEADLOCK 
_BOTH 


DTS_E_PACKAGEPASSWOR 
DEMPTY 


DTS_E_DECRYPTXML_PASS 
WORD 


DTS_E_DECRYPTPACKAGE_ 
USERKEY 


DTS_E_SERVERSTORAGEDIS 
ALLOWED 


DTS_E_LOADFROMSQLSER 
VER 


DTS_E_SIGNATUREPOLICYV 
IOLATION 


DESCRIPTION 


A deadlock was detected 
while trying to lock 
variables "%1" for 
read/write access. A lock 
cannot be acquired after 16 
attempts. The locks timed 
out. 


A deadlock was detected 
while trying to lock 
variables "%1" for read 
access and variables "%2" 
for read/write access. A lock 
cannot be acquired after 16 
attempts. >The locks timed 
out. 


The protection level of the 
package requires a 
password, but 
PackagePassword property 
is empty. 


Failed to decrypt an 
encrypted XML node 
because the password was 
not specified or not correct. 
Package load will attempt to 
continue without the 
encrypted information.> 


Failed to decrypt a package 
that is encrypted with a 
user key. You may not be 
the user who encrypted this 
package, or you are not 
using the same machine 
that was >used to save the 
package. 


The protection level, 
ServerStorage, cannot be 
used when saving to this 
destination. The system 
could not verify that the 
destination supports secure 
storage > capability. 


LoadFromSQLServer 
method has failed. 


The package cannot be 
loaded because the state of 
the digital signature violates 
signature policy. Error 
0x%1!8.8X! "%2" 


HEXADECIMAL CODE 


0xC0014064 


0xC0014065 


0xC0014100 


0xC0014101 


0xC0014103 


0xC0014104 


0xC001410E 


0xC0015001 


0xC0015002 


DECIMAL CODE 


-1073659804 


-1073659803 


-1073659648 


-1073659647 


-1073659645 


-1073659644 


-1073659634 


-1073655807 


-1073655806 


SYMBOLIC NAME 


DTS_E_SIGNATURENOTPRES 
ENT 


DTS_E_SQLPROFILERDLL_O 
NLY_X86 


DTS_E_NAMEALREADYADD 
ED 


DTS_E_NAMEALREADYEXIST 
S 


DTS_E_FAILEDDEPENDENCI 
ES 


DTS_E_INVALIDCHECKPOIN 
T_TRANSACTION 


DTS_E_CONNECTIONMANA 
GERJOINTRANSACTION 


DTS_E_BPDUPLICATE 


DTS_E_BPUNKNOWNID 


DESCRIPTION 


The package is not signed. 


The log provider for SQL 
Server Profiler was unable 
to load pfclnt.dll because it 
is only supported on 32-bit 
systems. 


The object cannot be added 
because another object with 
the same name already 
exists in the collection. Use 
a different name to resolve 
this error. 


The object name cannot be 
changed from "%1" to "%2" 
because another object in 
the collection already uses 
that name. Use a different 
name to resolve this error. 


There was an error 
enumerating the package 
dependencies. Check other 
messages for more 
information. 


The current package 
settings are not supported. 
Please change the 
SaveCheckpoints property 
or the TransactionOption 


property. 


The connection manager 
failed to defect from the 
transaction. 


The specified breakpoint ID 
already exists. This error 
occurs when a task calls 
CreateBreakpoint with the 
same ID multiple times. It is 
possible to create a 
breakpoint with >the same 
ID multiple times if the task 
calls RemoveBreakpoint on 
the first creation before 
creating the second one. 


The specified breakpoint ID 
does not exist. This error 
occurs when a task 
references a breakpoint that 
does not exist. 


HEXADECIMAL CODE 


0xC0015004 


0xC0015005 


0xC0015105 


0xC0016001 


0xC0016002 


0xC0016003 


0xC0016004 


0xC0016005 


0xC0016006 


DECIMAL CODE 


-1073655804 


-1073655803 


-1073655547 


-1073651711 


-1073651710 


-1073651709 


-1073651708 


-1073651707 


-1073651706 


SYMBOLIC NAME 


DTS_E_CANTWRITETOFILE 


DTS_E_NOROWSETRETURN 
ED 


DTS_E_DUMP_FAILED 


DTS_E_INVALIDURL 


DTS_E_INVALIDSCHEME 


DTS_E_WINHTTPCANNOTC 
ONNECT 


DTS_E_CONNECTIONTERMI 
NATED 


DTS_E_LOGINFAILURE 


DTS_E_INVALIDSERVERNAM 
E 


DESCRIPTION 


The file, "%1", could not be 
opened for writing. The file 
could be read-only, or you 
do not have the correct 
permissions. 


No result rowset is 
associated with the 
execution of this query. The 
result is not correctly 
specified. 


Debug dump files were not 
generated correctly. The 
hresult is 0x%1!8.8X!. 


The URL specified is not 
valid. This can happen when 
the server or proxy URL is 
null, or in an incorrect 
format. A valid URL format 
is in the form of 
https://ServerName:Port/>R 
esourcePath or 
https://ServerName:Port/Re 
sourcePath. 


The URL %1 is not valid. 
This can happen when a 
scheme other than http or 
https is specified, or the 
URL is in an incorrect 
format. A valid URL format 
is in the form of 
>https://ServerName:Port/R 
esourcePath or 
https://ServerName:Port/Re 
sourcePath. 


Connection to server %1 
cannot be established. This 
error can occur when the 
server does not exist, or the 
proxy settings are incorrect. 


The connection with the 
server has been reset or 
terminated. Try again later. 


The login attempt failed for 
"%1". This error occurs 
when the login credentials 
provided are incorrect. 
Verify the login credentials. 


The server name specified 
in the URL %1 cannot be 
resolved. 


HEXADECIMAL CODE 


0xC0016007 


0xC0016008 


0xC0016009 


0xC001600A 


0xC001600B 


0xC001600C 


0xC001600D 


0xC001600E 


0xC001600F 


0xC0016010 


DECIMAL CODE 


-1073651705 


-1073651704 


-1073651703 


-1073651702 


-1073651701 


-1073651700 


-1073651699 


-1073651698 


-1073651697 


-1073651696 


SYMBOLIC NAME 


DTS_E_PROXYAUTH 


DTS_E_SECUREFAILURE 


DTS_E_TIMEOUT 


DTS_E_CLIENTAUTH 


DTS_E_REDIRECTFAILURE 


DTS_E_SERVERAUTH 


DTS_E_WINHTTPUNKNOW 
NERROR 


DTS_E_UNKNOWNSTATUSC 
ODE 


DTS_E_WINHTTPNOTSUPPO 
RTED 


DTS_E_INVALIDTIMEOUT 


DESCRIPTION 


Proxy authentication failed. 
This error occurs when login 
credentials are not 
provided, or the credentials 
are incorrect. 


TLS/SSL certificate response 
obtained from the server 
was not valid. Cannot 
process the request. 


The request has timed out. 
This error can occur when 
the timeout specified was 
too short, or a connection 
to the server or proxy 
cannot be established. 
Ensure that the server and 
> proxy URL are correct. 


Client certificate is missing. 
This error occurs when the 
server is expecting a 
TLS/SSL client certificate 
and the user has provided 
an invalid certificate, or has 
not provided a >certificate. 
A client certificate must be 
configured for this 
connection. 


The specified server, URL 
%1, has a redirect and the 
redirect request failed. 


Server authentication failed. 
This error occurs when login 
credentials are not 
provided, or the credentials 
are incorrect. 


Request cannot be 
processed. Try again later. 


Server returned status code 
- %1!u! : %2. This error 
occurs when the server is 
experiencing problems. 


This platform is not 
supported by WinHttp 
services. 


Timeout value is not valid. 
Timeout should be in the 
range of %1!d! to %2!d! (in 
seconds). 


HEXADECIMAL CODE 


0xC0016011 


0xC0016012 


0xC0016013 


0xC0016014 


0xC0016015 


0xC0016016 


0xC0016017 


DECIMAL CODE 


-1073651695 


-1073651694 


-1073651693 


-1073651692 


-1073651691 


-1073651690 


-1073651689 


SYMBOLIC NAME 


DTS_E_INVALIDCHUNKSIZE 


DTS_E_CERTERROR 


DTS_E_FORBIDDEN 


DTS_E_WINHTTPOPEN 


DTS_E_LOPENCERTSTORE 


DTS_E_UNPROTECTXMLFAIL 
ED 


DTS_E_UNPROTECTCONNE 
CTIONSTRINGFAILED 


DESCRIPTION 


The chunk size is not valid. 
The ChunkSize property 
should be in the range of 
%1!d! to %2!d! (in KB). 


Error processing client 
certificate. This error can 
occur when the client 
certificate provided was not 
found in the Personal 
Certificate Store. Verify that 
the client >certificate is 
valid. 


Server returned error code 
"403 - Forbidden". This 
error can occur when the 
specified resource needs 
"https" access, but the 
certificate validity period 
has expired, the > certificate 
is not valid for the use 
requested, or the certificate 
has been revoked or 
revocation can not be 
checked. 


Error initializing HTTP 
session with proxy "%1". 
This error can occur when 
an invalid proxy was 
specified. HTTP connection 
manager only supports 
CERN-type proxies. 


Error opening certificate 
store. 


Failed to decrypt protected 
XML node "%1" with error 
0x%2!8.8X! "%3". You may 
not be authorized to access 
this information. This error 
occurs when there is a 
>cryptographic error. Verify 
that the correct key is 
available. 


Failed to decrypt protected 
connection string for server 
"%1" with error 0x%2!8.8X! 
"%3". You may not be 
authorized to access this 
information. This error 
>occurs when there is a 
cryptographic error. Verify 
that the correct key is 
available. 


HEXADECIMAL CODE 


0xC0016018 


0xC0016019 


0xC0016020 


0xC0016021 


0xC0016022 


0xC0016023 


0xC0016024 


0xC0016025 


0xC0016026 


DECIMAL CODE 


-1073651688 


-1073651687 


-1073651680 


-1073651679 


-1073651678 


-1073651677 


-1073651676 


-1073651675 


-1073651674 


SYMBOLIC NAME 


DTS_E_NEGATIVEVERSION 


DTS_E_PACKAGEMIGRATED 


DTS_E_PACKAGEMIGRATIO 
NFAILED 


DTS_E_PACKAGEMIGRATIO 
NMODULELOAD 


DTS_E_PACKAGEMIGRATIO 
NMODULE 


DTS_E_CANTDETERMINEW 
HICHPROPTOPERSIST 


DTS_E_CANTADDREMOVE 
WHENEXECUTING 


DTS_E_NODENOTFOUND 


DTS_E_COLLECTIONLOCKE 
D 


DESCRIPTION 


The version number cannot 
be negative. This error 
occurs when the 
VersionMajor, VersionMinor, 
or VersionBuild property of 
the package is set toa 
negative value. 


The package has been 
migrated to a later version 
during loading. It must be 
reloaded to complete the 
process. This is an internal 
error code. 


Package migration from 
version %1!d! to version 
%2!d! failed with error 
0x%3!8.8X! "%4". 


Package migration module 
has failed to load. 


Package migration module 
has failed. 


Unable to persist object 
using default persistence. 
This error occurs when the 
default persistence is unable 
to determine which objects 
are on the hosted > object. 


Cannot add or remove an 
element from a package in 
runtime mode. This error 
occurs when an attempt is 
made to add or remove an 
object from a collection 
while >the package is 
executing. 


The "%1" node cannot be 
found in custom default 
persistence. This error 
occurs if the default saved 
XML of an extensible object 
was changed in a way that 
a saved object is >no 
longer found, or if the 
extensible object itself 
changed. 


This collection cannot be 
modified during package 
validation or execution. 


HEXADECIMAL CODE 


0xC0016027 


0xC0016029 


0xC001602A 


0xC001602B 


0xC001602C 


0xC001602D 


0xC001602E 


0xC001602F 


0xC0016030 


0xC0016031 


0xC0016032 


0xC0016033 


DECIMAL CODE 


-1073651673 


-1073651671 


-1073651670 


-1073651669 


-1073651668 


-1073651667 


-1073651666 


-1073651665 


-1073651664 


-1073651663 


-1073651662 


-1073651661 


SYMBOLIC NAME 


DTS_E_COLLOCKED 


DTS_E_FTPNOTCONNECTED 


DTS_E_FTPERROR 


DTS_E_FTPINVALIDRETRIES 


DTS_E_LOADWININET 


DTS_E_FTPINVALIDCONNEC 
TIONSTRING 


DTS_E_FTPCREATEFOLDER 


DTS_E_FTPDELETEFOLDER 


DTS_E_FTPCHANGEFOLDER 


DTS_E_FTPFILESEMPTY 


DTS_E_FTPINVALIDLOCALP 
ATH 


DTS_E_FTPNOFILESTODELET 
E 


DESCRIPTION 


The "%1" collection cannot 
be modified during package 
validation or execution. 
"%2" cannot be added to 
the collection. 


Connection with the FTP 
server has not been 
established. 


An error occurred in the 
requested FTP operation. 
Detailed error description: 
%1. 


The number of retries is not 
valid. The number of retries 
should be between %1!d! 
and %2!dl. 


The FTP connection 
manager needs the 
following DLL to function: 
%1. 


The port specified in the 
connection string is not 
valid. The ConnectionString 
format is ServerName:Port. 
Port should be an integer 
value between %1!d! and 
>%2!dl. 


Creating folder "%1" ... %2. 


Deleting folder "%1" ... %2. 


Changing current directory 
to "%1". %2. 


No files to transfer. This 
error can occur when 
performing a Send or 
Receive operation and no 
files are specified for the 
transfer. 


Specified local path is not 
valid. Specify a valid local 

path. This can occur when 
the specified local path is 

null. 


No files specified to delete. 


HEXADECIMAL CODE 


0xC0016034 


0xC0016035 


0xC0016049 


0xC001604A 


0xC001604B 


0xC001604C 


0xC001604D 


0xC0016050 


0xC00160AA 


DECIMAL CODE 


-1073651660 


-1073651659 


-1073651639 


-1073651638 


-1073651637 


-1073651636 


-1073651635 


-1073651632 


-1073651542 


SYMBOLIC NAME 


DTS_E_WINHTTPCERTDECO 
DE 


DTS_E_WINHTTPCERTENCO 
DE 


DTS_E_CHECKPOINTMISMA 
TCH 


DTS_E_CHECKPOINTFILEAL 
READY EXISTS 


DTS_E_CHECKPOINTFILELO 
CKED 


DTS_E_LOPENCHECKPOINTFI 
LE 


DTS_E_CREATECHECKPOINT 
FILE 


DTS_E_FTPINVALIDPORT 


DTS_E_CONNECTTOSERVER 
FAILED 


DESCRIPTION 


Internal error occurred 
while loading the certificate. 
This error could occur when 
the certificate data is 
invalid. 


Internal error occurred 
while saving the certificate 
data. 


Checkpoint file "%1" does 
not match this package. The 
ID of the package and the 
ID in the checkpoint file do 
not match. 


An existing checkpoint file is 
found with contents that do 
not appear to be for this 
package, so the file cannot 
be overwritten to start 
saving new >checkpoints. 
Remove the existing 
checkpoint file and try 
again. This error occurs 
when a checkpoint file 
exists, the package is set to 
not use a checkpoint file, 
but to save checkpoints. 
The existing checkpoint file 
>will not be overwritten. 


The checkpoint file "%1" is 
locked by another process. 
This may occur if another 
instance of this package is 
currently executing. 


Checkpoint file "%1" failed 
to open due to error 
0x%2!8.8X! "%3". 


Checkpoint file "%1" failed 
during creation due to error 
0x%2!8.8X! "%3". 


The FTP Port contains an 

invalid value. The FTP Port 
value should be an integer 
between %1!d! and %2!d!. 


Connect to SSIS Service on 
machine "%1" failed: 


2. 


HEXADECIMAL CODE 


0xC0017002 


0xC0017003 


0xC0017004 


0xC0017005 


0xC0017006 


0xC0017007 


0xC0017008 


0xC0017009 


0xC001700A 


0xC001700C 


DECIMAL CODE 


-1073647614 


-1073647613 


-1073647612 


-1073647611 


-1073647610 


-1073647609 


-1073647608 


-1073647607 


-1073647606 


-1073647604 


SYMBOLIC NAME 


DTS_E_PROPERTYEXPRESSI 
ONSDISABLEDONVARIABLE 
S 


DTS_E_PROPERTYEXPRESSI 
ONEVAL 


DTS_E_PROPERTYEXPRESSI 
ONSET 


DTS_E_FORLOOPEVALEXPR 
ESSIONINVALID 


DTS_E_EXPRESSIONNOTBO 
OLEAN 


DTS_E_FORLOOPHASNOEX 
PRESSION 


DTS_E_FORLOOPASSIGNEX 
PRESSIONINVALID 


DTS_E_FORLOOPINITEXPRE 
SSIONINVALID 


DTS_E_INVALIDVERSIONNU 
MBER 


DTS_E_INVALIDVERNUMCA 
NTBENEGATIVE 


DESCRIPTION 


The Expression property is 
not supported on Variable 
objects. Use the 
EvaluateAsExpression 
property instead. 


The expression "%1" on 
property "%2" cannot be 
evaluated. Modify the 
expression to be valid. 


The result of the expression 
"%1" on property "%2" 
cannot be written to the 
property. The expression 
was evaluated, but cannot 
be set on the property. 


The evaluation expression 
for the loop is not valid. The 
expression needs to be 
modified. There should be 
additional error messages. 


The expression "%1" must 
evaluate to True or False. 
Change the expression to 
evaluate to a Boolean value. 


There is no expression for 
the loop to evaluate. This 
error occurs when the 
expression on the For Loop 
is empty. Add an 
expression. 


The assignment expression 
for the loop is not valid and 
needs to be modified. There 
should be additional error 
messages. 


The initialization expression 
for the loop is not valid and 
needs to be modified. There 
should be additional error 
messages. 


The version number in the 
package is not valid. The 
version number cannot be 
greater than current version 
number. 


The version number in the 
package is not valid. The 
version number is negative. 


HEXADECIMAL CODE 


0xC001700D 


0xC001700E 


0xC0019001 


0xC0019004 


0xC0019305 


0xC001A003 


0xC001A004 


0xC001B001 


DECIMAL CODE 


-1073647603 


-1073647602 


-1073639423 


-1073639420 


-1073638651 


-1073635325 


-1073635324 


-1073631231 


SYMBOLIC NAME 


DTS_E_PACKAGEUPDATEDIS 
ABLED 


DTS_E_EXPREVALTRUNCATI 
ONASERROR 


DTS_E_FAILEDSETEXECVALV 
ARIABLE 


DTS_E_VARIABLEEXPRESSIO 
NERROR 


DTS_E_UNSUPPORTEDSQLV 


ERSION 


DTS_E_TXNSPECINVALID 


DTS_E_INCOMPATIBLETRAN 
SACTIONCONTEXT 


DTS_E_NOTSUSPENDED 


DESCRIPTION 


The package has an older 
format version, but 
automatic package format 
upgrading is disabled. 


A truncation occurred 
during evaluation of the 
expression. 


The wrapper was unable to 
set the value of the variable 
specified in the 
ExecutionValueVariable 
property. 


The expression for variable 
"%1" failed evaluation. 
There was an error in the 
expression. 


The attempted operation is 
not supported with this 
database version. 


Transaction cannot be 
specified when a retained 
connection is used. This 
error occurs when Retain is 
set to TRUE on the 
connection manager, but 
AcquireConnection was 
>called with a non-null 
transaction parameter. 


Incompatible transaction 
context was specified for a 
retained connection. This 
connection has been 
established under a 
different transaction 
context. > Retained 
connections can be used 
under exactly one 
transaction context. 


Resume call failed because 
the package is not 
suspended. This occurs 
when the client calls 
resume, but the package is 
not suspended. 


HEXADECIMAL CODE 


0xC001B002 


0xC001B003 


0xC001C002 


0xC001C010 


0xC001C011 


0xC001C012 


0xC001C013 


0xC001F001 


DECIMAL CODE 


-1073631230 


-1073631229 


-1073627134 


-1073627120 


-1073627119 


-1073627118 


-1073627117 


-1073614847 


SYMBOLIC NAME 


DTS_E_ALREADYEXECUTING 


DTS_E_NOTEXECUTING 


DTS_E_INVALIDFILE 


DTS_E_VALUEINDEXNOTINT 
EGER 


DTS_E_VALUEINDEXNEGATI 
VE 


DTS_E_FOREACHVARIABLE 
MAPPING 


DTS_E_OBJECTNOTINFOREA 
CHLOOP 


DTS_E_FAILEDSYSTEMVARIA 
BLEREMOVE 


DESCRIPTION 


Execute call failed because 
the executable is already 
executing. This error occurs 
when the client calls Execute 
on a container that is still 
executing from the last 

> Execute call. 


Suspend or Resume call 
failed because the 
executable is not executing, 
or is not the top-level 
executable. This occurs 
when the client calls 
Suspend or Resume on an 
>executable that is not 
currently processing an 
Execute call. 


The file specified in the For 
Each File enumerator is not 
valid. Check that the file 
specified in the For Each File 
enumerator exists. 


The value index is not an 
integer . Mapping a For 
Each Variable number %1!d! 
to the variable "%2". 


The value index is negative. 
The ForEach Variable 
Mapping number %1!d! to 
variable "%2". 


ForEach Variable Mapping 
number %1!d! to variable 
"%2" cannot be applied. 


Failure when adding an 
object to a 
ForEachPropertyMapping 
that is not a direct child of 
the ForEachLoop container. 


Failed to remove a system 
variable. This error occurs 
when removing a variable 
that is a required variable. 
Required variables are 
variables that are created 
>by the runtime for 
communicating between 
tasks and the runtime. 


HEXADECIMAL CODE 


0xC001F002 


0xC001F003 


0xC001F004 


0xC001F006 


0xC001F008 


0xC001F009 


0xC001F010 


0xC001F011 


0xC001F021 


0xC001F022 


DECIMAL CODE 


-1073614846 


-1073614845 


-1073614844 


-1073614842 


-1073614840 


-1073614839 


-1073614832 


-1073614831 


-1073614815 


-1073614814 


SYMBOLIC NAME 


DTS_E_CHANGESYSTEMVAR 
IABLEREADONLY FAILED 


DTS_E_CHANGESYSTEMVAR 
IABLENAMEFAILED 


DTS_E_CHANGESYSTEMVAR 
IABLENAMESPACEFAILED 


DTS_E_EVENTHANDLERNA 


MEREADONLY 


DTS_E_PATHUNKNOWN 


DTS_E_RUNTIMEVARIABLET 
YPECHANGE 


DTS_E_INVALIDSTRING 


DTS_E_INVALIDOBJECTNA 
ME 


DTS_E_PROPERTYREADONL 
Y 


DTS_E_FAILEDGETTYPEINFO 


DESCRIPTION 


Changing the property of a 
variable failed because it is a 
system variable. System 
variables are read-only. 


Changing the name of a 
variable failed because it is a 
system variable. System 
variables are read-only. 


Changing the namespace of 
a variable failed because it is 
a system variable. System 
variables are read-only. 


Changing the event handler 
name failed. Event handler 
names are read-only. 


Cannot retrieve path to 
object. This is a system 
error. 


The type of the value being 
assigned to variable "%1" 
differs from the current 
variable type. Variables may 
not change type during 
execution. Variable types 
are >strict, except for 
variables of type Object. 


Invalid characters in string: 
"%1". This occurs when a 
string supplied for a 
property value contains 
unprintable characters. 


SSIS object name is invalid. 
More specific errors would 
have been raised explaining 
the exact naming problem. 


The property "%1" is read 
only. This occurs when a 
change to a read-only 
property is attempted. 


The object does not 
support type information. 
This occurs when the 
runtime attempts to get the 
type information from an 
object to populate the 
Properties collection. >The 
object must support type 
information. 


HEXADECIMAL CODE 


0xC001F023 


0xC001F024 


0xC001F025 


0xC001F026 


0xC001F027 


0xC001F028 


0xC001F029 


0xC001F02A 


0xC001F02C 


DECIMAL CODE 


-1073614813 


-1073614812 


-1073614811 


-1073614810 


-1073614809 


-1073614808 


-1073614807 


-1073614806 


-1073614804 


SYMBOLIC NAME 


DTS_E_FAILEDPROPERTYGE 
T 


DTS_E_FAILEDPROPERTYGE 
T_ERRORINFO 


DTS_E_FAILEDPROPERTYSET 


DTS_E_FAILEDPROPERTYSET 
_ERRORINFO 


DTS_E_PROPERTYWRITEON 
LY 


DTS_E_NODISPATCH 


DTS_E_NOCONTAININGTYP 
ELIB 


DTS_E_INVALIDTASKMONIK 
ER 


DTS_E_FAILEDCREATEXMLD 
OCUMENT 


DESCRIPTION 


An error occurred while 
retrieving the value of 
property "%1". The error 
code is 0x%2!8.8X!. 


An error occurred while 
retrieving the value of 
property "%1". The error 
code is 0x%2!8.8X! "%3". 


An error occurred while 
setting the value of 
property "%1". The error 
returned is 0x%2!8.8X!. 


An error occurred while 
setting the value of 
property "%1". The error 
returned is 0x%2!8.8X! 
"%3". 


The property "%1" is write- 
only. This error occurs when 
trying to retrieve the value 
of a property through a 
property object, but the 
property is write-only. 


The object does not 
implement |Dispatch. This 
error occurs when a 
property object or 
properties collection 
attempts to access an 
IDispatch interface on an 
object. 


Unable to retrieve the type 
library of the object. This 
error occurs when the 
Properties collection 
attempts to retrieve the 
type library for an object 
through its >IDispatch 
interface. 


Cannot create a task from 
XML for task "%1!s!", type 
"%2!s!" due to error 
0x%3!8.8X! "%Als!". 


Failed to create an XML 
document "%1". 


HEXADECIMAL CODE 


0xC001F02D 


0xC001F02E 


0xC001F02F 


0xC001F030 


0xC001F031 


0xC001F032 


0xC001F033 


0xC001F036 


0xC001F038 


DECIMAL CODE 


-1073614803 


-1073614802 


-1073614801 


-1073614800 


-1073614799 


-1073614798 


-1073614797 


-1073614794 


-1073614792 


SYMBOLIC NAME 


DTS_E_PMVARPROPTYPESD 
IFFERENT 


DTS_E_PMINVALIDPROPMA 
PTARGET 


DTS_E_COULDNOTRESOLVE 
PACKAGEPATH 


DTS_E_PMNODESTPROPERT 
Y 


DTS_E_INVALIDPROPERTYM 
APPINGSFOUND 


DTS_E_AMBIGUOUSVARIAB 
LENAME 


DTS_E_DESTINATIONOBJEC 
TPARENTLESS 


DTS_E_INVALIDPROPERTYM 
APPING 


DTS_E_PMFAILALERTREMO 
VE 


DESCRIPTION 


An error occurred because 
there is a property mapping 
from a variable to a 
property with a different 
type. The property type 
must match the variable 
type. 


Attempted to set property 
mapping to target 
unsupported object type. 
This error occurs when 
passing an unsupported 
object type to a property 


mapping. 


Cannot resolve a package 
path to an object in the 

package "%1". Verify that 
the package path is valid. 


The destination property 
for the property map is 
empty. Set the destination 
property name. 


The package failed to 
restore at least one 


property mapping. 


The variable name is 
ambiguous because 
multiple variables with this 
name exist in different 
namespaces. Specify 
namespace-qualified name 
to prevent ambiguity. 


The destination object in a 
property mapping has no 
parent. The destination 
object is not a child of any 
sequence container. It may 
have been removed from 
the > package. 


The property mapping is 
not valid. The mapping is 
ignored. 


Failure when alerting 
property mappings that a 
target is being removed. 


HEXADECIMAL CODE 


0xC001F03A 


0xC001F040 


0xC001F041 


0xC001F080 


0xC001F081 


0xC001F082 


0xC001F083 


DECIMAL CODE 


-1073614790 


-1073614784 


-1073614783 


-1073614720 


-1073614719 


-1073614718 


-1073614717 


SYMBOLIC NAME 


DTS_E_INVALIDFOREACHPR 
OPERTYMAPPING 


DTS_E_PMPROPERTYINVALI 
D 


DTS_E_INVALIDTASKMONIK 
ERNOPARAM 


DTS_E_COULDNOTREPLACE 
CHECKPOINTFILE 


DTS_E_CHECKPOINTFILENO 
TSPECIFIED 


DTS_E_CHECKPOINTLOADX 
ML 


DTS_E_LOADCHECKPOINT 


DESCRIPTION 


An invalid property 
mapping is found on the 
For Each Loop. This occurs 
when the ForEach property 
mapping fails to restore. 


A destination property was 
specified on a property 
mapping that is invalid. This 
occurs when a property is 
specified on a destination 
object that in not found on 
that > object. 


Cannot create a task from 
XML. This occurs when the 
runtime is unable to resolve 
the name to create a task. 
Verify that the name is 
correct. 


Cannot replace the existing 
checkpoint file with the 
updated checkpoint file. The 
checkpoint was successfully 
created in a temporary file, 
but overwriting >the 
existing file with the new file 
failed. 


The package is configured 
to always restart from a 
checkpoint, but checkpoint 
file is not specified. 


The attempt to load the 
XML checkpoint file "%1" 
failed with error 0x%2!8.8X! 
"%3". Check that the file 
name specified is correct, 
and that the file exists. 


The package failed during 
execution because the 
checkpoint file cannot be 
loaded. Further execution of 
the package requires a 
checkpoint file. This error 
usually occurs >when the 
CheckpointUsage property 
is set to ALWAYS, which 
specifies that the package 
always restarts. 


HEXADECIMAL CODE 


0OxC001F185 


0xC001F186 


0xC001F187 


0xC001F188 


0xC001F189 


0OxC001F18A 


0xC001F200 


DECIMAL CODE 


-1073614459 


-1073614458 


-1073614457 


-1073614456 


-1073614455 


-1073614454 


-1073614336 


SYMBOLIC NAME 


DTS_E_NOEVALEXPRESSION 


DTS_E_EXPREVALASSIGNME 
NTTYPEMISMATCH 


DTS_E_EXPREVALASSIGNME 
NTTOREADONLYVARIABLE 


DTS_E_EXPREVALASSIGNME 
NTVARIABLELOCKFORWRIT 
EFAILED 


DTS_E_EXPREVALRESULTTYP 
ENOTSUPPORTED 


DTS_E_EXPREVALRESULTTYP 
ECONVERSIONFAILED 


DTS_E_DTSNAME_NOTNULL 


DESCRIPTION 


The evaluation condition 
expression on the For Loop 
"%1" is empty. There must 
be a Boolean evaluation 
expression in the For Loop. 


The result of the 
assignment expression "%1" 
cannot be converted to a 
type that is compatible with 
the variable that it was 
assigned to. 


Error using a read-only 
variable "%1" in an 
assignment expression. The 
expression result cannot be 
assigned to the variable 
because the variable is 
>read only. Choose a 
variable that can be written 
to, or remove the 
expression from this 
variable. 


Cannot evaluate expression 
"%1" because the variable 
"%2." does not exist or 
cannot be accessed for 
writing. The expression 
result cannot be >assigned 
to the variable because the 
variable was not found, or 
could not be locked for 
write access. 


The expression "%1" has a 
result type of "%2", which 
cannot be converted to a 
supported type. 


The conversion of the result 
of the expression"%1" from 
type "%2" to a supported 
type failed with error code 
0x%3!8.8X!. An unexpected 
error occurred >when 
trying to convert the 
expression result to a type 
supported by the runtime 
engine, even though the 
type conversion is 
supported. 


The object name is not 
valid. The name cannot be 
set to NULL. 


HEXADECIMAL CODE 


0xC001F201 


0xC001F202 


0xC001F203 


0xC001F204 


OxC001F205 


0xC001F206 


0xC001F207 


0xC001F208 


0xC001F209 


0xC001F420 


0OxC001F422 


0xC001F423 


0xC001F424 


DECIMAL CODE 


-1073614335 


-1073614334 


-1073614333 


-1073614332 


-1073614331 


-1073614330 


-1073614329 


-1073614328 


-1073614327 


-1073613792 


-1073613790 


-1073613789 


-1073613788 


SYMBOLIC NAME 


DTS_E_DTSNAME_NOTEMPT 
Y 


DTS_E_DTSNAME_LEGAL 


DTS_E_DTSNAME_PRINTABL 
E 


DTS_E_DTSNAME_NOLEAD 
WHITESP 


DTS_E_DTSNAME_NOTRAIL 
WHITESP 


DTS_E_DTSNAME_BEGINSW 
ITHALPHA 


DTS_E_DTSNAME_BEGINSW 
ITHALPHAUNDERBAR 


DTS_E_DTSNAME_ALPHADI 
GITUNDERBAR 


DTS_E_DTSNAME_VALIDFIL 
ENAME 


DTS_E_FAILLOADINGPROPE 
RTY 


DTS_E_NODELISTENUM_IN 
VALIDCONNMGRTYPE 


DTS_E_NODELISTENUM_XP 
ATHISEMPTY 


DTS_E_NODELISTENUM_IN 
VALIDDATANODE 


DESCRIPTION 


The object name is not 
valid. The name cannot be 
empty. 


The object name "%1" is not 
valid. The name cannot 
contain any of the following 
characters: /\:[].= 


Object name "%1" is not 
valid. The name cannot 
contain control characters 
that render it unprintable. 


Object name "%1" is not 
valid. Name cannot begin 
with a whitespace. 


Object name "%1" is not 
valid. Name cannot end 
with a whitespace. 


Object name "%1" is not 
valid. Name must begin 
with an alphabetical 
character. 


Object name "%1" is not 
valid. Name must begin 
with an alphabetical 

character or underscore 


Object name "%1" is not 
valid. Name must contain 
only alphanumeric 
characters or underscores 


Object name "%1" is not 
valid. The name cannot 
contain any of the following 
characters: /\:?"< > | 


Failed to load the value 
property "%1" using default 
persistence. 


Connection manager "%1" 
is not of type "%2" 


"%1" is empty 


Invalid data node in the 
nodelist enumerator section 


HEXADECIMAL CODE 


OxC001F425 


0xC001F427 


0xC001F428 


OxC001F429 


OxC00220DE 


OxC00220DF 


OxC00220E0 


OxC00220E2 


OxC00220E3 


OxC00220E4 


0xC0024102 


0xC0024104 


DECIMAL CODE 


-1073613787 


-1073613785 


-1073613784 


-1073613783 


-1073602338 


-1073602337 


-1073602336 


-1073602334 


-1073602333 


-1073602332 


-1073594110 


-1073594108 


SYMBOLIC NAME 


DTS_E_NODELISTENUM_NO 
ENUMERATORCREATED 


DTS_E_OPERATIONFAILCAC 
HEINUSE 


DTS_E_PROPERTYCANNOTB 
EMODIFIED 


DTS_E_PACKAGEUPGRADEF 
AILED 


DTS_E_TKEXECPACKAGE_U 
NABLETOLOADFILE 


DTS_E_TKEXECPACKAGE_U 
NSPECIFIEDPACKAGE 


DTS_E_TKEXECPACKAGE_U 
NSPECIFIEDCONNECTION 


DTS_E_TKEXECPACKAGE_IN 
CORRECTCONNECTIONMA 
NAGERTY PE 


DTS_E_TKEXECPACKAGE_U 
NABLETOLOADXML 


DTS_E_TKEXECPACKAGE_U 
NABLETOLOAD 


DTS_E_TASKVALIDATIONFAI 
LED 


DTS_E_TASKEXECUTEFAILED 


DESCRIPTION 


No enumerator can be 
created 


The operation failed 
because the cache is in use. 


The property cannot be 
modified. 


The package upgrade has 
failed. 


Error 0x%1!8.8X! while 
loading package file "%3". 
%2. 


The package is not 
specified. 


The connection is not 
specified. 


The connection manager 
"%1" has an unsupported 
type "%2". Only "FILE" and 
"OLEDB" connection 
managers are supported. 


Error 0x%1!8.8X! while 
loading package file "%3" 
into an XML document. %2. 


Error 0x%1!8.8X! while 
preparing to load the 
package. %2. 


The Validate method on the 
task failed, and returned 
error code 0x%1!8.8X! (%2). 
The Validate method must 
succeed and indicate the 
result using an "out" 
parameter. 


The Execute method on the 
task returned error code 
0x%1!8.8X! (%2). The 
Execute method must 
succeed, and indicate the 
result using an "out" 
parameter. 


HEXADECIMAL CODE 


0xC0024105 


0xC0024107 


0xC0024108 


0xC0024109 


0xC002410A 


0xC002410B 


0xC002410C 


DECIMAL CODE 


-1073594107 


-1073594105 


-1073594104 


-1073594103 


-1073594102 


-1073594101 


-1073594100 


SYMBOLIC NAME 


DTS_E_RETRIEVINGDEPEND 
ENCIES 


DTS_E_TASKVALIDATIONER 
ROR 


DTS_E_CONNECTIONSTRIN 
GFORMAT 


DTS_E_UNQUOTEDSEMICO 
LON 


DTS_E_LOGPROVIDERVALID 
ATIONFAILED 


DTS_E_INVALIDVALUEINAR 
RAY 


DTS_E_ENUMERATIONELEM 
ENTNOTENUMERABLE 


DESCRIPTION 


A failure occurred on task 
"%1": 0x%2!8.8X! while 
retrieving dependencies. 
The runtime was retrieving 
dependencies from the 
task's dependencies 
collection when the > error 
occurred. The task may 
have incorrectly 
implemented one of the 
dependency interfaces. 


There were errors during 
task validation. 


The connection string 
format is not valid. It must 
consist of one or more 
components of the form 
X=Y, separated by 
semicolons. This error 
occurs when a connection 
>string with zero 
components is set on 
database connection 
manager. 


The connection string 
components cannot contain 
unquoted semicolons. If the 
value must contain a 
semicolon, enclose the 
entire value in quotes. This 
error occurs when >values 
in the connection string 
contain unquoted 
semicolons, such as the 
InitialCatalog property. 


Validation of one or more 
log providers failed. The 
package cannot execute. 
The package does not 
execute when a log provider 
fails validation. 


Invalid value in array. 


An element of the 
enumerator returned by the 
ForEach Enumerator does 
not implement IEnumerator, 
contradicting the 
CollectionEnumerator 
property of the >ForEach 
Enumerator. 


HEXADECIMAL CODE 


0xC002410D 


0xC0029100 


0xC0029101 


0xC0029102 


0xC0029105 


0xC0029106 


0xC0029107 


0xC0029108 


0xC0029109 


0xC002910A 


0xC002910B 


DECIMAL CODE 


-1073594099 


-1073573632 


-1073573631 


-1073573630 


-1073573627 


-1073573626 


-1073573625 


-1073573624 


-1073573623 


-1073573622 


-1073573621 


SYMBOLIC NAME 


DTS_E_INVALIDENUMERAT 
ORINDEX 


DTS_E_AXTASK_MISSING_E 
NTRY_METHOD_NAME 


DTS_E_AXTASK_EMPTY_SCRI 
PT 


DTS_E_AXTASK_INITIALIZATI 
ON_WITH_WRONG_XML_E 
LEMENT 


DTS_E_AXTASK_HANDLER_N 
OT_FOUND 


DTS_E_AXTASKUTIL_ENUME 
RATE_LANGUAGES FAILED 


DTS_E_AXTASKUTIL_SCRIPT 
HOST_CREATE_FAILED 


DTS_E_AXTASKUTIL_SCRIPT 
HOSTINIT_FAILED 


DTS_E_AXTASKUTIL_ADDVA 
RIABLES_FAILED 


DTS_E_AXTASKUTIL_SCRIPT_ 
PARSING_FAILED 


DTS_E_AXTASKUTIL_MSG_B 
AD_FUNCTION 


DESCRIPTION 


The enumerator failed to 
retrieve element at index 
"%1!d!". 


Function not found. 


Function not found. 


ActiveX Script Task was 
initiated with a wrong XML 
element. 


Handler not found. 


An error occurred while 
attempting to retrieve the 
scripting languages installed 
on the system. 


An error occurred while 
creating the ActiveX script 
host. Verify that you have 
the script host installed 


properly. 


An error occurred while 
trying to instantiate the 
script host for the chosen 
language. Verify that the 
script language you have 
chosen is installed on >your 
system. 


An error occurred while 
adding the SSIS variables to 
the script host namespace. 
This might prevent the task 
from using SSIS variables in 
the script. 


A fatal error occurred while 
trying to parse the script 
text. Verify that the script 
engine for the chosen 
language is installed 


properly. 


The function name entered 
is not valid. Verify that a 
valid function name has 
been specified. 


HEXADECIMAL CODE 


0xC002910C 


0xC002910D 


0xC002910E 


0xC002910F 


0xC0029110 


0xC0029111 


0xC0029112 


0xC0029113 


0xC0029114 


0xC0029115 


0xC0029116 


0xC0029117 


0xC0029118 


0xC0029119 


DECIMAL CODE 


-1073573620 


-1073573619 


-1073573618 


-1073573617 


-1073573616 


-1073573615 


-1073573614 


-1073573613 


-1073573612 


-1073573611 


-1073573610 


-1073573609 


-1073573608 


-1073573607 


SYMBOLIC NAME 


DTS_E_AXTASKUTIL_EXECUT 
ION_FAILED 


DTS_E_AXTASKUTIL_ADDTY 
PELIB_FAILED 


DTS_E_BITASK_INITIALIZATI 
ON_WITH_WRONG_XML_E 
LEMENT 


DTS_E_BITASK_DATA_FILE_N 
OT_SPECIFIED 


DTS_E_BITASK_HANDLER_N 
OT_FOUND 


DTS_E_BITASK_CANNOT_AC 
QUIRE_CONNECTION 


DTS_E_BITASK_NO_CONNE 
CTION_MANAGER SPECIFIE 
D 


DTS_E_BITASK_INVALID_CO 
NNECTION 


DTS_E_BITASK_NULL_CONN 
ECTION 


DTS_E_BITASK_EXECUTE_FAI 
LED 


DTS_E_BITASK_CANNOT_RE 
TRIEVE_TABLES 


DTS_E_BITASK_CANNOT_RE 
TRIEVE_COLUMN_INFO 


DTS_E_BITASK_ERROR_IN_D 
B_OPERATION 


DTS_E_BITASK_INVALIDSOU 
RCECONNECTIONNAME 


DESCRIPTION 


An error occurred while 
executing the script. Verify 
that the script engine for 
the selected language is 
installed properly. 


An error occurred while 
adding the managed type 
library to the script host. 
Verify that the DTS 2000 
runtime is installed. 


Bulk Insert Task was 
initiated with a wrong XML 
element. 


Data file name not specified. 


Handler not found. 


Failed to acquire the 
specified connection: "%1". 


Attempt to obtain the 
Connection Manager failed. 


The connection is not valid. 


The connection is null. 


Execution failed. 


An error occurred while 
retrieving the tables from 
the database. 


An error occurred while 
retrieving the columns of 
the table. 


An error occurred in the 
database operation. 


The specified connection 
"%1" is either not valid, or 
points to an invalid object. 
To continue, specify a valid 
connection. 


HEXADECIMAL CODE 


0xC002911A 


0xC002911B 


0xC002911C 


0xC002911D 


0xC002911E 


0xC002911F 


0xC0029120 


0xC0029121 


0xC0029122 


0xC0029123 


0xC0029124 


0xC0029125 


0xC0029126 


0xC0029127 


DECIMAL CODE 


-1073573606 


-1073573605 


-1073573604 


-1073573603 


-1073573602 


-1073573601 


-1073573600 


-1073573599 


-1073573598 


-1073573597 


-1073573596 


-1073573595 


-1073573594 


-1073573593 


SYMBOLIC NAME 


DTS_E_BITASK_INVALIDDES 
TCONNECTIONNAME 


DTS_E_BITASK_DESTINATIO 
N_TABLE_NOT_SPECIFIED 


DTS_E_BITASK_ERROR_IN_L 
OAD_FROM_XML 


DTS_E_BITASK_ERROR_IN_S 
AVE_TO_XML 


DTS_E_BITASKUNMANCON 
NECTION_INVALID_CONNE 
CTION 


DTS_E_BITASKUNMANCON 
NECTION_EXECUTE_FAILED 


DTS_E_BITASKUNMANCON 
NECTION_CANNOT_RETRIE 
VE_TABLES 


DTS_E_BITASKUNMANCON 
NECTION_CANNOT_RETRIE 
VE_COLUMN_INFO 


DTS_E_BITASKUNMANCON 
NECTION_CANNOT_OPEN_ 
FILE 


DTS_E_BITASKUNMANCON 
NECTION_OEM_CONVERSI 
ON_FAILED 


DTS_E_BITASKUNMANCON 
NECTION_ERROR_IN_DB_O 
PERATION 


DTS_E_DTSPROCTASK_NOC 
ONNECTIONSPECIFIED 


DTS_E_DTSPROCTASK_CON 
NECTIONMANAGERNOTOL 
AP 


DTS_E_DTSPROCTASK_UNA 
BLETOLOCATECONNECTIO 
NMANAGER 


DESCRIPTION 


The destination connection 
specified is not valid. Supply 
a valid connection to 
continue. 


You must specify a table 
name to continue. 


Error occurred in 
LoadFromXML at the tag 
nog 


Error occurred in 
SaveToXML at the tag "%1". 


The connection is not valid. 


Execution failed. 


Error occurred while 
retrieving the tables from 
the database. 


Error occurred while 
retrieving the columns of 
the table. 


Error occurred while trying 
to open the data file. 


Cannot convert the input 
OEM file to the specified 
format. 


Error in database operation. 


No connection manager 
specified. 


Connection "%1" is not an 
Analysis Services 
connection. 


Unable to locate connection 
964" 


HEXADECIMAL CODE 


0xC0029128 


0xC0029129 


0xC002912A 


0xC002912B 


0xC002912C 


0xC002912D 


0xC002912E 


0xC002912F 


0xC0029130 


0xC0029131 


0xC0029132 


0xC0029133 


0xC0029134 


0xC0029135 


0xC0029136 


0xC0029137 


DECIMAL CODE 


-1073573592 


-1073573591 


-1073573590 


-1073573589 


-1073573588 


-1073573587 


-1073573586 


-1073573585 


-1073573584 


-1073573583 


-1073573582 


-1073573581 


-1073573580 


-1073573579 


-1073573578 


-1073573577 


SYMBOLIC NAME 


DTS_E_DTSPROCTASK_INVA 
LIDTASKDATANODEEXE 


DTS_E_DTSPROCTASK_INVA 
LIDTASKDATANODEPROC 


DTS_E_DTSPROCTASK_INVA 
LIDDDL 


DTS_E_DTSPROCTASK_INVA 
LIDDDLPROCESSINGCOM 
MANDS 


DTS_E_DTSPROCTASK_CAN 
NOTWRITEINAREADONLYV 
ARIABLE 


DTS_E_DTSPROCTASK_INVA 
LIDVARIABLE 


DTS_E_DTSPROCTASK_CON 
NECTIONNOTFOUND 


DTS_E_DTSPROCTASK_INVA 
LIDCONNECTION 


DTS_E_DTSPROCTASK_NON 
EXISTENTATTRIBUTE 


DTS_E_DTSPROCTASK_TRAC 
EHASBEENSTOPPED 


DTS_E_DTSPROCTASK_DDLE 
XECUTIONFAILED 


DTS_E_DTSPROCTASK_FILED 
OESNOTEXIST 


DTS_E_DTSPROCTASK_VARI 
ABLENOTDEFINED 


DTS_E_DTSPROCTASK_FILEC 
ONNECTIONNOTDEFINED 


DTS_E_EXEC2000PKGTASK _| 
NITIALIZATION_WITH_WRO 
NG_XML_ELEMENT 


DTS_E_EXEC2000PKGTASK_ 
HANDLER_NOT_FOUND 


DESCRIPTION 


Analysis Services Execute 
DDL task received an invalid 
task data node. 


Analysis Services Processing 
task received an invalid task 
data node. 


The DDL is not valid. 


The DDL found in 
ProcessingCommands is 
not valid. 


The Execution result cannot 
be saved in a read-only 
variable. 


Variable "%1" it's not 
defined. 


Connection Manager "%1" 
it's not defined. 


Connection Manager "%1" 
it's not a FILE Connection 
Manager. 


"%1" was not found during 
deserialization. 


The trace has been stopped 
due to an exception. 


Execution of DDL failed. 


There is no file associated 
with connection "%1". 


Variable "%1" is not defined. 


File connection "%1" is not 
defined. 


Execute DTS 2000 Package 
task is initiated with a 
wrong XML element. 


Handler not found. 


HEXADECIMAL CODE 


0xC0029138 


0xC0029139 


0xC002913A 


0xC002913B 


0xC002913C 


0xC002913D 


0xC002913E 


0xC002913F 


0xC0029140 


0xC0029141 


0xC0029142 


0xC0029143 


0xC0029144 


DECIMAL CODE 


-1073573576 


-1073573575 


-1073573574 


-1073573573 


-1073573572 


-1073573571 


-1073573570 


-1073573569 


-1073573568 


-1073573567 


-1073573566 


-1073573565 


-1073573564 


SYMBOLIC NAME 


DTS_E_EXEC2000PKGTASK_ 
PACKAGE_NAME_NOT_SPE 
CIFIED 


DTS_E_EXEC2000PKGTASK_ 
PACKAGE_ID_NOT_SPECIFIE 
D 


DTS_E_EXEC2000PKGTASK_ 
PACKAGE_VERSIONGUID_N 
OT_SPECIFIED 


DTS_E_EXEC2000PKGTASK_ 
SQLSERVER_NOT_SPECIFIE 
D 


DTS_E_EXEC2000PKGTASK_ 
SQL_USERNAME_NOT_SPEC 
IFIED 


DTS_E_EXEC2000PKGTASK_ 
FILE_NAME_NOT_SPECIFIED 


DTS_E_EXEC2000PKGTASK_ 
DTS2000CANTBEEMPTY 


DTS_E_EXEC2000PKGTASK_ 
ERROR_IN_PACKAGE_EXEC 
UTE 


DTS_E_EXEC2000PKGTASK_ 
SQLSERVER_NOT_AVAILABL 
E_NETWORK 


DTS_E_EXEC2000PKGTASK_ 
DATATYPE_NULL 


DTS_E_EXEC2000PKGTASK_ 
NULL_VALUE 


DTS_E_EXEC2000PKGTASK_ 
NULL_VALUE_ARGUMENT 


DTS_E_EXEC2000PKGTASK_ 
CLS_NOT_REGISTRED_EXCE 
PTION 


DESCRIPTION 


Package name is not 
specified. 


Package ID is not specified. 


Package version GUID is 
not specified. 


SQL Server is not specified. 


SQL Server user name not 
specified. 


Storage file name not 
specified. 


The DTS 2000 package 
property is empty. 


An error occurred while 
executing the DTS 2000 
package. 


Cannot load the available 
SQL Servers from the 
network. Check the 
network connection. 


The data type cannot be 
null. Please specify the 
correct data type to use for 
validating the value. 


Cannot validate a null 
against any data type. 


A required argument is null. 


To execute the DTS 2000 
Package task, start SQL 
Server Setup and use the 
Advanced button from the 
Components to Install page 
to select Legacy 
>Components. 


HEXADECIMAL CODE 


0xC0029145 


0xC0029146 


0xC0029147 


0xC0029148 


0xC0029149 


0xC002914A 


0xC002914B 


0xC002914C 


0xC002914D 


0xC002914E 


0xC002914F 


0xC0029150 


0xC0029151 


DECIMAL CODE 


-1073573563 


-1073573562 


-1073573561 


-1073573560 


-1073573559 


-1073573558 


-1073573557 


-1073573556 


-1073573555 


-1073573554 


-1073573553 


-1073573552 


-1073573551 


SYMBOLIC NAME 


DTS_E_EXEC2000PKGTASK_ 
NOT_PRIMITIVE_TYPE 


DTS_E_EXEC2000PKGTASK_ 
CONVERT_FAILED 


DTS_E_EXEC2000PKGTASK_ 
ERROR_IN_VALIDATE 


DTS_E_EXEC2000PKGTASK_ 
ERROR_IN_LOAD_FROM_X 
ML 


DTS_E_EXEC2000PKGTASK_ 
ERROR_IN_SAVE_TO_XML 


DTS_E_EXECPROCTASK_INV 
ALIDTIMEOUT 


DTS_E_EXECPROCTASK_CA 
NTREDIRECTIO 


DTS_E_EXECPROCTASK_PRO 
CESSHASTIMEDOUT 


DTS_E_EXECPROCTASK_EXE 
CUTABLENOTSPECIFIED 


DTS_E_EXECPROCTASK_STD 
OUTVARREADONLY 


DTS_E_EXECPROCTASK_STD 
ERRVARREADONLY 


DTS_E_EXECPROCTASK_REC 
EIVEDINVALIDTASKDATANO 
DE 


DTS_E_EXECPROCTASK_PRO 
CESSEXITCODEEXCEEDS 


DESCRIPTION 


"%1" is not a value type. 


Could not convert "%1" to 
Noga" 


Could not validate "%1" 
against "%2". 


Error occurred in 
LoadFromXML at the tag 
n96q 


Error occurred in 
SaveToXML at the tag "%1". 


The time-out value 
provided is not valid. 
Specify the number of 
seconds that the task allows 
the process to run. The 
minimum time-out is 0, 
which indicates >that no 
time-out value is used and 
the process runs to 
completion or until an error 
occurs. The maximum time- 
out is 2147483 (((2431) - 
1)/1000). 


Cannot redirect streams if 
the process can continue 
executing beyond the 
lifetime of the task. 


The process timed out. 


The executable is not 
specified. 


The standard out variable is 
read-only. 


The standard error variable 
is read-only. 


The Execute Process task 
received a task data node 
that is not valid. 


In Executing "%2" "%3" at 
"%1", The process exit code 
was "%4" while the 
expected was "%5". 


HEXADECIMAL CODE 


0xC0029152 


0xC0029153 


0xC0029154 


0xC0029156 


0xC0029157 


0xC0029158 


0xC0029159 


0xC002915A 


0xC002915B 


0xC002915C 


0xC002915D 


0xC002915E 


0xC002915F 


0xC0029160 


0xC0029163 


0xC0029165 


DECIMAL CODE 


-1073573550 


-1073573549 


-1073573548 


-1073573546 


-1073573545 


-1073573544 


-1073573543 


-1073573542 


-1073573541 


-1073573540 


-1073573539 


-1073573538 


-1073573537 


-1073573536 


-1073573533 


-1073573531 


SYMBOLIC NAME 


DTS_E_EXECPROCTASK_WO 
RKINGDIRDOESNOTEXIST 


DTS_E_EXECPROCTASK_FILE 
DOESNOTEXIST 


DTS_E_EXECPROCTASK_FILE 
NOTINPATH 


DTS_E_EXECPROCTASK_WO 
RKINGDIRECTORYDOESNO 
TEXIST 


DTS_E_EXECPROCTASK_ERR 
OREXECUTIONVALUE 


DTS_E_FSTASK_SYNCFAILED 


DTS_E_FSTASK_INVALIDDAT 
A 


DTS_E_FSTASK_DIRECTORYE 
XISTS 


DTS_E_FSTASK_PATHNOTVA 
LID 


DTS_E_FSTASK_DESTINATIO 
NNOTSET 


DTS_E_FSTASK_SOURCENOT 
SET 


DTS_E_FSTASK_CONNECTIO 
NTYPENOTFILE 


DTS_E_FSTASK_VARIABLED 
OESNTEXIST 


DTS_E_FSTASK_VARIABLEN 
OTASTRING 


DTS_E_FSTASK_FILEDOESN 
OTEXIST 


DTS_E_FSTASK_DESTCONNU 
SAGETYPEINVALID 


DESCRIPTION 


The directory "%1" does not 
exist. 


File/Process "%1" does not 
exist in directory "%2". 


File/Process "%1" is not in 
path. 


Working Directory "%1" 
does not exist. 


The process exited with 
return code "%1". However, 
"%2" was expected. 


Synchronization object 
failed. 


The File System task 
received an invalid task data 
node. 


The Directory already exists. 


"%1" is not valid on 
operation type "%2". 


Destination property of 
operation "%1" not set. 


Source property of 
operation "%1" not set. 


Type of Connection "%1" is 
not a file. 


Variable "%1" does not 
exist. 


Variable "%1" is not a string. 


File or directory "%1" 
represented by connection 
"%2" does not exist. 


The destination file 
connection manager "%1" 
has an invalid usage type: 
"%2". 


HEXADECIMAL CODE 


0xC0029166 


0xC0029167 


0xC0029168 


0xC0029169 


0xC002916A 


0xC002916B 


0xC002916C 


0xC002916D 


0xC002916E 


0xC002916F 


0xC0029170 


0xC0029171 


0xC0029172 


0xC0029173 


0xC0029175 


0xC0029176 


DECIMAL CODE 


-1073573530 


-1073573529 


-1073573528 


-1073573527 


-1073573526 


-1073573525 


-1073573524 


-1073573523 


-1073573522 


-1073573521 


-1073573520 


-1073573519 


-1073573518 


-1073573517 


-1073573515 


-1073573514 


SYMBOLIC NAME 


DTS_E_FSTASK_SRCCONNUS 
AGETYPEINVALID 


DTS_E_FSTASK_LOGENTRYG 
ETTINGFILEOPERATION 


DTS_E_FSTASK_LOGENTRYG 
ETTINGFILEOPERATIONDES 
C 


DTS_E_FSTASK_TASKDISPLA 
YNAME 


DTS_E_FSTASK_TASKDESCRI 
PTION 


DTS_E_FTPTASK_SYNCOBJF 
AILED 


DTS_E_FTPTASK_UNABLETO 
OBTAINFILELIST 


DTS_E_FTPTASK_LOCALPAT 
HEMPTY 


DTS_E_FTPTASK_REMOTEPA 
THEMPTY 


DTS_E_FTPTASK_LOCALVARI 
BALEEMPTY 


DTS_E_FTPTASK_REMOTEVA 
RIBALEEMPTY 


DTS_E_FTPTASK_FTPRCVDIN 
VLDDATANODE 


DTS_E_FTPTASK_CONNECTI 
ON_NAME_NULL 


DTS_E_FTPTASK_CONNECTI 
ON_NOT_FTP 


DTS_E_FTPTASK_INITIALIZA 
TION_WITH_NULL_XML_EL 
EMENT 


DTS_E_FTPTASK_SAVE_TO_N 
ULL_XML_ELEMENT 


DESCRIPTION 


The source file connection 
manager "%1" has an 
invalid usage type "%2". 


FilesystemOperation 


Provides information 
regarding File System 
operations. 


File System Task 


Perform file system 
operations, such as copying 
and deleting files. 


Synchronization object 
failed. 


Unable to obtain the file list. 


The local path is empty. 


The remote path is empty. 


The local variable is empty. 


The remote variable is 
empty. 


The FTP task received an 
invalid task data node. 


The connection is empty. 
Verify that a valid FTP 
connection is provided. 


The connection specified is 
not an FTP connection. 
Verify that a valid FTP 
connection is provided. 


Cannot initialize the task 
with a null XML element. 


Cannot save the task to a 
null XML document. 


HEXADECIMAL CODE 


0xC0029177 


0xC0029178 


0xC0029179 


0xC002917A 


0xC002917B 


0xC002917C 


0xC002917D 


0xC002917E 


0xC002917F 


0xC0029180 


0xC0029182 


0xC0029183 


0xC0029184 


0xC0029185 


0xC0029186 


0xC0029187 


0xC0029188 


DECIMAL CODE 


-1073573513 


-1073573512 


-1073573511 


-1073573510 


-1073573509 


-1073573508 


-1073573507 


-1073573506 


-1073573505 


-1073573504 


-1073573502 


-1073573501 


-1073573500 


-1073573499 


-1073573498 


-1073573497 


-1073573496 


SYMBOLIC NAME 


DTS_E_FTPTASK_ERROR_IN_ 
LOAD_FROM_XML 


DTS_E_FTPTASK_NOFILESAT 
LOCATION 


DTS_E_FTPTASK_LOCALVARI 
ABLEISEMPTY 


DTS_E_FTPTASK_REMOTEVA 
RIABLEISEMPTY 


DTS_E_FTPTASK_NOFILESIN 
CONNMGR 


DTS_E_FTPTASK_NOFILEPAT 
HSINLOCALVAR 


DTS_E_FTPTASK_VARIABLEN 
OTASTRING 


DTS_E_FTPTASK_VARIABLEN 
OTFOUND 


DTS_E_FTPTASK_INVALIDPA 
THONOPERATION 


DTS_E_FTPTASK_DIRECTORY 
EXISTS 


DTS_E_FTPTASK_CONNECTI 
ONTYPENOTFILE 


DTS_E_FTPTASK_FILEDOESN 
OTEXIST 


DTS_E_FTPTASK_INVALIDDI 
RECTORY 


DTS_E_FTPTASK_NOFILESFO 
UND 


DTS_E_FTPTASK_NODIRECT 
ORYPATHINCONMGR 


DTS_E_FTPTASK_UNABLETO 
DELETELOCALEFILE 


DTS_E_FTPTASK_UNABLETO 
REMOVELOCALDIRECTORY 


DESCRIPTION 


Error occurred in 
LoadFromXML at the tag 
"O61", 


There are no files at "%1". 


The variable "%1" is empty. 


The variable "%1" is empty. 


The File "%1" doesn't 
contain file path(s). 


The variable "%1" doesn't 
contain file path(s). 


Variable "%1" is not a string. 


Variable "%1" does not 
exist. 


Invalid path on operation 
n96q" 


"%1" already exists. 


Type of Connection "%1" is 
Not a file. 


File represented by "%1" 
does not exist. 


Directory is not specified in 
the variable "%1". 


No files found in "%1". 


Directory is not specified in 
the file connection manager 
nop" 


Unable to delete local file 
nog" 


Unable to remove local 
directory "%1". 


HEXADECIMAL CODE 


0xC0029189 


0xC002918A 


0xC002918B 


0xC002918C 


0xC002918D 


0xC002918E 


0xC002918F 


0xC0029190 


0xC0029191 


0xC0029192 


0xC0029193 


0xC0029194 


0xC0029195 


0xC0029196 


0xC0029197 


0xC0029198 


DECIMAL CODE 


-1073573495 


-1073573494 


-1073573493 


-1073573492 


-1073573491 


-1073573490 


-1073573489 


-1073573488 


-1073573487 


-1073573486 


-1073573485 


-1073573484 


-1073573483 


-1073573482 


-1073573481 


-1073573480 


SYMBOLIC NAME 


DTS_E_FTPTASK_UNABLETO 
CREATELOCALDIRECTORY 


DTS_E_FTPTASK_UNABLETO 
RECEIVEFILES 


DTS_E_FTPTASK_UNABLETO 
SENDFILES 


DTS_E_FTPTASK_UNABLETO 
MAKEDIRREMOTE 


DTS_E_FTPTASK_UNABLETO 
REMOVEDIRREMOTE 


DTS_E_FTPTASK_UNABLETO 
DELETEREMOTEFILES 


DTS_E_FTPTASK_UNABLETO 
CONNECTTOSERVER 


DTS_E_FTPTASK_INVALIDVA 
RIABLEVALUE 


DTS_E_FTPTASK_INVALIDRE 
MOTEPATH 


DTS_E_DTS_E_FTPTASK_CAN 
NOT_ACQUIRE_CONNECTI 
ON 


DTS_E_MSGQTASKUTIL_CER 
T_OPEN_STORE_FAILED 


DTS_E_MSGQTASKUTIL_CER 
T_FAILED_GETTING_DISPLA 
Y_NAME 


DTS_E_MSGQTASKUTIL_CER 
T_FAILED_GETTING_ISSUER_ 
NAME 


DTS_E_MSGQTASKUTIL_CER 
T_FAILED_GETTING_FRIEND 
LY_NAME 


DTS_E_-MSMQTASK_NO_CO 
NNECTION 


DTS_E_MSMQTASK_INITIALI 
ZATION_WITH_WRONG_X 
ML_ELEMENT 


DESCRIPTION 


Unable to create local 
directory "%1". 


Unable to receive files using 
nop" 


Unable to send files using 
n964 


Unable to create remote 
directory using "%1". 


Unable to remove remote 
directory using "%1". 


Unable to delete remote 
files using "%1". 


Unable to connect to FTP 
server using "%1". 


Variable "%1" doesn't start 
with "/". 


Remote path "%1" doesn't 
start with "7". 


There was an error 
acquiring the FTP 
connection. Please check if 
you have specified a valid 
connection type "%1". 


Opening the certificate 
store failed. 


An error occurred while 
retrieving the display name 
of the certificate. 


An error occurred while 
retrieving the issuer name 
of the certificate. 


An error occurred while 
retrieving the friendly name 
of the certificate. 


The MSMQ connection 
name is not set. 


Task was initialized with the 
wrong XML element. 


HEXADECIMAL CODE 


0xC0029199 


0xC002919A 


0xC002919B 


0xC002919C 


0xC002919D 


0xC002919E 


0xC002919F 


0xC00291A0 


0xC00291A1 


0xC00291A2 


0xC00291A3 


0xC00291A4 


0xC00291A5 


0xC00291A6 


0xC00291A7 


DECIMAL CODE 


-1073573479 


-1073573478 


-1073573477 


-1073573476 


-1073573475 


-1073573474 


-1073573473 


-1073573472 


-1073573471 


-1073573470 


-1073573469 


-1073573468 


-1073573467 


-1073573466 


-1073573465 


SYMBOLIC NAME 


DTS_E_MSMQTASK_DATA_FI 
LE_NAME_EMPTY 


DTS_E_MSMQTASK_DATA_FI 
LE_SAVE_NAME_EMPTY 


DTS_E_MSMQTASK_DATA_FI 
LE_SIZE_LERROR 


DTS_E_MSMQTASK_DATA_FI 
LE_SAVE_FAILED 


DTS_E_LMSMQTASK_STRING 
_COMPARE_VALUE_MISSIN 
G 


DTS_E_MSMQTASK_INVALI 
D_QUEUE_PATH 


DTS_E_ MSMQTASK_NOT_TR 
ANSACTIONAL 


DTS_E_MSMQTASK_INVALI 
D_MESSAGE_TYPE 


DTS_E_MSMQTASK_TASK_T| 
MEOUT 


DTS_E_MSMQTASK_INVALI 
D_PROPERTY_VALUE 


DTS_E_LMSMQTASK_MESSA 
GE_NON_AUTHENTICATED 


DTS_E_MSMQTASK_INVALI 
D_ENCRYPTION_ALGO_WR 
APPER 


DTS_E_MSMQTASK_VARIAB 
LE_TO_RECEIVE_STRING_MS 
G_EMPTY 


DTS_E_MSMQTASK_RECEIVE 
_VARIABLE_EMPTY 


DTS_E_MSMQTASK_CONNE 
CTIONTYPENOTMSMQ 


DESCRIPTION 


Data file name is empty. 


The name specified for the 
data file to save is empty. 


File size should be less than 
4 MB. 


Saving the data file failed. 


String filter value is empty. 


Queue path is not valid. 


The message queue task 
does not support enlisting 
in distributed transactions. 


The message type is not 
valid. 


The message queue timed 
out. No message has been 
received. 


The property specified is 
not valid. Verify that the 
argument type is correct. 


Message is not 
authenticated. 


You are trying to set the 
value of Encryption 
Algorithm with an invalid 
object. 


The variable to receive 
string message is empty. 


Variable to receive variable 
message is empty. 


Connection "%1" is not of 
type MSMQ. 


HEXADECIMAL CODE 


0xC00291A8 


0xC00291A9 


0xC00291AA 


0xC00291AB 


0xC00291AC 


0xC00291AD 


0xC00291AE 


0xC00291AF 


0xC00291B0 


0xC00291B1 


0xC00291B2 


0xC00291B3 


0xC00291B4 


0xC00291B5 


DECIMAL CODE 


-1073573464 


-1073573463 


-1073573462 


-1073573461 


-1073573460 


-1073573459 


-1073573458 


-1073573457 


-1073573456 


-1073573455 


-1073573454 


-1073573453 


-1073573452 


-1073573451 


SYMBOLIC NAME 


DTS_E_MSMQTASK_DATAFIL 
E_ALREADY_EXISTS 


DTS_E_LMSMQTASK_STRING 
_MSG_TO_VARIABLE_NOT_F 
OUND 


DTS_E_MSMQTASK_CONN 
MNGRNULL 


DTS_E_MSMQTASK_CONN 
MNGRDOESNOTEXIST 


DTS_E_SCRIPTTASK_COMPI 
LEERRORMSG 


DTS_E_SCRIPTTASK_COMPI 
LEERRORMSG2 


DTS_E_SCRIPTTASK_COMPI 
LEERRORMSG3 


DTS_E_SCRIPTTASK_SCRIPTR 
EPORTEDFAILURE 


DTS_E_SCRIPTTASK_SCRIPTF 
ILESFAILEDTOLOAD 


DTS_E_SCRIPTTASK_SCRIPTT 
HREWEXCEPTION 


DTS_E_SCRIPTTASK_COULD 
NOTCREATEENTRYPOINTCL 
ASS 


DTS_E_SCRIPTTASK_LOADFR 
OMXMLEXCEPTION 


DTS_E_SCRIPTTASK_SOURC 
EITEMNOTFOUNDEXCEPTI 
ON 


DTS_E_SCRIPTTASK_BINARY| 
TEMNOTFOUNDEXCEPTIO 
N 


DESCRIPTION 


The data file "%1" already 
exists at the specified 
location. Cannot overwrite 
the file as the Overwrite 
option is set to false. 


The specified variable "%1" 
to receive string message is 
not found in the package 
variable collection. 


The connection manager 
"%1" is empty. 


The connection manager 
"%1" does not exist. 


Error "%1": "%2"\r\nLine 
"%3" Column "%4" through 
"%5". 


There was an error 
compiling the script: "%1". 


Error "%1": "%2"\r\nLine 
"%3" Columns "%4"- 
"%5"\r\nLine Text: "%6". 


User script returned a 
failure result. 


User script files failed to 
load. 


User script threw an 
exception: "%1". 


Could not create an 
instance of entrypoint class 
n964 


There was an exception 
while loading Script Task 
from XML: "%1". 


Source item "%1" was not 
found in the package. 


Binary item "%1" was not 
found in the package. 


HEXADECIMAL CODE 


0xC00291B6 


0xC00291B7 


0xC00291B8 


0xC00291B9 


0xC00291BA 


0xC00291BB 


0xC00291BC 


0xC00291BD 


0xC00291BE 


0xC00291BF 


0xC00291C0 


0xC00291C1 


0xC00291C2 


0xC00291C3 


DECIMAL CODE 


-1073573450 


-1073573449 


-1073573448 


-1073573447 


-1073573446 


-1073573445 


-1073573444 


-1073573443 


-1073573442 


-1073573441 


-1073573440 


-1073573439 


-1073573438 


-1073573437 


SYMBOLIC NAME 


DTS_E_SCRIPTTASK_UNREC 
OGNIZEDSCRIPTLANGUAG 
EEXCEPTION 


DTS_E_SCRIPTTASK_ILLEGAL 
SCRIPTNAME 


DTS_E_SCRIPTTASK_INVALI 
DSCRIPTLANGUAGE 


DTS_E_SCRIPTTASK_CANTIN 
ITNULLTASK 


DTS_E_SCRIPTTASK_MUSTIN 
ITWITHRIGHTTASK 


DTS_E_SCRIPTTASK_WASNO 
TINITED 


DTS_E_SCRIPTTASK_HOST_N 
AME_CANT_EMPTY 


DTS_E_SCRIPTTASK_INVALI 
D_SCRIPT_NAME 


DTS_E_SCRIPTTASK_INVALI 
D_SCRIPT_LANGUAGE 


DTS_E_SCRIPTTASK_INVALI 
D_ENTRY_POINT 


DTS_E_SCRIPTTASK_LANGU 
AGE_EMPTY 


DTS_E_SCRIPTTASK_INITIALI 
ZATION_WITH_NULL_TASK 


DTS_E_SCRIPTTASK_UI_INITI 
ALIZATION_WITH_WRONG_ 
TASK 


DTS_E_SENDMAILTASK_RECI 
PIENT_EMPTY 


DESCRIPTION 


"%1" was not recognized as 
a valid script language. 


The script name is not valid. 
It cannot contain spaces, 
slashes, special characters, 
or begin with a number. 


The script language 
specified is not valid. 


Cannot initialize to a null 
task. 


The Script Task user 
interface must initialize to 
an Script Task. 


The Script Task user 
interface is not initialized. 


Name cannot be empty. 


The project name is not 
valid. It cannot contain 
spaces, slashes, special 
characters, or begin with a 
number. 


The script language 
specified is not valid. 


Entry point not found. 


The script language is not 
specified. Verify that a valid 
script language is specified. 


User interface initialization: 
The task is null. 


The Script Task user 
interface is initialized with 
an incorrect task. 


No recipient is specified. 


HEXADECIMAL CODE 


0xC00291C4 


0xC00291C5 


0xC00291CB 


0xC00291CD 


0xC00291CE 


0xC00291CF 


0xC00291D0O 


0xC00291D1 


0xC00291D2 


0xC00291D3 


0xC00291D4 


0xC00291D5 


0xC00291D6 


0xC00291D7 


0xC00291D8 


DECIMAL CODE 


-1073573436 


-1073573435 


-1073573429 


-1073573427 


-1073573426 


-1073573425 


-1073573424 


-1073573423 


-1073573422 


-1073573421 


-1073573420 


-1073573419 


-1073573418 


-1073573417 


-1073573416 


SYMBOLIC NAME 


DTS_E_SENDMAILTASK_SMT 
P_SERVER_NOT_SPECIFIED 


DTS_E_SENDMAILTASK_TAS 
K_INITIALIZATION_WITH_W 
RONG_XML_ELEMENT 


DTS_E_SENDMAILTASK_INV 
ALIDATTACHMENT 


DTS_E_SENDMAILTASK_CHE 
CK_VALID_SMTP_SERVER 


DTS_E_SENDMAILTASK_CO 
NNECTIONTYPENOTFILE 


DTS_E_SENDMAILTASK_FILE 
DOESNOTEXIST 


DTS_E_SENDMAILTASK_VAR 
IABLETYPEISNOTSTRING 


DTS_E_SENDMAILTASK_CO 
NNECTIONTYPENOTSMTP 


DTS_E_SENDMAILTASK_CO 
NNMNGRNULL 


DTS_E_SENDMAILTASK_NO 
CONNMNGR 


DTS_E_SQLTASK_NOSTATEM 
ENTSPECIFIED 


DTS_E_SQLTASK_NOXMLSU 
PPORT 


DTS_E_SQLTASK_NOHANDL 
ERFORCONNECTION 


DTS_E_SQLTASK_NOCONNE 
CTIONMANAGER 


DTS_E_SQLTASK_CANNOTA 
CQUIRECONNMANAGER 


DESCRIPTION 


The Simple Mail Transfer 
Protocol (SMTP) server is 
not specified. Provide a 
valid name or IP address of 
the SMTP server. 


Send Mail task is initiated 
with an incorrect XML 
element. 


Either the file "%1" does not 
exist or you do not have 


permissions to access the 
file. 


Verify that the Simple Mail 
Transfer Protocol (SMTP) 
server specified is valid. 


Connection "%1" is not of 
type File. 


On operation "%1", file "%2" 
does not exist. 


Variable "%1" is not of type 
string. 


Connection "%1" is not of 
type SMTP. 


Connection "%1" is empty. 


The specified connection 
"%1" does not exist. 


No Transact-SQL statement 
specified. 


The connection does not 
support XML result sets. 


Cannot locate a handler for 
the specified connection 


type. 


No connection manager is 
specified. 


Cannot acquire a 
connection from the 
connection manager. 


HEXADECIMAL CODE 


0xC00291D9 


0xC00291DA 


0xC00291DB 


0xC00291DC 


0xC00291DD 


0xC00291DE 


0xC00291DF 


0xC00291E0 


0xC00291E1 


0xC00291E2 


0xC00291E3 


0xC00291E4 


0xC00291E5 


0xC00291E6 


DECIMAL CODE 


-1073573415 


-1073573414 


-1073573413 


-1073573412 


-1073573411 


-1073573410 


-1073573409 


-1073573408 


-1073573407 


-1073573406 


-1073573405 


-1073573404 


-1073573403 


-1073573402 


SYMBOLIC NAME 


DTS_E_SQLTASK_NULLPARA 
METERNAME 


DTS_E_SQLTASK_INVALIDPA 
RAMETERNAME 


DTS_E_SQLTASK_VALIDPAR 
AMETERTYPES 


DTS_E_SQLTASK_READONLY 
VARIABLE 


DTS_E_SQLTASK_INDESNOTI 
NCOLLECTION 


DTS_E_SQLTASK_ROVARINO 
UTPARAMETER 


DTS_E_SQLTASK_OBJECTNO 
TINCOLLECTION 


DTS_E_SQLTASK_UNABLETO 
ACQUIREMANAGEDCONN 


DTS_E_UNABLETOPOPRESU 
LT 


DTS_E_SQLTASK_INVALIDN 
UMOFRESULTBINDINGS 


DTS_E_SQLTASK_RESULTBIN 
DTYPEFORROWSETXML 


DTS_E_SQLTASK_INVALIDEP 
ARAMDIRECTIONFALG 


DTS_E_SQLTASK_NOSQLTAS 
KDATAINXMLFRAGMENT 


DTS_E_SQLTASK_MULTIPLER 
ETURNVALUEPARAM 


DESCRIPTION 


Cannot have a null 
parameter name. 


The parameter name is not 
valid. 


Valid parameter names are 
of type Int or String. 


Variable "%1" cannot be 
used in a result binding 
because it is read-only. 


The index is not assigned in 
this collection. 


The variable "%1" cannot be 
used as an "out" parameter 
or return value in a 
parameter binding because 
it is read-only. 


The object does not exist in 
this collection. 


Cannot acquire a managed 
connection. 


Cannot populate the result 
columns for a single row 
result type. The query 
returned an empty result 
set. 


There is an invalid number 
of result bindings returned 
for the ResultSetType: "%1". 


The result binding name 
must be set to zero for full 
result set and XML results. 


The parameter directions 
flag is not valid. 


The XML fragment does not 
contain SQL Task data. 


A parameter with type 
return value is not the first 
parameter, or there are 
more than one parameter 
of type return value. 


HEXADECIMAL CODE 


0xC00291E7 


0xC00291E8 


0xC00291E9 


0xC00291EA 


0xC00291EB 


0xC00291EC 


0xC00291ED 


0xC00291EE 


0xC00291 EF 


0xC00291FO 


0xC00291F1 


0xC00291F2 


0xC00291F3 


0xC00291F4 


0xC00291F5 


DECIMAL CODE 


-1073573401 


-1073573400 


-1073573399 


-1073573398 


-1073573397 


-1073573396 


-1073573395 


-1073573394 


-1073573393 


-1073573392 


-1073573391 


-1073573390 


-1073573389 


-1073573388 


-1073573387 


SYMBOLIC NAME 


DTS_E_SQLTASK_CONNECTI 
ONTYPENOTFILE 


DTS_E_SQLTASK_FILEDOESN 
OTEXIST 


DTS_E_SQLTASK_VARIABLET 
YPEISNOTSTRING 


DTS_E_SQLTASK_VARIABLEN 
OTFOUND 


DTS_E_SQLTASK_CANNOTL 
OCATECONNMANAGER 


DTS_E_SQLTASK_FAILEDTOA 
CQUIRECONNECTION 


DTS_E_SQLTASK_RESULTBYN 
AMENOTSUPPORTED 


DTS_E_SQLTASKCONN_ERR_ 
NO_ROWS 


DTS_E_SQLTASKCONN_ERR_ 
NO_DISCONNECTED_RS 


DTS_E_SQLTASKCONN_ERR_ 
UNSUPPORTED_TYPE 


DTS_E_SQLTASKCONN_ERR_ 
UNKNOWN_TYPE 


DTS_E_SQLTASKCONN_ERR_ 
PARAM_DATA_TYPE 


DTS_E_SQLTASKCONN_ERR_ 
PARAM_NAME_MIX 


DTS_E_SQLTASKCONN_ERR_ 
PARAM_DIR 


DTS_E_SQLTASKCONN_ERR_ 
RESULT_DATA_TYPE 


DESCRIPTION 


Connection "%1" is not a 
file connection manager. 


File represented by "%1" 
does not exist. 


Type of variable "%1" is not 
string. 


Variable "%1" does not exist 
or could not be locked. 


Connection manager "%1" 
does not exist. 


Failed to acquire connection 
"%1". Connection may not 
be configured correctly or 
you may not have the right 
permissions on this 
connection. 


Result binding by name 
"%1" is not supported for 
this connection type. 


A result set type of single 
row is specified, but no 
rows were returned. 


No disconnected record set 
is available for the Transact- 
SQL statement. 


Unsupported type. 


Unknown type. 


Unsupported data type on 
parameter binding \"%s\". 


Parameter names cannot be 
an mix of ordinal and 
named types. 


The parameter direction on 
parameter binding \"%s\" is 
not valid. 


The data type on result set 
binding \"%s\" is not 
supported. 


HEXADECIMAL CODE 


0xC00291F6 


0xC00291F7 


0xC00291F9 


0xC00291FA 


0xC00291FB 


0xC00291FC 


0xC00291FD 


0xC00291FE 


0xC00291FF 


0xC0029200 


0xC0029201 


0xC0029202 


0xC0029203 


0xC0029204 


0xC0029205 


DECIMAL CODE 


-1073573386 


-1073573385 


-1073573383 


-1073573382 


-1073573381 


-1073573380 


-1073573379 


-1073573378 


-1073573377 


-1073573376 


-1073573375 


-1073573374 


-1073573373 


-1073573372 


-1073573371 


SYMBOLIC NAME 


DTS_E_SQLTASKCONN_ERR_ 
RESULT_COL_INDEX 


DTS_E_SQLTASKCONN_ERR_ 
UNKNOWN_RESULT_COL 


DTS_E_SQLTASKCONN_ERR_ 
NOROWSET 


DTS_E_SQLTASKCONN_ERR_ 
ODBC_DISCONNECTED 


DTS_E_SQLTASKCONN_ERR_ 
RESULT_SET_DATA_TYPE 


DTS_E_SQLTASKCONN_ERR_ 
CANT_LOAD_XML 


DTS_E_TTGENTASK_NOCON 
NORVARIABLE 


DTS_E_TTGENTASK_FAILEDC 
REATE 


DTS_E_TTGENTASK_BADTAB 
LEMETADATA 


DTS_E_TTGENTASK_FAILEDC 
REATEPIPELINE 


DTS_E_TTGENTASK_BADVAR 
IABLETYPE 


DTS_E_TTGENTASK_NOTFILE 
CONNECTION 


DTS_E_TTGENTASK_BADFILE 
NAME 


DTS_E_WEBSERVICETASK_C 
ONNECTION_NAME_NULL 


DTS_E_WEBSERVICETASK_C 
ONNECTION_NOT_FOUND 


DESCRIPTION 


The result column index %d 
is not valid. 


Cannot find column \"%s\" 
in the result set. 


No result rowset is 
associated with the 
execution of this query. 


Disconnected recordsets are 
not available from ODBC 
connections. 


The data type in the result 
set, column %hd, is not 
supported. 


Cannot load XML with 
query result. 


A connection name or 
variable name for the 
package must be specified. 


Failed to create the 
package. 


The TableMetaDataNode is 
not an XMLNode. 


Failed to create the pipeline. 


The variable is not the 
correct type. 


The connection manager 
specified is not a FILE 
connection manager. 


Invalid file name specified 
on the connection manager 
Hop 4" 


The connection is empty. 
Verify that a valid HTTP 
connection is specified. 


The connection does not 
exist. Verify that a valid, 
existing HTTP connection is 
specified. 


HEXADECIMAL CODE 


0xC0029206 


0xC0029207 


0xC0029208 


0xC0029209 


0xC002920A 


0xC002920B 


0xC002920C 


0xC002920D 


OxC002920E 


0xC002920F 


0xC0029210 


0xC0029211 


0xC0029212 


DECIMAL CODE 


-1073573370 


-1073573369 


-1073573368 


-1073573367 


-1073573366 


-1073573365 


-1073573364 


-1073573363 


-1073573362 


-1073573361 


-1073573360 


-1073573359 


-1073573358 


SYMBOLIC NAME 


DTS_E_WEBSERVICETASK_C 
ONNECTION_NOT_HTTP 


DTS_E_WEBSERVICETASK_SE 
RVICE_NULL 


DTS_E_WEBSERVICETASK_M 
ETHODNAME_NULL 


DTS_E_WEBSERVICETASK_W 
EBMETHODINFO_NULL 


DTS_E_WEBSERVICETASK_O 
UTPUTLOC_NULL 


DTS_E_WEBSERVICETASK_V 
ARIABLE_NOT_FOUND 


DTS_E_WEBSERVICETASK_V 
ARIABLE_READONLY 


DTS_E_WEBSERVICETASK_ER 
ROR_IN_LOAD_FROM_XML 


DTS_E_WEBSERVICETASK_ER 
ROR_IN_SAVE_TO_XML 


DTS_E_WEBSERVICETASK_TA 
SK_SAVE_TO_NULL_XML_EL 
EMENT 


DTS_E_WEBSERVICETASK_TA 
SK_INITIALIZATION_WITH_ 
NULL_XML_ELEMENT 


DTS_E_WEBSERVICETASK_TA 
SK_INITIALIZATION_WITH_ 
WRONG_XML_ELEMENT 


DTS_E_WEBSERVICETASK_U 
NEXPECTED_XML_ELEMENT 


DESCRIPTION 


The connection specified is 
not a HTTP connection. 
Verify that a valid HTTP 
connection is specified. 


The Web Service name is 
empty. Verify that a valid 
web service name is 
specified. 


The web method name is 
empty. Verify that a valid 
web method is specified. 


The web method is empty 
or may not exist. Verify that 
there is an existing web 
method to specify. 


The output location is 
empty. Verify that an 
existing file connection or 
variable is specified. 


The variable cannot be 
found. Verify that the 
variable exists in the 
package. 


Cannot save the result. 
Verify that the variable is 
not read-only. 


Error occurred in 
LoadFromXML at the tag 
"O61", 


Error occurred in 
SaveToXML at the tag "%1". 


Cannot save the task to a 
null XML document. 


Cannot initialize the task 
with a null XML element. 


The Web Service Task is 
initiated with an incorrect 
XML element. 


Unexpected XML element 
found. 


HEXADECIMAL CODE 


0xC0029213 


0xC0029214 


0xC0029215 


0xC0029216 


0xC0029217 


0xC0029218 


0xC0029219 


0xC002921A 


0xC002921B 


0xC002921C 


0xC002921D 


0xC002921E 


0xC002921F 


DECIMAL CODE 


-1073573357 


-1073573356 


-1073573355 


-1073573354 


-1073573353 


-1073573352 


-1073573351 


-1073573350 


-1073573349 


-1073573348 


-1073573347 


-1073573346 


-1073573345 


SYMBOLIC NAME 


DTS_E_WEBSERVICETASK_C 
ANNOT_ACQUIRE_CONNEC 
TION 


DTS_E_WEBSERVICETASK_FI 
LE_CONN_NOT_FOUND 


DTS_E_WEBSERVICETASK_FI 
LE_NOT_FOUND 


DTS_E_WEBSERVICETASK_FI 
LE_NULL 


DTS_E_WEBSERVICETASK_C 
ANNOT_ACQUIRE_FILE_CO 
NNECTION 


DTS_E_WEBSERVICETASK_D 
ATATYPE_NOT_SUPPORTED 


DTS_E_WEBSERVICETASK_P 
ARAMTYPE_NOT_SUPPORT 
ED 


DTS_E_WEBSERVICETASK_W 
SDL_VERSION_NOT_SUPPO 
RTED 


DTS_E_WEBSERVICETASK_W 
RONG_XML_ELEMENT 


DTS_E_WEBSERVICETASK_X 
ML_ATTRIBUTE_NOT_FOUN 
D 


DTS_E_WEBSERVICETASK_E 
NUM_NO_VALUES 


DTS_E_WEBSERVICETASK_C 
ONNECTIONNOTFOUND 


DTS_E_WEBSERVICETASK_C 
ONNECTION_ALREADY_EXI! 
STS 


DESCRIPTION 


There was an error 
acquiring the HTTP 
connection. Verify that a 
valid connection type is 
specified. 


Cannot save the result. 
Verify that there is an 
existing file connection. 


Cannot save the result. 
Verify that the file exists. 


Cannot save the result. The 
file name is empty or the 
file is in use by another 
process. 


There was an error in 
acquiring the file 
connection. Verify that a 
valid file connection is 
specified. 


Only Complex Types with 
Primitive values, Primitive 
Arrays, and Enumerations 
are supported. 


Only Primitive, Enum, 
Complex, PrimitiveArray, 
and ComplexArray types 
are supported. 


This version of WSDL is not 
supported. 


Initialized with an incorrect 
XML element. 


A mandatory attribute is 
not found. 


The enum "%1" does not 
have any values. The WSDL 
is corrupted. 


The connection cannot be 
found. 


Connection by this name 
already exists. 


HEXADECIMAL CODE 


0xC0029220 


0xC0029221 


0xC0029222 


0xC0029223 


0xC0029224 


0xC0029225 


0xC0029226 


0xC0029227 


0xC0029228 


0xC0029229 


0xC002922A 


0xC002922B 


0xC002922C 


DECIMAL CODE 


-1073573344 


-1073573343 


-1073573342 


-1073573341 


-1073573340 


-1073573339 


-1073573338 


-1073573337 


-1073573336 


-1073573335 


-1073573334 


-1073573333 


-1073573332 


SYMBOLIC NAME 


DTS_E_WEBSERVICETASK_N 
ULL_CONNECTION 


DTS_E_WEBSERVICETASK_N 
OT_HTTP_CONNECTION 


DTS_E_WEBSERVICETASK_W 
SDL_NOT_FOUND 


DTS_E_WEBSERVICETASK_ER 
ROR_IN_DOWNLOAD 


DTS_E_WEBSERVICETASK_SE 
RVICE_DESC_NULL 


DTS_E_WEBSERVICETASK_SE 
RVICENULL 


DTS_E_WEBSERVICETASK_W 
SDL_NULL 


DTS_E_WEBSERVICETASK_SE 
RVICE_NOT_FOUND 


DTS_E_WEBSERVICETASK_S 
OAPPORT_NOT_FOUND 


DTS_E_WEBSERVICETASK_S 
OAPBINDING_NOT_FOUND 


DTS_E_WEBSERVICETASK_S 
OAPPORTTYPE_NOT_FOUN 
D 


DTS_E_WEBSERVICETASK_M 
SG_NOT_FOUND 


DTS_E_WEBSERVICETASK_C 
ANNOT_GEN_PROXY 


DESCRIPTION 


Connection cannot be null 
or empty. 


The connection specified is 
not a HTTP connection. 
Verify that a valid HTTP 
connection is specified. 


The specified Uniform 
Resource Identifier (URI) 
does not contain a valid 
WSDL. 


Could not read the WSDL 
file. The input WSDL file is 
not valid. The reader threw 
the following error: "%1". 


Service Description cannot 
be null. 


Service name cannot be 
null. 


URL cannot be null. 


The service is not currently 
available. 


The service is not available 
on the SOAP port. 


Failed to parse the Web 
Services Description 
Language (WSDL). Cannot 
find the Binding that 
corresponds to the SOAP 
port. 


Failed to parse the Web 
Services Description 
Language (WSDL). Cannot 
find a PortType that 
corresponds to the SOAP 
port. 


Cannot find the message 
that corresponds to the 
method specified. 


Could not generate the 
proxy for the given web 
service. The following errors 
were encountered while 
generating the proxy "%1". 


HEXADECIMAL CODE 


0xC002922D 


OxC002922E 


0xC002922F 


0xC0029230 


0xC0029231 


0xC0029232 


0xC0029233 


0xC0029234 


0xC0029235 


0xC0029236 


DECIMAL CODE 


-1073573331 


-1073573330 


-1073573329 


-1073573328 


-1073573327 


-1073573326 


-1073573325 


-1073573324 


-1073573323 


-1073573322 


SYMBOLIC NAME 


DTS_E_WEBSERVICETASK_C 
ANNOT_LOAD_PROXY 


DTS_E_WEBSERVICETASK_IN 
VALID_SERVICE 


DTS_E_WEBSERVICETASK_W 
EBMETHOD_INVOKE_FAILE 
D 


DTS_E_WEBSERVICETASK_IN 
VOKE_ERR 


DTS_E_WEBSERVICETASK_M 
ETHODINFO_NULL 


DTS_E_WEBSERVICETASK_V 
ALUE_NOT_PRIMITIVE 


DTS_E_WEBSERVICETASK_V 
ALUE_NOT_ENUM 


DTS_E_VALUE_WEBSERVICE 
TASK_NOT_COMPLEX 


DTS_E_WEBSERVICETASK_V 
ALUE_NOT_ARRAY 


DTS_E_WEBSERVICETASK_TY 
PE_NOT_PRIMITIVE 


DESCRIPTION 


Could not load the proxy 
for the given web service. 
The exact error is as follows: 
"%1". 


Could not find the specified 
service. The exact error is as 
follows: "%1". 


The Web Service threw the 
following error during 
method execution: "%1". 


Could not execute the web 
method. The exact error is 
as follows: "%1". 


MethodInfo cannot be null. 


The specified 
WebMethodInfo is not 
correct. The ParamValue 
supplied does not match 
the ParamType. The 
DTSParamValue is not of 
type PrimitiveValue. 


The WebMethodInfo 
specified is not correct. The 
ParamValue supplied does 
not match the ParamType. 
The DTSParamValue found 
is not of type EnumValue. 


The WebMethodInfo 
specified is not correct. The 
ParamValue supplied does 
not match the ParamType. 
The DTSParamValue found 
is not of type 
ComplexValue. 


The WebMethodInfo 
specified is not correct. The 
ParamValue supplied does 
not match the ParamType. 
The DTSParamValue found 
is not of type ArrayValue. 


The WebMethodInfo you 
have specified is wrong. 
"%1" is not Primitive Type. 


HEXADECIMAL CODE 


0xC0029237 


0xC0029238 


0xC0029239 


0xC002923A 


0xC002923B 


0xC002923C 


0xC002923D 


0xC002923E 


0xC002923F 


0xC0029240 


0xC0029241 


0xC0029242 


0xC0029243 


0xC0029244 


DECIMAL CODE 


-1073573321 


-1073573320 


-1073573319 


-1073573318 


-1073573317 


-1073573316 


-1073573315 


-1073573314 


-1073573313 


-1073573312 


-1073573311 


-1073573310 


-1073573309 


-1073573308 


SYMBOLIC NAME 


DTS_E_WEBSERVICETASK_A 
RRAY_VALUE_INVALID 


DTS_E_WEBSERVICETASK_SE 
LECTED_VALUE_NULL 


DTS_E_WEBSERVICETASK_N 
ULL_VALUE 


DTS_E_WEBSERVICETASK_E 
NUM_VALUE_NOT_FOUND 


DTS_E_WEBSERVICETASK_P 
ROP_NOT_EXISTS 


DTS_E_WEBSERVICETASK_C 
ONVERT_FAILED 


DTS_E_WEBSERVICETASK_C 
LEANUP_FAILED 


DTS_E_WEBSERVICETASK_C 
REATE_INSTANCE_FAILED 


DTS_E_WEBSERVICETASK_N 
OT_PRIMITIVE_TYPE 


DTS_E_WEBSERVICETASK_ER 
ROR_IN_VALIDATE 


DTS_E_WEBSERVICETASK_D 
ATATYPE_NULL 


DTS_E_WEBSERVICETASK_IN 
DEX_OUT_OF_BOUNDS 


DTS_E_WEBSERVICETASK_W 
RONG_WSDL 


DTS_E_WMIDRTASK_SYNCO 
BJECTFAILED 


DESCRIPTION 


The format of the 
ArrayValue is not valid. 
There should be at least 
one element in the array. 


The value of the 
enumeration cannot be null. 
Select a default value for 
the enumeration. 


Cannot validate a null 
against any datatype. 


The enumeration Value is 
not correct. 


The class specified does not 
contain a public property 
by the name "%1". 


Could not convert "%1" to 
Noga" 


Cleanup failed. The proxy 
that was created for the 
web service may not have 
been deleted. 


Could not create an object 
of type "%1". Please check 
whether the default 
constructor exists. 


"%1" is not a value type. 


Could not validate "%1" 
against "%1". 


The data type cannot be 
null. Specify the value of the 
data type to validate. 


The ParamValue cannot be 
inserted at this position. 
The index specified might 
be lesser than zero or 
greater than the length. 


The input WSDL file is not 
valid. 


Synchronization object 
failed. 


HEXADECIMAL CODE 


0xC0029245 


0xC0029246 


0xC0029247 


0xC0029248 


0xC0029249 


0xC002924A 


0xC002924B 


0xC002924C 


0xC002924D 


OxC002924E 


0xC002924F 


0xC0029250 


0xC0029251 


0xC0029252 


0xC0029253 


0xC0029254 


DECIMAL CODE 


-1073573307 


-1073573306 


-1073573305 


-1073573304 


-1073573303 


-1073573302 


-1073573301 


-1073573300 


-1073573299 


-1073573298 


-1073573297 


-1073573296 


-1073573295 


-1073573294 


-1073573293 


-1073573292 


SYMBOLIC NAME 


DTS_E_WMIDRTASK_MISSIN 
GWQLQUERY 


DTS_E_WMIDRTASK_DESTIN 
ATIONMUSTBESET 


DTS_E_WMIDRTASK_MISSIN 
GCONNECTION 


DTS_E_WMIDRTASK_INVALI 
DDATANODE 


DTS_E_WMIDRTASK_FAILED 
VALIDATION 


DTS_E_WMIDRTASK_FILEDO 
ESNOTEXIST 


DTS_E_WMIDRTASK_CONN 
ECTIONMNGRDOESNTEXIS 
T 


DTS_E_WMIDRTASK_VARIAB 
LETYPEISNOTSTRINGOROBJ 
ECT 


DTS_E_WMIDRTASK_CONN 
ECTIONTYPENOTFILE 


DTS_E_WMIDRTASK_CONN 
ECTIONTYPENOTWMI 


DTS_E_WMIDRTASK_FILEAL 
READY EXISTS 


DTS_E_WMIDRTASK_CONN 
ECTIONMANAGEREMPTY 


DTS_E_WMIDRTASK_VARNO 
TOBJECT 


DTS_E_WMIDRTASK_TASKFA 
ILURE 


DTS_E_WMIDRTASK_CANT 
WRITETOVAR 


DTS_E_WMIEWTASK_SYNC 
OBJECTFAILED 


DESCRIPTION 


The WQL query is missing. 


The destination must be 
set. 


No WMI connection is set. 


WMI Data Reader Task 
received an invalid task data 
node. 


The task failed validation. 


File "%1" does not exist. 


Connection manager "%1" 
does not exist. 


Variable "%1" is not of type 
string or object. 


Connection "%1" is not of 
type "FILE". 


Connection "%1" is not of 
type "WMI". 


File "%1" already exists. 


Connection manager "%1" 
is empty. 


Variable "%1" should be of 
type object to be assigned a 
data table. 


Task failed due to invalid 
WMI query: "%1". 


Unable to write to variable 
"%1" since it set to keep its 
original value. 


Synchronization object 
failed. 


HEXADECIMAL CODE 


0xC0029255 


0xC0029256 


0xC0029257 


0xC0029258 


0xC0029259 


0xC002925A 


0xC002925B 


0xC002925C 


0xC002925D 


OxC002925E 


0xC002925F 


0xC0029260 


0xC0029261 


0xC0029262 


0xC0029263 


0xC0029264 


DECIMAL CODE 


-1073573291 


-1073573290 


-1073573289 


-1073573288 


-1073573287 


-1073573286 


-1073573285 


-1073573284 


-1073573283 


-1073573282 


-1073573281 


-1073573280 


-1073573279 


-1073573278 


-1073573277 


-1073573276 


SYMBOLIC NAME 


DTS_E_WMIEWTASK_MISSI 
NGWQLQUERY 


DTS_E_WMIEWTASK_MISSI 
NGCONNECTION 


DTS_E_WMIEWTASK_QUERY 
FAILURE 


DTS_E_WMIEWTASK_INVALI 
DDATANODE 


DTS_E_WMIEWTASK_CONN 
ECTIONMNGRDOESNTEXIS 
T 


DTS_E_WMIEWTASK_FILED 
OESNOTEXIST 


DTS_E_WMIEWTASK_VARIA 
BLETYPEISNOTSTRING 


DTS_E_WMIEWTASK_CONN 
ECTIONTYPENOTFILE 


DTS_E_WMIEWTASK_CONN 
ECTIONTYPENOTWMI 


DTS_E_WMIEWTASK_FILEAL 
READY EXISTS 


DTS_E_WMIEWTASK_CONN 
ECTIONMANAGEREMPTY 


DTS_E_WMIEWTASK_TIMEO 
UTOCCURRED 


DTS_E_WMIEWTASK_ERRME 
SSAGE 


DTS_E_XMLTASK_NODEFAU 
LTOPERTION 


DTS_E_XMLTASK_CONNECTI 
ONTYPENOTFILE 


DTS_E_XMLTASK_CANTGETR 
EADERFROMSOURCE 


DESCRIPTION 


The WQL query is missing. 


The WMI connection is 
missing. 


The task failed to execute 
the WMI query. 


The WMI Event Watcher 
Task received a task data 
node that is not valid. 


Connection manager "%1" 
does not exist. 


File "%1" does not exist. 


Variable "%1" is not of type 
string. 


Connection "%1" is not of 
type "FILE". 


Connection "%1" is not of 
type "WMI". 


File "%1" already exists. 


Connection manager "%1" 
is empty. 


Timeout of "%1" second(s) 
occurred before event 
represented by "%2". 


Watching for the Wal query 
caused the following system 
exception: "%1". Check the 
query for errors or WMI 
connection for access 
rights/permissions. 


The Operations specified is 
not defined. 


The connection type is not 
File. 


Cannot get an XmlReader 
from the source XML 
document. 


HEXADECIMAL CODE 


0xC0029265 


0xC0029266 


0xC0029268 


0xC0029269 


0xC002926A 


0xC002926B 


0xC002926C 


0xC002926D 


0OxC002926E 


0xC002926F 


0xC0029270 


0xC0029271 


0xC0029272 


0xC0029273 


DECIMAL CODE 


-1073573275 


-1073573274 


-1073573272 


-1073573271 


-1073573270 


-1073573269 


-1073573268 


-1073573267 


-1073573266 


-1073573265 


-1073573264 


-1073573263 


-1073573262 


-1073573261 


SYMBOLIC NAME 


DTS_E_XMLTASK_CANTGETR 
EADERFROMDEST 


DTS_E_XMLTASK_CANTGETR 
EADERFROMDIFFGRAM 


DTS_E_XMLTASK_EMPTYNO 
DELIST 


DTS_E_XMLTASK_NOELEME 
NTFOUND 


DTS_E_XMLTASK_UNDEFINE 
DOPERATION 


DTS_E_XMLTASK_XPATHNAV 
ERROR 


DTS_E_XMLTASK_NOSCHEM 
AFOUND 


DTS_E_XMLTASK_VALIDATI 
ONERROR 


DTS_E_XMLTASK_SYNCOBJE 
CTFAILED 


DTS_E_XMLTASK_ROOTNO 
ODESNOTMATCHED 


DTS_E_XMLTASK_INVALIDE 
DITSCRIPT 


DTS_E_XMLTASK_CDATANO 
DESISSUE 


DTS_E_XMLTASK_COMMEN 
TSNODEISSUE 


DTS_E_XMLTASK_TEXTNODE 
ISSUES 


DESCRIPTION 


Cannot get an XmlReader 
from the changed XML 
document. 


Cannot get the XDL 
diffgram reader from the 
XDL diffgram XML. 


The node list is empty. 


The element was not found. 


The Operations specified is 
not defined. 


Unexpected content item in 
XPathNavigator. 


No schema found to 
enforce validation. 


A validation error occurred 
when validating the 
instance document. 


Synchronization object 
failed. 


The root nodes do not 
match. 


The Edit Script Operation 
type in the final Edit Script 
is not valid. 


CDATA nodes should be 
added with 
DiffgramAddSubtrees class. 


Comment nodes should be 
added with 
DiffgramAddSubtrees class. 


Text nodes should be added 
with DiffgramAddSubtrees 
class. 


HEXADECIMAL CODE 


0xC0029274 


0xC0029275 


0xC0029276 


0xC0029277 


0xC0029278 


0xC0029279 


0xC002927B 


0xC002927C 


0xC002927D 


0xC002927E 


0xC002927F 


0xC0029280 


0xC0029281 


0xC0029282 


DECIMAL CODE 


-1073573260 


-1073573259 


-1073573258 


-1073573257 


-1073573256 


-1073573255 


-1073573253 


-1073573252 


-1073573251 


-1073573250 


-1073573249 


-1073573248 


-1073573247 


-1073573246 


SYMBOLIC NAME 


DTS_E_XMLTASK_WHITESPA 
CEISSUE 


DTS_E_XMLTASK_DIFFENU 
MISSUE 


DTS_E_XMLTASK_TASKISEM 
PTY 


DTS_E_XMLTASK_DOCUME 
NTHASDATA 


DTS_E_XMLTASK_INVALIDE 
NODETYPE 


DTS_E_XMLTASK_INVALIDD 
ATANODE 


DTS_E_XMLTASK_VARIABLET 
YPEISNOTSTRING 


DTS_E_XMLTASK_COULDN 
OTGETENCODINGFROMDO 
CUMENT 


DTS_E_XMLTASK_MISSINGS 
OURCE 


DTS_E_XMLTASK_MISSINGS 
ECONDOPERAND 


DTS_E_XMLTASK_INVALIDP 
ATHDESCRIPTOR 


DTS_E_XMLTASK_NOMATCH 
INGNODE 


DTS_E_XMLTASK_EXPECTIN 
GDIFFGRAMELEMENT 


DTS_E_XMLTASK_MISSINGS 
RCDOCATTRIBUTE 


DESCRIPTION 


Significant white space 
nodes should be added 
with DiffgramAddSubtrees 
class. 


Correct the OperationCost 
array so that it reflects the 
XmIDiffO peration 
enumeration. 


There are no operations in 
the task. 


The document already 
contains data and should 
not be used again. 


The node type is not valid. 


The XML Task received a 
task data node that is not 
valid. 


Variable data type is not a 
String. 


Cannot get encoding from 
XML. 


Source is not specified. 


Second operand is not 
specified. 


Invalid XDL diffgram. "%1" 
is an invalid path descriptor. 


Invalid XDL diffgram. No 
node matches the path 
descriptor "%1". 


Invalid XDL diffgram. 
Expecting xd:xmldiff as a 
root element with 
namespace URI "%1". 


The XDL diffgram is not 
valid. The srcDocHash 
attribute on the xd:xmldiff 
element is missing. 


HEXADECIMAL CODE 


0xC0029283 


0xC0029284 


0xC0029285 


0xC0029286 


0xC0029287 


0xC0029288 


0xC0029289 


0xC002928A 


0xC002928B 


OxC002928E 


0xC002928F 


0xC0029290 


DECIMAL CODE 


-1073573245 


-1073573244 


-1073573243 


-1073573242 


-1073573241 


-1073573240 


-1073573239 


-1073573238 


-1073573237 


-1073573234 


-1073573233 


-1073573232 


SYMBOLIC NAME 


DTS_E_XMLTASK_MISSINGO 
PTIONSATTRIBUTE 


DTS_E_XMLTASK_INVALIDSR 
CDOCATTRIBUTE 


DTS_E_XMLTASK_INVALIDO 
PTIONSATTRIBUTE 


DTS_E_XMLTASK_SRCDOCM 
ISMATCH 


DTS_E_XMLTASK_MORETHA 
NONENODEMATCHED 


DTS_E_XMLTASK_XMLDECL 
MISMATCH 


DTS_E_XMLTASK_INTERNAL 
ERRORMORETHANONENO 
DEINLIST 


DTS_E_XMLTASK_INTERNAL 
ERRORMORETHANONENO 
DELEFT 


DTS_E_XMLTASK_XSLTRESUL 
TFILEISNOTXML 


DTS_E_XMLTASK_FILEDOES 
NOTEXIST 


DTS_E_XMLTASK_XMLTEXTE 
MPTY 


DTS_E_XMLTASK_FILEALREA 
DYEXISTS 


DESCRIPTION 


The XDL diffgram is not 
valid. The options attribute 
on the xd:xmldiff element is 
missing. 


The XDL diffgram is not 
valid. The srcDocHash 
attribute has an invalid 
value. 


The XDL diffgram is not 
valid. The options attribute 
has an invalid value. 


The XDL diffgram is not 
applicable to this XML 
document. The rcDocHash 
value does not match. 


Invalid XDL diffgram; more 
than one node matches the 
"%1" path descriptor on the 
xd:node or xd:change 
element. 


The XDL diffgram is not 
applicable to this XML 
document. A new XML 
declaration cannot be 
added. 


Internal Error. 
XmIDiffPathSingleNodeList 
can contain only one node. 


Internal Error. "%1" nodes 
left after patch, expecting 1. 


The File/Text Produced by 
the XSLT is not a valid 
XmIDocument, thus can not 
be set as result of 
operation: "%1". 


There is no file associated 
with connection "%1". 


Property "%1" has no 
source Xml text; Xml Text is 
either invalid, null or empty 
string. 


File "%1" already exists. 


HEXADECIMAL CODE 


0xC0029293 


0xC0029294 


0xC0029295 


0xC0029296 


0xC0029297 


0xC0029298 


0xC0029299 


0xC002929A 


0xC002929B 


O0xC002929C 


0xC002929D 


OxC002929E 


0xC002929F 


DECIMAL CODE 


-1073573229 


-1073573228 


-1073573227 


-1073573226 


-1073573225 


-1073573224 


-1073573223 


-1073573222 


-1073573221 


-1073573220 


-1073573219 


-1073573218 


-1073573217 


SYMBOLIC NAME 


DTS_E_TRANSFERTASKS_SRC 
CONNECTIONREQUIRED 


DTS_E_TRANSFERTASKS_DES 
TCONNECTIONREQUIRED 


DTS_E_TRANSFERTASKS_CO 
NNECTIONNOTFOUND 


DTS_E_TRANSFERTASKS_SER 
VERVERSIONNOTALLOWED 


DTS_E_TRANSFERTASKS_SRC 
SERVERLESSEQUALDESTSER 
VER 


DTS_E_TRANSFERTASKS_SRC 
DBREQUIRED 


DTS_E_TRANSFERTASKS_SRC 
DBMUSTEXIST 


DTS_E_TRANSFERTASKS_DES 
TDBREQUIRED 


DTS_E_TRANSFERTASKS_SRC 
DBANDDESTDBTHESAME 


DTS_E_TRANSFERDBTASK_FI 
LENAMEREQUIRED 


DTS_E_TRANSFERDBTASK_F 
OLDERREQUIRED 


DTS_E_TRANSFERTASKS_NET 
SHAREREQUIRED 


DTS_E_TRANSFERTASKS FIL 
ELISTSCOUNTMISMATCH 


DESCRIPTION 


A source connection must 
be specified. 


A destination connection 
must be specified. 


The connection "%1" could 
not be found in the 
package. 


The connection "%1" 
specifies a SQL Server 
instance with a version that 
is not supported for 
transfer. Only versions 7, 
2000, and 2005 are 
>supported. 


The source connection "%1" 
must specify a SQL Server 
instance with a version 
earlier than or the same as 
the destination connection 
"%2". 


A source database must be 
specified. 


The source database "%1" 
must exist on the source 
server. 


A destination database 
must be specified. 


The source database and 
the destination database 
can not be the same. 


The transfer file information 
%1 is missing the filename. 


The transfer file information 
%1 is missing the folder 
part. 


The transfer file information 
%1 is missing the network 
share part. 


The number of source 
transfer files and the 
number of destination 
transfer files must be the 
same. 


HEXADECIMAL CODE 


0xC00292A0 


0xC00292A1 


0xC00292A2 


0xC00292A3 


0xC00292A4 


0xC00292A5 


0OxC00292A6 


0xC00292A7 


0xC00292A8 


0xC00292A9 


0xC00292B3 


OxC002F210 


DECIMAL CODE 


-1073573216 


-1073573215 


-1073573214 


-1073573213 


-1073573212 


-1073573211 


-1073573210 


-1073573209 


-1073573208 


-1073573207 


-1073573197 


-1073548784 


SYMBOLIC NAME 


DTS_E_DOESNOTSUPPORTT 
RANSACTIONS 


DTS_E_TRANSFERDBTASK_O 
FFLINEERROR 


DTS_E_TRANSFERDBTASK_N 
ETSHAREDOESNOTEXIST 


DTS_E_TRANSFERDBTASK_N 
ETSHARENOACCESS 


DTS_E_TRANSFERDBTASK_U 
SERMUSTBEDBOORSYSAD 
MIN 


DTS_E_TRANSFERDBTASK_U 
SERMUSTBESYSADMIN 


DTS_E_TRANSFERDBTASK_FT 
CATALOGSOFFLINEYUKON 
ONLY 


DTS_E_TRANSFERDBTASK_N 
OOVERWRITEDB 


DTS_E_TRANSFERDBTASK_M 
USTHAVESOURCEFILES 


DTS_E_TRANSFERDBTASKS_S 
RCFILENOTFOUND 


DTS_E_MSMQITASK_FIPS140 
2COMPLIANCE 


DTS_E_SQLTASK_ERROREXE 
CUTINGTHEQUERY 


DESCRIPTION 


Enlisting in transactions is 
not supported. 


The following exception 
occurred during an offline 
database transfer: %1. 


The network share "%1" 
could not be found. 


The network share "%1 
could not be accessed. The 
error is: %2. 


The user "%1" must be a 
DBO or a sysadmin for "%2" 
in order to perform an 
online database transfer. 


The user "%1" must be a 
sysadmin on "%2" to 
perform an offline database 
transfer. 


Full text catalogs can only 
be included when 
performing an offline 
database transfer between 
2 SQL Server 2005 servers. 


The database "%1" already 
exists on the destination 
server "%2". 


At least one source file 
must be specified. 


Could not find the file "%1" 
in the source database 
"%2". 


The operation requested is 
not allowed in systems 
compliant with U.S. FIPS 
140-2. 


Executing the query "%1" 
failed with the following 
error: "%2". Possible failure 
reasons: Problems with the 
query, "ResultSet" property 
not set correctly, 
>parameters not set 
correctly, or connection not 
established correctly. 


HEXADECIMAL CODE 


OxC002F300 


0xC002F301 


OxC002F302 


OxC002F303 


OxC002F304 


OxC002F305 


OxC002F306 


OxC002F307 


OxC002F308 


OxC002F309 


OxCO002F30A 


OxC002F30B 


OxCO002F30C 


OxC002F30D 


OxCO002F30E 


DECIMAL CODE 


-1073548544 


-1073548543 


-1073548542 


-1073548541 


-1073548540 


-1073548539 


-1073548538 


-1073548537 


-1073548536 


-1073548535 


-1073548534 


-1073548533 


-1073548532 


-1073548531 


-1073548530 


SYMBOLIC NAME 


DTS_E_TRANSFERSPTASK_ER 
RORREADINGSPNAMES 


DTS_E_TRANSFERSPTASK_IN 
VALIDDATANODE 


DTS_E_TRANSFERTASKS_CO 
NNECTIONTYPEISNOTSMO 
SERVER 


DTS_E_TRANSFERSPTASK_EX 
ECUTIONFAILED 


DTS_E_ERROROCCURREDWI 
THFOLLOWINGMESSAGE 


DTS_E_BITASK_EXECUTION_ 
FAILED 


DTS_E_FSTASK_INVALIDDES 
TPATH 


DTS_E_FSTASK_CANTCREATE 
DIR 


DTS_E_SQLTASK_ODBCNOS 
UPPORTTRANSACTION 


DTS_E_SQLTASK_ERRORASSI 
GINGVALUETOVAR 


DTS_E_FSTASK_SOURCEISE 
MPTY 


DTS_E_FSTASK_DESTINATIO 
NISEMPTY 


DTS_E_FSTASK_FILEDIRNOT 
FOUND 


DTS_E_FSTASK_VARSRCORD 
ESTISEMPTY 


DTS_E_FSTASK_FILEDELETED 


DESCRIPTION 


Error reading stored 
procedure names from the 
xml file. 


Invalid data node for the 
Transfer Stored Procedure 
task. 


Connection "%1" is not of 
type "SMOServer". 


Execution failed with the 
following error "%1". 


An error occurred with the 
following error message: 
"O61", 


Bulk insert execution failed. 


Invalid destination path. 


Can not create directory. 
User chose to fail the task if 
directory exists. 


The task has a transaction 
option of "Required" and 
connection "%1" is of type 
"ODBC". ODBC connections 
don't support transactions. 


An error occurred while 
assigning a value to variable 
no" "Oh". 


The source is empty. 


The destination is empty. 


File or directory "%1" does 
not exist. 


Variable "%1" is used as a 
source or destination and is 
empty. 


File or directory "%1" was 
deleted. 


HEXADECIMAL CODE 


OxC002F30F 


0xC002F310 


0xC002F311 


OxC002F312 


0xC002F313 


OxC002F314 


OxC002F315 


0xC002F316 


OxC002F317 


OxC002F318 


0OxC002F319 


OxC002F320 


OxC002F321 


DECIMAL CODE 


-1073548529 


-1073548528 


-1073548527 


-1073548526 


-1073548525 


-1073548524 


-1073548523 


-1073548522 


-1073548521 


-1073548520 


-1073548519 


-1073548512 


-1073548511 


SYMBOLIC NAME 


DTS_E_FSTASK_DIRECTORY 
DELETED 


DTS_E_WMIDRTASK_VARIAB 
LETYPEISNOTOBJECT 


DTS_E_WMIDRTASK_VARIAB 
LETYPEISNOTSTRING 


DTS_E_FTPTASK_CANNOTAC 
QUIRECONNECTION 


DTS_E_FTPTASK_CONNECTI 
ONNOTFOUND 


DTS_E_FTPTASK_FILEUSAGE 
TYPEERROR 


DTS_E_TRANSFERTASKS_SO 
URCECANTBESAMEASDESTI 
NATION 


DTS_E_ERRMSGTASK_EMPT 
YSOURCELIST 


DTS_E_ERRMSGTASK_DIFFE 
RENTMESSAGEANDLANGU 
AGESIZES 


DTS_E_ERRMSGTASK_ERRO 
RMESSAGEOUTOFRANGE 


DTS_E_TRANSFERTASKS_NO 
TRANSACTIONSUPPORT 


DTS_E_ERRMSGTASK_FAILE 
DTOTRANSFERERRORMESS 
AGES 


DTS_E_ERRMSGTASK_ERRO 
RMESSAGEALREADY EXISTS 


DESCRIPTION 


Directory "%1" was deleted. 


The variable "%1" should be 
of type object to be 
assigned a data table. 


The variable "%1" does not 
have a string data type. 


There was an error 
acquiring the FTP 
connection. Verify that a 
valid connection type is 
specified in "%1". 


The FTP connection 
manager "%1" can not be 
found. 


File usage type of 
connection "%1" should be 
"%2" for operation "%3". 


The source server can not 
be the same as the 
destination server. 


There are no Error 
Messages to transfer. 


The lists of error messages 
and their corresponding 
languages are of different 
sizes. 


The error message id "%1" 
is out of the allowed range 
of user defined error 
messages. User defined 
error message ids are 
between 50000 and 
2147483647. 


This task can not participate 
in a transaction. 


Failed to transfer some or 
all of the Error Messages. 


The error message "%1" 
already exists at destination 
server. 


HEXADECIMAL CODE 


OxC002F324 


OxC002F325 


OxC002F327 


OxC002F330 


0xC002F331 


OxC002F334 


OxC002F337 


0xC002F338 


OxC002F340 


OxC002F342 


OxC002F344 


OxC002F345 


OxC002F346 


OxC002F349 


OxC002F350 


OxC002F353 


DECIMAL CODE 


-1073548508 


-1073548507 


-1073548505 


-1073548496 


-1073548495 


-1073548492 


-1073548489 


-1073548488 


-1073548480 


-1073548478 


-1073548476 


-1073548475 


-1073548474 


-1073548471 


-1073548464 


-1073548461 


SYMBOLIC NAME 


DTS_E_ERRMSGTASK_ERRO 
RMESSAGECANTBEFOUND 


DTS_E_TRANSFERTASKS_EXE 
CUTIONFAILED 


DTS_E_JOBSTASK_FAILEDTO 
TRANSFERJOBS 


DTS_E_JOBSTASK_EMPTYSO 
URCELIST 


DTS_E_JOBSTASK_JOBEXIST 
SATDEST 


DTS_E_JOBSTASK_JOBCANT 
BEFOUND 


DTS_E_LOGINSTASK_EMPTY 
LIST 


DTS_E_LOGINSTASK_CANTG 
ETLOGINSNAMELIST 


DTS_E_LOGINSTASK_ERROR 
LOGINEXISTS 


DTS_E_LOGINSTASK_LOGIN 
NOTFOUND 


DTS_E_LOGINSTASK_FAILED 
TOTRANSFERLOGINS 


DTS_E_STOREDPROCSTASK_ 
FAILEDTOTRANSFERSPS 


DTS_E_STOREDPROCSTASK_ 
STOREDPROCNOTFOUND 


DTS_E_STOREDPROCSTASK_ 
ERRORSTOREDPROCEDURE 
EXISTS 


DTS_E_STOREDPROCSTASK_ 
EMPTYSOURCELIST 


DTS_E_TRANSOBJECTSTASK 
_FAILEDTOTRANSFEROBJEC 
TS 


DESCRIPTION 


The error message "%1" can 
not be found at source 
server. 


Execution failed with the 
following error: "%1". 


Failed to transfer the Job(s). 


There are no Jobs to 
transfer. 


The job "%1" already exists 
at destination server. 


The job "%1" can not be 
found at source server. 


The list of "Logins" to 
transfer is empty. 


Can not get the list of 
"Logins" from source server. 


Login "%1" already exists at 
destination server. 


Login "%1" does not exist at 
source. 


Failed to transfer some or 
all of the logins. 


Failed to transfer the stored 
procedure(s). More 
informative error should 
have been raised. 


Stored Procedure "%1" is 
not found at the source. 


Stored procedure "%1" 
already exists at destination 
server. 


There are no stored 
procedures to transfer. 


Failed to transfer the 
object(s). 


HEXADECIMAL CODE 


OxC002F354 


OxC002F355 


OxC002F356 


OxC002F357 


OxC002F359 


OxC002F360 


0xC002F361 


OxC002F363 


OxC002F364 


OxC002F365 


OxC002F367 


OxC002F368 


OxC002F369 


OxC002F371 


OxC002F372 


OxC002F373 


DECIMAL CODE 


-1073548460 


-1073548459 


-1073548458 


-1073548457 


-1073548455 


-1073548448 


-1073548447 


-1073548445 


-1073548444 


-1073548443 


-1073548441 


-1073548440 


-1073548439 


-1073548431 


-1073548430 


-1073548429 


SYMBOLIC NAME 


DTS_E_TRANSOBJECTSTASK 
_EMPTYLIST 


DTS_E_TRANSOBJECTSTASK 
_NOSPATSOURCE 


DTS_E_TRANSOBJECTSTASK 
_SPALREADYATDEST 


DTS_E_TRANSOBJECTSTASK 
_ERRORHANDLINGSPS 


DTS_E_TRANSOBJECTSTASK 
_NORULEATSOURCE 


DTS_E_TRANSOBJECTSTASK 
_RULEALREADYATDEST 


DTS_E_TRANSOBJECTSTASK 
_ERRORHANDLINGRULES 


DTS_E_TRANSOBJECTSTASK 
_NOTABLEATSOURCE 


DTS_E_TRANSOBJECTSTASK 
_TABLEALREADYATDEST 


DTS_E_TRANSOBJECTSTASK 
_ERRORHANDLINGTABLES 


DTS_E_TRANSOBJECTSTASK 
_NOVIEWATSOURCE 


DTS_E_TRANSOBJECTSTASK 
_VIEWALREADYATDEST 


DTS_E_TRANSOBJECTSTASK 
_ERRORHANDLINGVIEWS 


DTS_E_TRANSOBJECTSTASK 
_NOUDFATSOURCE 


DTS_E_TRANSOBJECTSTASK 
_UDFALREADYATDEST 


DTS_E_TRANSOBJECTSTASK 
_ERRORHANDLINGUDFS 


DESCRIPTION 


The list of "Objects" to 
transfer is empty. 


Stored procedure "%1" does 
not exist at the source. 


Stored procedure "%1" 
already exists at destination. 


An error occurred while 
trying to get set the Stored 
Procedures list to transfer: 
"%1". 


Rule "%1" does not exist at 
the source. 


Rule "%1" already exists at 
destination. 


An error occurred while 
trying to get set the Rules 
list to transfer: "%1". 


Table "%1" does not exist at 
the source. 


Table "%1" already exists at 
destination. 


An error occurred while 
trying to get set the Tables 
list to transfer: "%1". 


View "%1" does not exist at 
the source. 


View "%1" already exists at 
destination. 


An error occurred while 
trying to get set the Views 
list to transfer: "%1". 


User Defined Function "%1" 
does not exist at the source. 


User Defined Function "%1" 
already exists at destination. 


An error occurred while 
trying to get set the User 
Defined Functions list to 
transfer: "%1". 


HEXADECIMAL CODE 


OxC002F375 


OxC002F376 


OxC002F377 


OxC002F379 


OxC002F380 


0xC002F381 


OxC002F383 


OxC002F384 


OxC002F385 


OxC002F387 


OxC002F388 


OxC002F389 


0xC002F391 


OxC002F392 


DECIMAL CODE 


-1073548427 


-1073548426 


-1073548425 


-1073548423 


-1073548416 


-1073548415 


-1073548413 


-1073548412 


-1073548411 


-1073548409 


-1073548408 


-1073548407 


-1073548399 


-1073548398 


SYMBOLIC NAME 


DTS_E_TRANSOBJECTSTASK 
_NODEFAULTATSOURCE 


DTS_E_TRANSOBJECTSTASK 
_DEFAULTALREADYATDEST 


DTS_E_TRANSOBJECTSTASK 
_ERRORHANDLINGDEFAUL 
TS 


DTS_E_TRANSOBJECTSTASK 
_NOUDDTATSOURCE 


DTS_E_TRANSOBJECTSTASK 
_UDDTALREADYATDEST 


DTS_E_TRANSOBJECTSTASK 
_ERRORHANDLINGUDDTS 


DTS_E_TRANSOBJECTSTASK 
_NOPFATSOURCE 


DTS_E_TRANSOBJECTSTASK 
_PFALREADYATDEST 


DTS_E_TRANSOBJECTSTASK 
_ERRORHANDLINGPFS 


DTS_E_TRANSOBJECTSTASK 
_NOPSATSOURCE 


DTS_E_TRANSOBJECTSTASK 
_PSALREADYATDEST 


DTS_E_TRANSOBJECTSTASK 
_ERRORHANDLINGPSS 


DTS_E_TRANSOBJECTSTASK 
_NOSCHEMAATSOURCE 


DTS_E_TRANSOBJECTSTASK 
_SCHEMAALREADYATDEST 


DESCRIPTION 


Default "%1" does not exist 
at the source. 


Default "%1" already exists 
at destination. 


An error occurred while 
trying to get set the 
Defaults list to transfer: 
"%1". 


User Defined Data Type 
"%1" does not exist at the 
source. 


User Defined Data Type 
"%1" already exists at 
destination. 


An error occurred while 
trying to get set the User 
Defined Data Types list to 
transfer: "%1". 


Partition Function "%1" 
does not exist at the source. 


Partition Function "%1" 
already exists at destination. 


An error occurred while 
trying to get set the 
Partition Functions list to 
transfer: "%1". 


Partition Scheme "%1" does 
not exist at the source. 


Partition Scheme "%1" 
already exists at destination. 


An error occurred while 
trying to get set the 
Partition Schemes list to 
transfer: "%1". 


Schema "%1" does not exist 
at the source. 


Schema "%1" already exists 
at destination. 


HEXADECIMAL CODE 


OxC002F393 


OxC002F395 


OxC002F396 


OxC002F397 


OxC002F399 


OxC002F400 


OxC002F401 


OxC002F403 


OxC002F404 


OxC002F405 


OxC002F407 


OxC002F408 


OxC002F409 


DECIMAL CODE 


-1073548397 


-1073548395 


-1073548394 


-1073548393 


-1073548391 


-1073548288 


-1073548287 


-1073548285 


-1073548284 


-1073548283 


-1073548281 


-1073548280 


-1073548279 


SYMBOLIC NAME 


DTS_E_TRANSOBJECTSTASK 
_ERRORHANDLINGSCHEM 
AS 


DTS_E_TRANSOBJECTSTASK 
_NOSQLASSEMBLYATSOUR 
CE 


DTS_E_TRANSOBJECTSTASK 
_SQLASSEMBLYALREADYAT 
DEST 


DTS_E_TRANSOBJECTSTASK 
_ERRORHANDLINGSQLASS 
EMBLIES 


DTS_E_TRANSOBJECTSTASK 
_NOAGGREGATEATSOURCE 


DTS_E_TRANSOBJECTSTASK 
_AGGREGATEALREADYATDE 
ST 


DTS_E_TRANSOBJECTSTASK 
_ERRORHANDLINGAGGREG 
ATES 


DTS_E_TRANSOBJECTSTASK 
_NOTYPEATSOURCE 


DTS_E_TRANSOBJECTSTASK 
_TYPEALREADYATDEST 


DTS_E_TRANSOBJECTSTASK 
_ERRORHANDLINGTY PES 


DTS_E_TRANSOBJECTSTASK 
_NOXMLSCHEMACOLLECTI 
ONATSOURCE 


DTS_E_TRANSOBJECTSTASK 
_XMLSCHEMACOLLECTION 
ALREADYATDEST 


DTS_E_TRANSOBJECTSTASK 
_ERRORHANDLINGXMLSCH 
EMACOLLECTIONS 


DESCRIPTION 


An error occurred while 
trying to get set the 
Schemas list to transfer: 
"%1", 


SqlAssembly "%1" does not 
exist at the source. 


SqlAssembly "%1" already 
exists at destination. 


An error occurred while 
trying to get set the 
SqlAssemblies list to 
transfer: "%1". 


User Defined Aggregate 
"%1" does not exist at the 
source. 


User Defined Aggregate 
"%1" already exists at 
destination. 


An error occurred while 
trying to get set the User 
Defined Aggregates list to 
transfer: "%1". 


User Defined Type "%1" 
does not exist at the source. 


User Defined Type "%1" 
already exists at destination. 


An error occurred while 
trying to get set the User 
Defined Types list to 
transfer: "%1". 


XmlSchemaCollection "%1" 
does not exist at the source. 


XmlSchemaCollection "%1" 
already exists at destination. 


An error occurred while 
trying to get set the 
XmlSchemaCollections list 
to transfer: "%1". 


HEXADECIMAL CODE 


OxC002F411 


OxC002F413 


OxC002F414 


0xC002F416 


OxC002F417 


OxC002F419 


OxC002F41B 


OxC002F41C 


OxC002F41F 


OxC002F421 


OxC002F426 


OxC002F428 


OxC002F429 


DECIMAL CODE 


-1073548271 


-1073548269 


-1073548268 


-1073548266 


-1073548265 


-1073548263 


-1073548261 


-1073548260 


-1073548257 


-1073548255 


-1073548250 


-1073548248 


-1073548247 


SYMBOLIC NAME 


DTS_E_TRANSOBJECTSTASK 
_SUPPORTEDONYUKONON 
LY 


DTS_E_LOGINSTASK_EMPTY 
DATABASELIST 


DTS_E_TRANSOBJECTSTASK 
_NOLOGINATSOURCE 


DTS_E_TRANSOBJECTSTASK 
_LOGINALREADYATDEST 


DTS_E_TRANSOBJECTSTASK 
_ERRORHANDLINGLOGINS 


DTS_E_TRANSOBJECTSTASK 
_NOUSERATSOURCE 


DTS_E_TRANSOBJECTSTASK 
_USERALREADYATDEST 


DTS_E_TRANSOBJECTSTASK 
_ERRORHANDLINGUSERS 


DTS_E_BITASK_CANNOTRET 
AINCONNINTRANSACTION 


DTS_E_SQLTASKOUTPUTEN 
CODINGNOTSUPPORTED 


DTS_E_FTPTASK_FILECONNE 
CTIONNOTFOUND 


DTS_E_TRANSOBJECTSTASK 
_CANNOTDROPOBJECTS 


DTS_E_SQLTASK_PARAMSIZ 
EERROR 


DESCRIPTION 


Objects of type "%1" are 
only supported between 
SQL Server 2005 or newer 
servers. 


The databases list is empty. 


Login "%1" does not exist at 
the source. 


Login "%1" already exists at 
destination. 


An error occurred while 
trying to get set the Logins 
list to transfer: "%1". 


User "%1" does not exist at 
the source. 


User "%1" already exists at 
destination. 


An error occurred while 
trying to get set the Users 
list to transfer: "%1". 


The task can not have a 
retained connection 
manager in a transaction. 


Unable to obtain XML data 
from SQL Server as Unicode 
because the provider does 
not support the 
OUTPUTENCODING 


property. 


For the FTP operation "%1", 
the FILE connection 
manager "%2" can not be 
found. 


"Logins" are server level 
objects and can not be 
dropped first since the 
source and destination are 
the same server. Dropping 
objects first will remove 
>the logins from the source 
as well. 


Parameter "%1" cannot be 
negative. (-1) is used for the 
default value. 


HEXADECIMAL CODE 


0xC0040019 


0xC0040020 


0xC0040040 


0xC0040041 


0xC0040042 


0xC0040043 


0xC0040044 


0xC0040045 


0xC0040046 


0xC0040047 


0xC0040048 


0xC0047000 


0xC0047001 


0xC0047002 


DECIMAL CODE 


-1073479655 


-1073479648 


-1073479616 


-1073479615 


-1073479614 


-1073479613 


-1073479612 


-1073479611 


-1073479610 


-1073479609 


-1073479608 


-1073451008 


-1073451007 


-1073451006 


SYMBOLIC NAME 


DTS_E_UNREGISTEREDPIPEL 
INEXML_LOAD 


DTS_E_UNREGISTEREDPIPEL 
INEXML_SAVE 


DTS_E_PIPELINE_SAVE 


DTS_E_PIPELINE_LOAD 


DTS_E_SAVE_PERSTFORMAT 


DTS_E_LOAD_PERSTFORMA 
T 


DTS_E_SETPERSIST_PROPEV 
ENTS 


DTS_E_SETPERSIST_XMLDO 
M 


DTS_E_SETPERSIST_XMLNO 
DE 


DTS_E_SETPERSISTPROP_FAI 
LED 


DTS_E_NOCUSTOMPROPC 
OL 


DTS_E_CYCLEINEXECUTION 
TREE 


DTS_E_DISCONNECTEDOBJ 
ECT 


DTS_E_INVALIDOBJECTID 


DESCRIPTION 


Data Flow objects cannot 
be loaded. Check if 
Microsoft.SqlServer Pipeline 
Xml.dll is properly 
registered. 


Data Flow objects cannot 
be saved. Check if 
Microsoft.SqlServerPipeline 
Xml.dll is properly 
registered. 


Failed to save Data Flow 
objects. 


Failed to load Data Flow 
objects 


Failed to save Data Flow 
objects. The specified 
format is not supported. 


Failed to load Data Flow 
objects. The specified 
format is not supported. 


Failed to set the XML 
persistence events property 
for the Data Flow objects. 


Failed to set the persistence 
XML DOM property for the 
Data Flow objects. 


Failed to set the persistence 
XML ELEMENT property for 
the Data Flow objects. 


Failed to set xml persistence 
properties for the Data 
Flow objects. 


Failed to get custom 
property collection for Data 
Flow components. 


An execution tree contains 
a cycle. 


The %1 object "%2" (%3!d!) 
is disconnected from the 
layout. 


The ID for the layout object 
is not valid. 


HEXADECIMAL CODE 


0xC0047003 


0xC0047005 


0xC0047006 


0xC0047008 


0xC0047009 


0xC004700A 


0xC004700B 


0xC004700C 


0xC004700D 


0xC004700E 


0xC004700F 


0xC0047010 


0xC0047011 


DECIMAL CODE 


-1073451005 


-1073451003 


-1073451002 


-1073451000 


-1073450999 


-1073450998 


-1073450997 


-1073450996 


-1073450995 


-1073450994 


-1073450993 


-1073450992 


-1073450991 


SYMBOLIC NAME 


DTS_E_INPUTWITHOUTPAT 
HS 


DTS_E_INVALIDSYNCHRON 
OUSINPUT 


DTS_E_INVALIDOUTPUTLIN 
EAGEID 


DTS_E_DUPLICATENAMESIN 
COLLECTION 


DTS_E_INVALIDEXCLUSION 
GROUP 


DTS_E_DUPLICATELINEAGEI 
DSINCOLLECTION 


DTS_E_VALIDATIONFAILED 
ONLAYOUT 


DTS_E_VALIDATIONFAILED 
ONCOMPONENTS 


DTS_E_VALIDATIONFAILED 


DTS_E_THREADSTARTUPFAI 
LED 


DTS_E_CANTGETMUTEX 


DTS_E_CANTGETSEMAPHO 
RE 


DTS_E_BUFFERFAILUREDETA 
ILS 


DESCRIPTION 


A required input object is 
not connected to a path 
object. 


%1 has an invalid 
synchronous input ID 
%2!dl. 


%1 has lineage ID %2!d!, 
but should have had %3!d!. 


The package contains two 
objects with the duplicate 
name of "%1" and "%2". 


The "%1" and the "%2" are 
in the same exclusion 
group, but they do not 
have the same synchronous 
input. 


Two objects in the same 
collection have a duplicate 
lineage ID of %1!d!. The 
objects are %2 and %3. 


The layout failed validation. 


One or more component 
failed validation. 


The layout and one or more 
components failed 
validation. 


The Data Flow task engine 
failed at startup because it 
cannot create one or more 
required threads. 


A thread failed to create a 
mutex at initialization. 


A thread failed to create a 
semaphore at initialization. 


The system reports %1!d! 
percent memory load. 
There are %2 bytes of 
physical memory with %3 
bytes free. There are %4 
bytes of virtual memory 
with %5 bytes free. The 
>paging file has %6 bytes 
with %7 bytes free. 


HEXADECIMAL CODE 


0xC0047012 


0xC0047013 


0xC0047015 


0xC0047016 


0xC0047017 


0xC0047018 


0xC0047019 


0xC004701A 


0xC004701B 


0xC004701C 


0xC004701E 


0xC004701F 


0xC0047020 


DECIMAL CODE 


-1073450990 


-1073450989 


-1073450987 


-1073450986 


-1073450985 


-1073450984 


-1073450983 


-1073450982 


-1073450981 


-1073450980 


-1073450978 


-1073450977 


-1073450976 


SYMBOLIC NAME 


DTS_E_BUFFERALLOCFAILE 
D 


DTS_E_CANTCREATEBUFFER 
MANAGER 


DTS_E_BUFFERBADSIZE 


DTS_E_DANGLINGWITHPAT 
H 


DTS_E_INDIVIDUALVALIDAT 
IONFAILED 


DTS_E_INDIVIDUALPOSTEX 
ECUTEFAILED 


DTS_E_INDIVIDUALPREPAR 
EFAILED 


DTS_E_INDIVIDUALPREEXE 
CUTEFAILED 


DTS_E_INDIVIDUALCLEANU 
PFAILED 


DTS_E_INVALIDINPUTLINEA 
GEID 


DTS_E_EXECUTIONTREECYC 
LE 


DTS_E_CANTCOMPARE 


DTS_E_REFUSEDFORSHUTD 
OWN 


DESCRIPTION 


A buffer failed while 
allocating %1!d! bytes. 


The Buffer Manager could 
not be created. 


Buffer Type %1!d! had a size 
of %2!164d! bytes. 


%1 is marked as dangling, 
but has a path attached to 
it. 


%1 failed validation and 
returned error code 
0x%2!8.8X!. 


%1 failed the post-execute 
phase and returned error 
code 0x%2!8.8X!. 


%! failed the prepare phase 
and returned error code 
0x%2!8.8X!. 


%1 failed the pre-execute 
phase and returned error 
code 0x%2!8.8X!. 


%1 failed the cleanup phase 
and returned error code 
0x%2!8.8X!. 


%1 has lineage ID %2!d! 
that was not previously 
used in the Data Flow task. 


Cannot connect %1 to %2 
because a cycle would be 
created. 


The data type "%1" cannot 
be compared. Comparison 
of that data type is not 
supported, so it cannot be 
sorted or used as a key. 


This thread has shut down 
and is not accepting buffers 
for input. 


HEXADECIMAL CODE 


0xC0047021 


0xC0047022 


0xC0047023 


0xC0047024 


0xC0047028 


0xC0047029 


DECIMAL CODE 


-1073450975 


-1073450974 


-1073450973 


-1073450972 


-1073450968 


-1073450967 


SYMBOLIC NAME 


DTS_E_THREADFAILED 


DTS_E_PROCESSINPUTFAILE 
D 


DTS_E_CANTREALIZEVIRTU 
ALBUFFERS 


DTS_E_PIPELINETOOCOMP 
LEX 


DTS_E_SCHEDULERCOULD 
NOTCOUNTSOURCES 


DTS_E_SCHEDULERCOULD 
NOTCOUNTDESTINATIONS 


DESCRIPTION 


SSIS Error Code 
DTS_E_THREADFAILED. 
Thread "%1" has exited with 
error code 0x%2!8.8X!. 
There may be error 
messages posted before 
this with more information 
on why the >thread has 
exited. 


SSIS Error Code 
DTS_E_PROCESSINPUTFAILE 
D. The ProcessInput 
method on component 
"261" (%2!d!) failed with 
error code 0x%3!8.8X! while 
processing input "%4" 
(%5!d!). The > identified 
component returned an 
error from the ProcessInput 
method. The error is specific 
to the component, but the 
error is fatal and will cause 
the Data Flow task to stop 
running. There may be error 
messages > posted before 
this with more information 
about the failure. 


A set of virtual buffers 
cannot be realized. 


The number of threads 
required for this pipeline is 
%1'!d!, which is more than 
the system limit of %2!d!. 
The pipeline requires too 
many threads as 
configured. There >are 
either too many 
asynchronous outputs, or 
EngineThreads property is 
set too high. Split the 
pipeline into multiple 
packages, or reduce the 
value of the EngineThreads 


property. 


The Data Flow engine 
scheduler cannot obtain a 
count of the sources in the 
layout. 


The Data Flow engine 
scheduler cannot obtain a 
count of the destinations in 
the layout. 


HEXADECIMAL CODE 


0xC004702A 


0xC004702B 


0xC004702C 


0xC004702D 


0xC004702E 


0xC004702F 


0xC0047030 


0xC0047031 


0xC0047032 


DECIMAL CODE 


-1073450966 


-1073450965 


-1073450964 


-1073450963 


-1073450962 


-1073450961 


-1073450960 


-1073450959 


-1073450958 


SYMBOLIC NAME 


DTS_E_COMPONENTVIEWIS 
UNAVAILABLE 


DTS_E_INCORRECTCOMPO 
NENTVIEWID 


DTS_E_BUFFERNOTLOCKED 


DTS_E_CANTBUILDBUFFERT 
YPE 


DTS_E_CANTREGISTERBUFF 
ERTYPE 


DTS_E_INVALIDUSESDISPOS 
ITIONSVALUE 


DTS_E_THREADFAILEDINITI 
ALIZE 


DTS_E_THREADFAILEDCREA 
TE 


DTS_E_EXECUTIONTREECYC 
LEADDINGSYNCHRONOUSI 
NPUT 


DESCRIPTION 


The component view is 
unavailable. Make sure the 
component view has been 
created. 


The component view ID is 
incorrect. The component 
view may be out of 
synchronization. Try 
releasing the component 
view and recreating it. 


This buffer is not locked and 
cannot be manipulated. 


The Data Flow task cannot 
allocate memory to build a 
buffer definition. The buffer 
definition had %1!d! 
columns. 


The Data Flow task cannot 
register a buffer type. The 
type had %1!d! columns 
and was for execution tree 
%2!d). 


The UsesDispositions 
property cannot be 
changed from its initial 
value. This occurs when the 
XML is edited and the 
UsesDispositions value is 
modified. This >value is set 
by the component when it 
is added to the package 
and is not allowed to 
change. 


The Data Flow task failed to 
initialize a required thread 
and cannot begin execution. 
The thread previously 
reported a specific error. 


The Data Flow task failed to 
create a required thread 
and cannot begin running. 
The usually occurs when 
there is an out-of-memory 
state. 


The synchronous input of 
"%1" cannot be set to "%2" 
because a cycle would be 
created. 


HEXADECIMAL CODE 


0xC0047033 


0xC0047035 


0xC0047036 


0xC0047037 


0xC0047038 


0xC0047039 


DECIMAL CODE 


-1073450957 


-1073450955 


-1073450954 


-1073450953 


-1073450952 


-1073450951 


SYMBOLIC NAME 


DTS_E_INVALIDCUSTOMPR 
OPERTYNAME 


DTS_E_BUFFERLOCKUNDER 
FLOW 


DTS_E_INDIVIDUALCACHEI 
NTERFACESFAILED 


DTS_E_INDIVIDUALRELEASE 
INTERFACESFAILED 


DTS_E_PRIMEOUTPUTFAILE 
D 


DTS_E_THREADCANCELLED 


DESCRIPTION 


A custom property named 
"%1" is invalid because 
there is a stock property 
with that name. A custom 
property cannot have the 
same name as a stock 
property on the >same 
object. 


The buffer was already 
unlocked. 


%1 failed initialization and 
returned error code 
0x%2!8.8X!. 


%1 failed during shut down 
and returned error code 
0x%2!8.8X!. A component 
failed to release its 
interfaces. 


SSIS Error Code 
DTS_E_PRIMEOUTPUTFAILE 
D. The PrimeOutput 
method on %1 returned 
error code 0x%2!8.8X!. The 
component returned a 
failure code when the 
pipeline engine >called 
PrimeOutput(). The 
meaning of the failure code 
is defined by the 
component, but the error is 
fatal and the pipeline 
stopped executing. There 
may be error messages 
posted before this with 
more information > about 
the failure. 


SSIS Error Code 
DTS_E_THREADCANCELLED. 
Thread "%1" received a 
shutdown signal and is 
terminating. The user 
requested a shutdown, or 
an error in another thread 
is causing >the pipeline to 
shutdown. There may be 
error messages posted 
before this with more 
information on why the 
thread was cancelled. 


HEXADECIMAL CODE 


0xC004703A 


0xC004703B 


0xC004703F 


0xC0047040 


0xC0047041 


0xC0047043 


0xC0047046 


0xC0047047 


0xC0047048 


0xC0047049 


DECIMAL CODE 


-1073450950 


-1073450949 


-1073450945 


-1073450944 


-1073450943 


-1073450941 


-1073450938 


-1073450937 


-1073450936 


-1073450935 


SYMBOLIC NAME 


DTS_E_DISTRIBUTORCANTS 
ETPROPERTY 


DTS_E_CANTREGISTERVIEW 
BUFFERTYPE 


DTS_E_CANTCREATEEXECUT 
IONTREE 


DTS_E_CANTINSERTINTOHA 
SHTABLE 


DTS_E_OBJECTNOTINHASH 


TABLE 


DTS_E_CANTCREATECOMP 
ONENTVIEW 


DTS_E_LAYOUTCANTSETUS 
AGETYPE 


DTS_E_WRONGOBJECTTYPE 


DTS_E_CANTCREATESPOOL 
FILE 


DTS_E_SEEKFAILED 


DESCRIPTION 


Distributor for thread "%1" 
failed to initialize property 
"%2" on component "%3" 
because of error 0x%8.8X. 
The distributor could not 
initialize the component's 
> property and cannot 
continue running. 


The Data Flow task cannot 
register a view buffer type. 
The type had %1!d! 
columns and was for input 
ID %2!d!. 


There is not enough 
memory to create an 
execution tree. 


There is not enough 
memory to insert an object 
into the hash table. 


The object is not in the 
hash table. 


Cannot create a component 
view because another one 
already exists. Only one 
component view can exist 
at a time. 


At input "%1" (%2!d!), the 
virtual input column 
collection does not contain 
a virtual input column with 
lineage ID %3!d!. 


The requested object has 
the incorrect object type. 


The buffer manager cannot 
create a temporary storage 
file on any path in the 
BufferTtempStoragePath 
property. There is an 
incorrect file name or no 
permission or the > paths 
have been full. 


The buffer manager could 
not seek to offset %1!d! in 
file "%2". The file is 
damaged. 


HEXADECIMAL CODE 


0xC004704A 


0xC004704B 


0xC004704C 


0xC004704D 


0xC004704E 


0xC004704F 


0xC0047050 


0xC0047051 


0xC0047053 


DECIMAL CODE 


-1073450934 


-1073450933 


-1073450932 


-1073450931 


-1073450930 


-1073450929 


-1073450928 


-1073450927 


-1073450925 


SYMBOLIC NAME 


DTS_E_EXTENDFAILED 


DTS_E_FILEWRITEFAILED 


DTS_E_FILEREADFAILED 


DTS_E_VIRTUALNOTSEQUE 
NTIAL 


DTS_E_BUFFERISREADONLY 


DTS_E_EXECUTIONTREECYC 
LESETTINGID 


DTS_E_NOMOREBUFFERTYP 
ES 


DTS_E_CANTCREATENEWTY 
PE 


DTS_E_SCHEDULERBADTREE 


DESCRIPTION 


The buffer manager cannot 
extend the file "%1" to 
length %2!lu! bytes. There 
was insufficient disk space. 


The buffer manager cannot 
write %1!d! bytes to file 
"%2.". There was insufficient 
disk space or quota. 


The buffer manager cannot 
read %1!d! bytes from file 
"%2". The file is damaged. 


Buffer ID %1!d! supports 
other virtual buffers and 
cannot be placed into 
sequential mode. 
IDTSBuffer100.SetSequential 
Mode was called on a buffer 
that supports > virtual 
buffers. 


This operation could not be 
performed because buffer is 
in read-only mode. A read- 
only buffer cannot be 
modified. 


ID %1 cannot be set to 
%2'd! because a cycle 
would be created. 


The buffer manager ran out 
of memory while trying to 
extend the table of buffer 
types. This is caused by an 
out-of-memory condition. 


The buffer manager failed 
to create a new buffer type. 


The Data Flow engine 
scheduler failed to retrieve 
the execution tree with 
index %1!d! from the 
layout. The scheduler 
received a count containing 
more execution trees >than 
actually exist. 


HEXADECIMAL CODE 


0xC0047056 


0xC0047057 


0xC004705A 


0xC004705B 


0xC004705C 


0xC004705E 


0xC004705F 


0xC0047060 


0xC0047061 


DECIMAL CODE 


-1073450922 


-1073450921 


-1073450918 


-1073450917 


-1073450916 


-1073450914 


-1073450913 


-1073450912 


-1073450911 


SYMBOLIC NAME 


DTS_E_CANTCREATEPRIME 
OUTPUTBUFFER 


DTS_E_SCHEDULERTHREAD 
MEMORY 


DTS_E_SCHEDULEROBJECT 


DTS_E_PREPARETREENODEF 
AILED 


DTS_E_CANTCREATEVIRTUA 
LBUFFER 


DTS_E_NOMOREIDS 


DTS_E_ALREADYATTACHED 


DTS_E_OUTPUTCOLUMNN 
AMECONFLICT 


DTS_E_EOQFANNOUNCEMEN 
TFAILED 


DESCRIPTION 


The Data Flow task failed to 
create a buffer to call 
PrimeOutput for output 
"%3" (%A!d!) on component 
"%1" (%2!d!). This error 
usually occurs due to an 
>out-of-memory condition. 


The Data Flow engine 
scheduler failed to create a 
thread object because not 
enough memory is 
available. This is caused by 
an out-of-memory 
condition. 


The Data Flow engine 
scheduler cannot retrieve 
object with ID %1!d! from 
the layout. The Data Flow 
engine scheduler previously 
located an object that is 
now no longer > available. 


The Data Flow task failed to 
prepare buffers for the 
execution tree node 
beginning at output "%1" 
(%2!d1). 


The Data Flow task cannot 
create a virtual buffer to 
prepare for execution. 


The maximum ID has been 
reached. There are no more 
IDs available to assign to 
objects. 


The %1 is already attached 
and cannot be attached 
again. Detach it and try 
again. 


Column name "%1" on 
output "%2" cannot be 
used because it conflicts 
with a column of the same 
name on synchronous input 
"%3". 


The Data Flow task cannot 
to create a buffer to mark 
the end of the rowset. 


HEXADECIMAL CODE 


0xC0047062 


0xC0047063 


0xC0047064 


0xC0047065 


0xC0047066 


0xC0047067 


0xC0047068 


0xC004706A 


0xC004706B 


0xC004706C 


DECIMAL CODE 


-1073450910 


-1073450909 


-1073450908 


-1073450907 


-1073450906 


-1073450905 


-1073450904 


-1073450902 


-1073450901 


-1073450900 


SYMBOLIC NAME 


DTS_E_USERCOMPONENTE 
XCEPTION 


DTS_E_SCHEDULERMEMOR 
Y 


DTS_E_BUFFERNOOBJECTM 
EMORY 


DTS_E_BUFFERNOMAPME 
MORY 


DTS_E_INDIVIDUALPUTVAR 
IABLESFAILED 


DTS_E_INDIVIDUALPUTCO 
MPONENTMETADATAFAILE 
D 


DTS_E_SORTEDOUTPUTHAS 
INVALIDSORTKEY POSITION 


DTS_E_SORTEDOUTPUTHAS 
INVALIDSORTKEY POSITION 
S 


DTS_E_INDIVIDUALVALIDAT 
IONSTATUSFAILED 


DTS_E_CANTCREATECOMP 
ONENT 


DESCRIPTION 


A managed user 
component has thrown 
exception "%1". 


The Data Flow engine 
scheduler cannot allocate 
enough memory for the 
execution structures. The 
system was low on memory 
before execution started. 


An out-of-memory 
condition prevented the 
creation of the buffer 
object. 


An out-of-memory 
condition prevents the 
mapping of a buffer's 
lineage IDs to DTPLHCOL 
indexes. 


The "%1!s!" cannot cache 
the Variables collection and 
returned error code 
0x%2!8.8X. 


The "%1" failed to cache the 
component metadata 
object and returned error 
code 0x%2!8.8X!. 


"%1" has a non-zero 
SortKeyPosition, but its 
value (%2!Id!) is too large. It 
must be less than or equal 
to the number of columns. 


The IsSorted property of 
%1 is set to TRUE, but the 
absolute values of the non- 
zero output column 
SortKeyPositions do not 
form a monotonically 
>increasing sequence, 
starting at one. 


"%1" failed validation and 
returned validation status 
Noga" 


Component "%1!s!" could 
not be created and 
returned error code 
0x%2!8.8X! "%3!s!". Make 
sure that the component is 
registered correctly. 


HEXADECIMAL CODE 


0xC004706D 


0xC004706E 


0xC004706F 


0xC0047070 


0xC0047071 


0xC0047072 


0xC0047073 


0xC0047074 


0xC0047075 


0xC0047077 


DECIMAL CODE 


-1073450899 


-1073450898 


-1073450897 


-1073450896 


-1073450895 


-1073450894 


-1073450893 


-1073450892 


-1073450891 


-1073450889 


SYMBOLIC NAME 


DTS_E_COMPONENTNOTRE 
GISTERED 


DTS_E_COMPONENTNOTF 
OUND 


DTS_E_BINARYCODENOTFO 
UND 


DTS_E_CANTCREATEBLOBFI 
LE 


DTS_E_SYNCHRONOUSIDM 
ISMATCH 


DTS_E_OBJECTIDNOTFOUN 
D 


DTS_E_OBJECTIDLOOKUPFA 
ILED 


DTS_E_INVALIDCODEPAGE 


DTS_E_INDIVIDUALPUTEVE 
NTINFOSFAILED 


DTS_E_DUPLICATEOUTPUT 
COLUMNNAMES 


DESCRIPTION 


The module containing 
"%1" is not registered or 
installed correctly. 


The module containing 
"%1" cannot be located, 
even though it is registered. 


The script component is 
configured to pre-compile 
the script, but binary code 
is not found. Please visit the 
IDE in Script Component 
Editor by clicking Design 
Script >button to cause 
binary code to be 
generated. 


The buffer manager cannot 
create a file to spool a long 
object on the directories 
named in the 
BLOBTempStoragePath 
property. Either an incorrect 
file name was > provided, or 
there are no permissions, or 
the paths have been full. 


The SynchronousInputID 
property on "%1" was 
%2!d!, and %3!d! was 
expected. 


No object exists with the ID 
%1'd!. 


Unable to locate an object 
with ID %1!d! because of 
the error code 0x%2!8.8X!. 


The code page %1!d! 
specified on output column 
"%2" (%3!d!) is not valid. 
Select a different code page 
for output column "%2". 


The Eventinfos collection 
could not be cached by 
"%1" and returned error 
code 0x%2!8.8X!. 


The name for "%1" is a 
duplicate. All names must 
be unique. 


HEXADECIMAL CODE 


0xC0047078 


0xC0047079 


0xC004707A 


0xC004707B 


0xC004707C 


0xC004707D 


0xC004707E 


0xC004707F 


DECIMAL CODE 


-1073450888 


-1073450887 


-1073450886 


-1073450885 


-1073450884 


-1073450883 


-1073450882 


-1073450881 


SYMBOLIC NAME 


DTS_E_NOOUTPUTCOLUM 
NFORINPUTCOLUMN 


DTS_E_EXCLGRPNOSYNCIN 
Pp 


DTS_E_ERROROUTCANTBEO 
NSYNCNONEXCLUSIVEOUT 
PUT 


DTS_E_EXPREVALDIVBYZER 
O 


DTS_E_EXPREVALLITERALOV 
ERFLOW 


DTS_E_EXPREVALBINARYOP 
NUMERICOVERFLOW 


DTS_E_EXPREVALBINARYOP 
OVERFLOW 


DTS_E_EXPREVALFUNCTION 
OVERFLOW 


DESCRIPTION 


There is no output column 
associated with input 
column "%1" (%2!d!). 


"%1" has a virtual buffer 
extending from a root 
source. There is an exclusion 
group that is not zero with 
a synchronous input that is 
zero. 


"%1" cannot be an error 
output because error 
outputs cannot be placed 
on synchronous, non- 
exclusive outputs. 


A divide-by-zero error 
occurred. The right side 
operand evaluates to zero 
in the expression "%1". 


The literal "%1" is too large 
to fit into type %2. The 
magnitude of the literal 
overflows the type. 


The result of the binary 
operation "%1" on data 
types %2 and %3 exceeds 
the maximum size for 
numeric types. The operand 
types could not be implicitly 
cast >into a numeric 
(DT_NUMERIC) result 
without loss of precision or 
scale. To perform this 
operation, one or both 
operands need to be 
explicitly cast with a cast 
operator. 


The result of the binary 
operation "%1" exceeds the 
maximum size for result 
data type "%2". The 
magnitude of the result of 
the operation overflows the 
type of >the result. 


The result of the function 
call "%1" is too large to fit in 
type "%2". The magnitude 
of the result of the function 
call overflows the type of 
the operand. An > explicit 
cast to a larger type may be 
required. 


HEXADECIMAL CODE 


0xC0047080 


0xC0047081 


0xC0047082 


0xC0047083 


0xC0047084 


0xC0047085 


0xC0047086 


DECIMAL CODE 


-1073450880 


-1073450879 


-1073450878 


-1073450877 


-1073450876 


-1073450875 


-1073450874 


SYMBOLIC NAME 


DTS_E_EXPREVALBINARYTY 
PEMISMATCH 


DTS_E_EXPREVALUNSUPPO 
RTEDBINARYTY PE 


DTS_E_EXPREVALBINARYSIG 
NMISMATCH 


DTS_E_EXPREVALBINARYOP 
ERATIONFAILED 


DTS_E_EXPREVALBINARYOP 
ERATIONSETTYPEFAILED 


DTS_E_EXPREVALSTRINGCO 
MPARISONFAILED 


DTS_E_EXPREVALUNSUPPO 
RTEDUNNARYTY PE 


DESCRIPTION 


The data types "%1" and 
"%2" are incompatible for 
binary operator "%3". The 
operand types could not be 
implicitly cast into 
compatible types for the 
operation. >To perform this 
operation, one or both 
operands need to be 
explicitly cast with a cast 
operator. 


The data type "%1" cannot 
be used with binary 
operator "%2". The type of 
one or both of the 
operands is not supported 
for the operation. To 
perform this >operation, 
one or both operands need 
to be explicitly cast with a 
cast operator. 


There is a sign mismatch for 
the bitwise binary operator 
"%1" in operation "%2". 
Both operands for this 
operator must be positive 
or negative. 


The binary operation "%1" 
failed with error code 
0x%2!8.8X!. An internal 
error occurred, or an out- 
of-memory condition exists. 


Attempt to set the result 
type of binary operation 
"%1" failed with error code 
0x%2!8.8X!. 


Comparing "%1" to string 
"%2" failed. 


The data type "%1" cannot 
be used with unary 
operator "%2". This operand 
type is not supported for 
the operation. To perform 
this operation, the operand 
>needs to be explicitly cast 
with a cast operator. 


HEXADECIMAL CODE 


0xC0047087 


0xC0047088 


0xC0047089 


0xC004708A 


0xC004708B 


0xC004708C 


0xC004708E 


0xC004708F 


0xC0047090 


DECIMAL CODE 


-1073450873 


-1073450872 


-1073450871 


-1073450870 


-1073450869 


-1073450868 


-1073450866 


-1073450865 


-1073450864 


SYMBOLIC NAME 


DTS_E_EXPREVALUNARYOP 
ERATIONFAILED 


DTS_E_EXPREVALUNARYOP 
ERATIONSETTYPEFAILED 


DTS_E_EXPREVALPARAMTY 
PEMISMATCH 


DTS_E_EXPREVALINVALIDF 
UNCTION 


DTS_E_EXPREVALFNSUBSTRI 
NGINVALIDLENGTH 


DTS_E_EXPREVALFNSUBSTRI 
NGINVALIDSTARTINDEX 


DTS_E_EXPREVALCHARMAP 
PINGFAILED 


DTS_E_EXPREVALINVALIDD 
ATEPART 


DTS_E_EXPREVALINVALIDN 
ULLPARAM 


DESCRIPTION 


The unary operation "%1" 
failed with error code 
0x%2!8.8X!. An internal 
error occurred, or there is 
an out-of- memory 
condition. 


Attempt to set the result 
type of unary operation 
"%1" failed with error code 
0x%2!8.8X!. 


The function "%1" does not 
support the data type "%2" 
for parameter number 
%3!d!. The type of the 
parameter could not be 
implicitly cast into a 
compatible type >for the 
function. To perform this 
operation, the operand 
needs to be explicitly cast 
with a cast operator. 


The function "%1" was not 
recognized. Either the 
function name is incorrect 
or does not exist. 


The length %1!d! is not 
valid for function "%2". The 
length parameter cannot be 
negative. Change the 
length parameter to zero or 
a positive value. 


The start index %1!d! is not 
valid for function "%2". The 
start index value must be 
an integer greater than 0. 
Start index is one-based, 
not >zero-based. 


The function "%1" cannot 
perform the character 
mapping on string "%2". 


"%1" is not a valid date part 
for function "%2". 


Parameter number %1!d! of 
the function NULL with 
data type "%2" is not valid. 
The parameters of NULL() 
must be static, and cannot 
contain dynamic elements 
such >as input columns. 


HEXADECIMAL CODE 


0xC0047091 


0xC0047092 


0xC0047093 


0xC0047094 


0xC0047095 


0xC0047096 


0xC0047097 


DECIMAL CODE 


-1073450863 


-1073450862 


-1073450861 


-1073450860 


-1073450859 


-1073450858 


-1073450857 


SYMBOLIC NAME 


DTS_E_EXPREVALINVALIDN 
ULLPARAMTYPE 


DTS_E_EXPREVALFUNCTION 
PARAMNOTSTATIC 


DTS_E_EXPREVALINVALIDC 
ASTPARAM 


DTS_E_EXPREVALINVALIDC 
ASTPARAMTYPE 


DTS_E_EXPREVALINVALIDC 
AST 


DTS_E_EXPREVALINVALIDTO 
KEN 


DTS_E_EXPREVALUNEXPECT 
EDPARSEERROR 


DESCRIPTION 


Parameter number %1!d! of 
the function NULL with 
data type "%2" is not an 
integer. A parameter of 
NULLQ must be an integer 
or a type that can be 
converted >to an integer. 


Parameter number %1!d! of 
the function "%2" is not 
static. This parameter must 
be static, and cannot 
contain dynamic elements 
such as input columns. 


Parameter number %1!d! of 
the cast to data type "%2" 
is not valid. The parameters 
of cast operators must be 
static, and cannot contain 
dynamic elements such as 
>input columns. 


Parameter number %1!d! of 
the cast to data type "%2" 
is not an integer A 
parameter of a cast 
operator must be an 
integer or a type that can 
be converted to >an 
integer. 


Cannot cast expression 
"%1" from data type "%2" 
to data type "%3". The 
requested cast is not 
supported. 


Attempt to parse the 
expression "%1" failed. The 
token "%2" at line number 
"%3", character number 
"%4" was not recognized. 
The expression cannot be 
parsed because >it contains 
invalid elements at the 
location specified. 


An error occurred when 
parsing the expression 
"%1". The expression failed 
to parse for an unknown 
reason. 


HEXADECIMAL CODE 


0xC0047098 


0xC0047099 


0xC004709A 


0xC004709B 


0xC004709C 


0xC004709D 


0xC004709E 


DECIMAL CODE 


-1073450856 


-1073450855 


-1073450854 


-1073450853 


-1073450852 


-1073450851 


-1073450850 


SYMBOLIC NAME 


DTS_E_EXPREVALFAILEDTOP 
ARSEEXPRESSIONWITHHR 


DTS_E_EXPREVALFAILEDTOP 
ARSEEXPRESSION 


DTS_E_EXPREVALEXPRESSIO 
NEMPTY 


DTS_E_EXPREVALCOMPUTE 
FAILED 


DTS_E_EXPREVALBUILDSTRI 
NGFAILED 


DTS_E_EXPREVALCANNOTC 
ONVERTRESULT 


DTS_E_EXPREVALCONDITIO 
NALOPINVALIDCONDITION 
TYPE 


DESCRIPTION 


Attempt to parse the 
expression "%1" failed and 
returned error code 
0x%2!8.8X!. The expression 
cannot be parsed. It might 
contain invalid elements 
>or it might not be well- 
formed. There may also be 
an out-of-memory error. 


The expression "%1" is not 
valid and cannot be parsed. 
The expression may contain 
invalid elements or it may 
not be well-formed. 


There was no expression to 
compute. An attempt was 
made to compute or get 
the string of an empty 
expression. 


Attempt to compute the 
expression "%1" failed with 
error code 0x%2!8.8X!. 


Attempt to generate a 
string representation of the 
expression failed with error 
code 0x%1!8.8X!. Failed 
when attempting to 
generate a displayable 
string that >represents the 
expression. 


Cannot convert the 
expression result data type 
"%1" to the column data 
type "%2". The result of the 
expression should be 
written to an input/output 
column, >but the data type 
of the expression cannot be 
converted to the data type 
of the column. 


The conditional expression 
"%1" of the conditional 
operator has an invalid data 
type of "%2". The 
conditional expression of 
the conditional > operator 
must return a Boolean, 
which is type DT_BOOL. 


HEXADECIMAL CODE 


0xC004709F 


0xC00470A0 


0xC00470A1 


0xC00470A2 


0xC00470A3 


0xC00470A4 


0xC00470A5 


DECIMAL CODE 


-1073450849 


-1073450848 


-1073450847 


-1073450846 


-1073450845 


-1073450844 


-1073450843 


SYMBOLIC NAME 


DTS_E_EXPREVALCONDITIO 
NALOPTYPEMISMATCH 


DTS_E_EXPREVALCONDITIO 
NALOPSETTYPEFAILED 


DTS_E_BUFFERORPHANED 


DTS_E_EXPREVALINPUTCOL 
UMNNAMENOTFOUND 


DTS_E_EXPREVALINPUTCOL 
UMNIDNOTFOUND 


DTS_E_EXPREVALNOINPUTC 
OLUMNCOLLECTIONFORC 
OLUMNNAME 


DTS_E_EXPREVALNOINPUTC 
OLUMNCOLLECTIONFORC 
OLUMNID 


DESCRIPTION 


The data types "%1" and 
"%2" are incompatible for 
the conditional operator. 
The operand types cannot 
be implicitly cast into 
compatible types for the 
>conditional operation. To 
perform this operation, one 
or both operands need to 
be explicitly cast with a cast 
operator. 


Attempt to set the result 
type of conditional 
operation "%1" failed with 
error code 0x%2!8.8X!. 


This buffer has been 
orphaned. The buffer 
manager has shut down, 
leaving an outstanding 
buffer and no cleanup will 
occur for the buffer. There is 
a potential for memory 
>leaks and other problems. 


Attempt to find the input 
column named "%1" failed 
with error code 0x%2!8.8X!. 
The input column specified 
was not found in the input 
column collection. 


Attempt to find the input 
column with lineage ID 
%1!d! failed with error code 
0x%2!8.8X!. The input 
column was not found in 
the input column collection. 


The expression contains 
unrecognized token "%1". If 
"%1" is a variable, it should 
be expressed as "@%1". The 
specified token is not valid. 
>If the token is intended to 
be a variable name, it 
should be prefixed with the 
@ symbol. 


The expression contains 
unrecognized token 
"#%1Id!", 


HEXADECIMAL CODE 


0xC00470A6 


0xC00470A7 


0xC00470A8 


0xC00470A9 


0xC00470AA 


0xC00470AB 


0xC00470AC 


DECIMAL CODE 


-1073450842 


-1073450841 


-1073450840 


-1073450839 


-1073450838 


-1073450837 


-1073450836 


SYMBOLIC NAME 


DTS_E_EXPREVALVARIABLE 
NOTFOUND 


DTS_E_EXPREVALINVALIDTO 
KENSTATE 


DTS_E_BLANKOUTPUTCOL 
UMNNAME 


DTS_E_HASSIDEEFFECTSWIT 
HSYNCINP 


DTS_E_EXPREVALINVALIDC 
ASTCODEPAGE 


DTS_E_EXPREVALINVALIDC 
ASTPRECISION 


DTS_E_EXPREVALINVALIDC 
ASTSCALE 


DESCRIPTION 


The variable "%1" was not 
found in the Variables 
collection. The variable 
might not exist in the 
correct scope. 


Attempt to parse the 
expression "%1" failed. The 
expression might contain an 
invalid token, an incomplete 
token, or an invalid 
element. It might not be 
>well-formed, or might be 
missing part of a required 
element such as a 
parenthesis. 


The name for "%1" is blank, 
and names cannot be 
blank. 


The "%1" has the 
HasSideEffects property set 
to TRUE, but "%1" is 
synchronous and cannot 
have side effects. Set the 
HasSideEffects property to 
FALSE. 


The value, %1!d!, specified 
for the code page 
parameter of the cast to 
data type "%2", is not valid. 
The code page is not 
installed on the machine. 


The value %1!d! specified 
for the precision parameter 
of the cast to data type 
"%2" is not valid. Precision 
must be in the range %3!d! 
to %4!d! and the > precision 
value is out of range for the 
type cast. 


The value %1!d! specified 
for the scale parameter of 
the cast to data type "%2" 
is not valid. The scale must 
be in the range %3!d! to 
%A!d! and the scale value 
>is out of range for the 
type cast. Scale must not 
exceed precision and must 
be positive. 


HEXADECIMAL CODE 


0xC00470AD 


0xC00470AF 


0xC00470B1 


0xC00470B2 


0xC00470B3 


0xC00470B4 


0xC00470B5 


0xC00470B6 


0xC00470B7 


DECIMAL CODE 


-1073450835 


-1073450833 


-1073450831 


-1073450830 


-1073450829 


-1073450828 


-1073450827 


-1073450826 


-1073450825 


SYMBOLIC NAME 


DTS_E_NONSORTEDOUTPU 
THASSORTKEY POSITIONS 


DTS_E_EXPREVALCONDITIO 
NALOPCODEPAGEMISMAT 
CH 


DTS_E_REFERENCEDMETAD 
ATABADCOUNT 


DTS_E_OBJECTLINEAGEIDN 
OTFOUND 


DTS_E_FILENAMEOUTPUTC 
OLUMNOTFOUND 


DTS_E_FILENAMEOUTPUTC 
OLUMNINVALIDDATATYPE 


DTS_E_DISTRIBUTORADDFA 
ILED 


DTS_E_LOCALENOTINSTALL 
ED 


DTS_E_EXPREVALILLEGALHE 
XESCAPEINSTRINGLITERAL 


DESCRIPTION 


The IsSorted property for 
"%1" is false, but %2!lu! of 
its output columns’ 
SortKeyPositions are non- 
zero. 


The code pages must match 
for operands of conditional 
operation "%1" for type %2. 
The code page of the left 
operand does not match 
the code page of >the right 
operand. For the 
conditional operator on the 
specified type, the code 
pages must be the same. 


Input "%1" (%2!d!) 
references input "%3" 
(%A!d!), but they do not 
have the same number of 
columns. Input %5!d! has 
%6!d! columns, while input 
%7'd! has %8!d! >columns. 


No object exists with a 
lineage ID of %1!d!. 


The output column for the 
file name cannot be found. 


The output column for the 
file name is not a null- 
terminated Unicode 
character string, which is 
data type DT_WSTR. 


A distributor failed to give a 
buffer to thread "%1" 
because of error 
0x%2!8.8xX!. The target 
thread is probably shutting 
down. 


The LocalelD %1!Id! is not 
installed on this system. 


The string literal "%1" 
contains an illegal 
hexadecimal escape 
sequence of "\x%2". The 
escape sequence is not 
supported in string literals 
in the >expression 
evaluator. The hexadecimal 
escape sequences must be 
of the form \xhhhh where h 
is a valid hexadecimal digit. 


HEXADECIMAL CODE 


0xC00470B8 


0xC00470B9 


0xC00470BA 


0xC00470BB 


0xC00470BC 


0xC00470BD 


0OxC00470BE 


0xC00470BF 


DECIMAL CODE 


-1073450824 


-1073450823 


-1073450822 


-1073450821 


-1073450820 


-1073450819 


-1073450818 


-1073450817 


SYMBOLIC NAME 


DTS_E_EXPREVALILLEGALES 
CAPEINSTRINGLITERAL 


DTS_E_NOOUTPUTCOLUM 
NS 


DTS_E_LOBDATATYPENOTS 
UPPORTED 


DTS_E_OUTPUTWITHMULTI 
PLEERRORS 


DTS_E_FAILEDDURINGOLED 
BDATATYPECONVERSIONC 
HECK 


DTS_E_BUFFERISEOR 


DTS_E_EXPREVALUNSUPPO 
RTEDTYPE 


DTS_E_PRIMEOUTPUTNOE 
OR 


DESCRIPTION 


The string literal "%1" 
contains an illegal escape 
sequence of "\%2!c!". The 
escape sequence is not 
supported in string literals 
in the expression 

> evaluator. If a backslash is 
needed in the string, use a 
double backslash, "\\". 


"%1" contains no output 
columns. An asynchronous 
output must contain output 
columns. 


The "%1" has a long object 
data type of DT_TEXT, 
DT_NTEXT, or DT_IMAGE, 
which is not supported. 


Output ID %1!d! was given 
multiple error output 
configurations. First %2!d! 
and %3!d!, then %4!d! and 
%S5!d!. 


The OLE DB provider failed 
during the data type 
conversion verification for 
"%1". 


This buffer represents the 
end of the rowset and its 
row count cannot be 
altered. An attempt was 
made to call AddRow or 
RemoveRow on a buffer 
that has the end of rowset 
flag.> 


The data type "%1" is not 
supported in an expression. 
The specified type is not 
supported or is not valid. 


The PrimeOutput method 
on "%1" returned success, 
but did not report an end 
of the rowset. There is an 
error in the component. It 
should have reported an 
end-of-row. The > pipeline 
will shut down execution to 
avoid unpredictable results. 


HEXADECIMAL CODE 


0xC00470C0 


0xC00470C1 


0xC00470C2 


0xC00470C3 


0xC00470C4 


0xC00470C5 


0xC00470C6 


0xC00470C7 


0xC00470CE 


DECIMAL CODE 


-1073450816 


-1073450815 


-1073450814 


-1073450813 


-1073450812 


-1073450811 


-1073450810 


-1073450809 


-1073450802 


SYMBOLIC NAME 


DTS_E_EXPREVALDATACON 
VERSIONOVERFLOW 


DTS_E_EXPREVALDATACON 
VERSIONNOTSUPPORTED 


DTS_E_EXPREVALDATACON 
VERSIONFAILED 


DTS_E_EXPREVALCONDITIO 
NALOPERATIONFAILED 


DTS_E_EXPREVALCASTFAILE 
D 


DTS_E_EXPREVALFUNCTION 
COMPUTEFAILED 


DTS_E_EXPREVALFUNCTION 
CONVERTPARAMTOMEMBE 
RFAILED 


DTS_E_REDIRECTROWUNAV 
AILABLEWITHFASTLOADAN 
DZEROMAXINSERTCOMMI 
TSIZE 


DTS_E_EXPREVALBINARYOP 
ERATORCODEPAGEMISMAT 
CH 


DESCRIPTION 


An overflow occurred while 
converting from data type 
"%1" to data type "%2". The 
source type is too large for 
the destination type. 


Conversion from data type 
"%1" to data type "%2" is 
unsupported. The source 
type cannot be converted 
to the destination type. 


Error code 0x%1!8.8X! 
occurred attempting to 
convert from data type %2 
to data type %3. 


The conditional operation 
"%1" failed with error code 
0x%2!8.8X!. There was an 
internal error or an out-of- 
memory error. 


Casting expression "%1" 
from data type "%2" to data 
type "%3" failed with error 
code 0x%4!8.8X!. 


Evaluating function "%1" 
failed with error code 
0x%2!8.8X!. 


Parameter number %1!d! of 
the function "%2" cannot be 
converted to a static value. 


The error row disposition 
on "%1" cannot be set to 
redirect the row when the 
fast load option is turned 
on, and the maximum 
>insert commit size is set 
to zero. 


The code pages for 
operands of binary 
operator "%1" for type "%2" 
must match. Currently, the 
code page of the left 
operand does not match 
the code > page of the right 
operand. For the specified 
binary operator on the 
specified type, the code 
pages must be the same. 


HEXADECIMAL CODE 


0xC00470CF 


0xC00470D0 


0xC00470D1 


0xC00470D2 


0xC00470D3 


0xC00470D4 


0xC00470D5 


0xC00470D6 


DECIMAL CODE 


-1073450801 


-1073450800 


-1073450799 


-1073450798 


-1073450797 


-1073450796 


-1073450795 


-1073450794 


SYMBOLIC NAME 


DTS_E_EXPREVALVARIABLEC 
OMPUTEFAILED 


DTS_E_EXPREVALVARIABLET 
YPENOTSUPPORTED 


DTS_E_EXPREVALCASTCODE 
PAGEMISMATCH 


DTS_E_BUFFERSIZEOUTOFR 
ANGE 


DTS_E_BUFFERMAXROWSIZ 
EOQUTOFRANGE 


DTS_E_EXTERNALCOLUMN 
METADATACODEPAGEMIS 
MATCH 


DTS_E_THREADCOUNTOUT 
OFRANGE 


DTS_E_EXPREVALINVALIDTO 
KENSINGLEQUOTE 


DESCRIPTION 


Retrieving the value of 
Variable "%1" failed with 
error code 0x%2!8.8X!. 


The data type of variable 
"%1" is not supported in an 
expression. 


Unable to cast expression 
"%1" from data type "%2" 
to data type "%3" because 
the code page of the value 
being cast (%4!d!) does not 
match the requested 
>result code page (%5!d)!). 
The code page of the 
source must match the 
code page requested for 
the destination. 


The default buffer size must 
be between %1!d! and 
%2!'d! bytes. An attempt 
was made to set the 
DefaultBufferSize property 
to a value that is too small 
or too large. 


The default buffer maximum 
rows must be larger than 
%1!d! rows. An attempt was 
made to set the 
DefaultBufferMaxRows 
property to a value that is 
too small. 


The code page on %1 is 
%2'd! and is required to be 
%3!d!. 


Failed to assign %3!d! to 
the EngineThreads property 
of the Data Flow task. The 
value must be between 
%1'd! and %2!d!. 


Parsing the expression "%1" 
failed. The single quotation 
mark at line number "%2", 
character number "%3", was 
not expected. 


HEXADECIMAL CODE 


0xC00470D7 


0xC00470DA 


0xC00470DB 


0xC00470DC 


0xC00470DD 


0xC00470DE 


0xC00470DF 


0xC00470E0 


DECIMAL CODE 


-1073450793 


-1073450790 


-1073450789 


-1073450788 


-1073450787 


-1073450786 


-1073450785 


-1073450784 


SYMBOLIC NAME 


DTS_E_EXPREVALINVALIDTO 
KENSINGLEEQUAL 


DTS_E_INDIVIDUALPUTREF 
TRACKERFAILED 


DTS_E_EXPREVALAMBIGUO 
USINPUTCOLUMNNAME 


DTS_E_EXPREVALDOTTEDIN 
PUTCOLUMNNAMENOTFO 
UND 


DTS_E_EXPREVALAMBIGUO 
USVARIABLENNAME 


DTS_E_REDUCTIONFAILED 


DTS_E_EXPREVALSQRTINVA 
LIDPARAM 


DTS_E_EXPREVALLNINVALI 
DPARAM 


DESCRIPTION 


Parsing the expression "%1" 
failed. The equal sign (=) at 
line number "%2", character 
number "%3", was not 
expected. A double equals 
sign (==) may be >required 
at the location specified. 


Component "%1" failed to 
cache the runtime object 
reference tracker collection 
and returned error code 
0x%2!8.8X!. 


There are multiple input 
columns with the name 
"%1". The desired input 
column must be specified 
uniquely as [Component 
Name].[%2] or referenced 
by >lineage ID. Currently, 
the input column specified 
exists on more than one 
component. 


Locating the input column 
named "[%1].[%2]" failed 
with error code 0x%3!8.8X!. 
The input column was not 
found in the input column 
collection. 


There are multiple variables 
with the name "%1". The 
desired variable must be 
specified uniquely as 
@[Namespace::%2]. The 
variable exists in more than 
one >namespace. 


The Data Flow engine 
scheduler failed to reduce 
the execution plan for the 
pipeline. Set the 
OptimizedMode property 
to false. 


The function SQRT cannot 
operate on negative values, 
and a negative value was 
passed to the SQRT 
function. 


The function LN cannot 
operate on zero or negative 
values, and a zero or 
negative value was passed 
to the LN function. 


HEXADECIMAL CODE 


0xC00470E1 


0xC00470E2 


0xC00470E3 


0xC00470E4 


0xC00470E5 


0xC00470E6 


0xC00470E7 


0xC00470E8 


0xC00470EA 


DECIMAL CODE 


-1073450783 


-1073450782 


-1073450781 


-1073450780 


-1073450779 


-1073450778 


-1073450777 


-1073450776 


-1073450774 


SYMBOLIC NAME 


DTS_E_EXPREVALLOGINVAL 
IDPARAM 


DTS_E_EXPREVALPOWERIN 
VALIDPARAM 


DTS_E_NOCANCELEVENT 


DTS_E_CANCELRECEIVED 


DTS_E_EXPREVALUNARYOP 
OVERFLOW 


DTS_E_EXPREVALPLACEHO 
LDERINEXPRESSION 


DTS_E_EXPREVALFNRIGHTI 
NVALIDLENGTH 


DTS_E_EXPREVALFNREPLIC 
ATEINVALIDREPEATCOUNT 


DTS_E_EXPREVALVARIABLEC 
OULDNOTBEREAD 


DESCRIPTION 


The function LOG cannot 
operate on zero or negative 
values, and a zero or 
negative value was passed 
to the LOG function. 


The parameters passed to 
the function POWER cannot 
be evaluated and yield an 
indeterminate result. 


The runtime cannot provide 
a cancel event because of 
error 0x%1!8.8X!. 


The pipeline received a 
request to cancel and is 
shutting down. 


The result of the unary 
minus (negation) operation 
"%1" exceeds the maximum 
size for result data type 
"%2". The magnitude of the 
result of the operation 
overflows >the type of the 
result. 


The placeholder "%1" was 
found in an expression. This 
must be replaced with an 
actual parameter or 
operand. 


The length %1!d! specified 
for function "%2" is 
negative, and is not valid. 
The length parameter must 
be positive. 


The repeat count %1!d! is 
negative and is not valid for 
function "%2". The repeat 
count parameter cannot be 
negative. 


Reading the variable "%1" 
failed with error code 
0x%2!8.8X!. 


HEXADECIMAL CODE 


0xC00470EC 


0xC00470ED 


OxC00470EE 


0xC00470EF 


0xC00470F0 


0xC00470F1 


DECIMAL CODE SYMBOLIC NAME 


-1073450772 DTS_E_EXPREVALBINARYOP 
DTSTRNOTSUPPORTED 

-1073450771 DTS_E_EXPREVALCONDITIO 
NALOPDTSTRNOTSUPPORT 
ED 

-1073450770 DTS_E_EXPREVALFNFINDST 
RINGINVALIDOCCURRENCE 
COUNT 

-1073450769 DTS_E_INDIVIDUALPUTLOG 
ENTRYINFOS 

-1073450768 DTS_E_EXPREVALINVALIDD 
ATEPARTNODE 

-1073450767 DTS_E_EXPREVALINVALIDC 


ASTLENGTH 


DESCRIPTION 


For operands of a binary 
operation, the data type 
DT_STR is supported only 
for input columns and cast 
operations. The expression 
"%1" has a DT_STR 

> operand that is not an 
input column or the result 
of a cast, and cannot be 
used in a binary operation. 
To perform this operation, 
the operand needs to be 
explicitly cast with a cast 
operator. 


For operands of the 
conditional operator, the 
data type DT_STR is 
supported only for input 
columns and cast 
operations. The expression 
"%1" has a >DT_STR 
operand that is not an 
input column or the result 
of a cast, and cannot be 
used with the conditional 
operation. To perform this 
operation, the operand 
needs to be explicitly cast 
with a cast operator. 


The occurrence count %1!d! 
is not valid for function 
"%2". This parameter must 
be greater than zero. 


"%1" failed to cache the 
LogEntryInfos collection 
and returned error code 
0x%2!8.8X!. 


The date part parameter 
specified for function "%1" 
is not valid. It must be a 
static string. The date part 
parameter cannot contain 
dynamic elements, such >as 
input columns, and must be 
of type DT_WSTR. 


The value %1!d! specified 
for the length parameter of 
the cast to data type %2 is 
negative and not valid. The 
length must be positive. 


HEXADECIMAL CODE 


0xC00470F2 


0xC00470F3 


0xC00470F4 


0xC00470F5 


0xC00470F6 


0xC00470F7 


0xC00470F8 


DECIMAL CODE 


-1073450766 


-1073450765 


-1073450764 


-1073450763 


-1073450762 


-1073450761 


-1073450760 


SYMBOLIC NAME 


DTS_E_EXPREVALINVALIDN 
ULLCODEPAGE 


DTS_E_EXPREVALINVALIDN 
ULLPRECISION 


DTS_E_EXPREVALINVALIDN 
ULLSCALE 


DTS_E_EXPREVALINVALIDN 
ULLLENGTH 


DTS_E_NEGATIVESNOTALLO 
WED 


DTS_E_FASTPARSENOTALLO 
WED 


DTS_E_CANNOTREATTACHP 
ATH 


DESCRIPTION 


The value %1!d! specified 
for the code page 
parameter of the NULL 
function with data type 
"%2" is not valid. The code 
page is not installed on the 
computer. 


The value %1!d! specified 
for the precision parameter 
of the NULL function with 
data type "%2" is out of 
range. Precision must be in 
the range %3!d! to %4!d!.> 


The value %1!d! specified 
for the scale parameter of 
the NULL function with 
data type %2 is out of 
range. Scale must be in the 
range %3!d! to %4!d!. Scale 
must >not exceed precision 
and must not be negative. 


The value %1!d! specified 
for the length parameter of 
the "NULL" function with 
data type %2 is negative 
and not valid. The length 
must be positive. 


The %1 can't be assigned a 
negative value. 


The "%1" custom property 
for "%2" cannot be set to 
true. The column data type 
must be one of the 
following: DT_I1, DT_I2, 
DT_l4, DT_I8, DT_UI1, 
DT_Ul2, DT_UI4, >DT_UI8, 
DT_DBTIMESTAMP 
DT_DBTIMESTAMP2, 
DT_DBTIMESTAMPOFFSET, 
DT_DATE, DT_DBDATE, 
DT_DBTIME, DT_DBTIME2, 
or DT_FILETIME. 


The "%1" cannot be 
reattached. Delete the path, 
add a new one, and attach 
it. 


HEXADECIMAL CODE 


0xC00470F9 


0xC00470FA 


0xC00470FB 


0xC00470FC 


0xC00470FD 


OxC00470FE 


0xC00470FF 


0xC0047100 


0xC0047101 


DECIMAL CODE 


-1073450759 


-1073450758 


-1073450757 


-1073450756 


-1073450755 


-1073450754 


-1073450753 


-1073450752 


-1073450751 


SYMBOLIC NAME 


DTS_E_EXPREVALINVALIDN 
UMBEROFPARAMSPLURAL 
SINGULAR 


DTS_E_EXPREVALINVALIDN 
UMBEROFPARAMSSINGUL 
ARPLURAL 


DTS_E_EXPREVALINVALIDN 
UMBEROFPARAMSPLURAL 
PLURAL 


DTS_E_EXPREVALFAILEDTOP 
ARSEEXPRESSIONOUTOFM 
EMORY 


DTS_E_INDIVIDUALCHECKP 
RODUCTLEVELFAILED 


DTS_E_PRODUCTLEVELTOL 
OW 


DTS_E_EXPREVALSTRINGLIT 
ERALTOOLONG 


DTS_E_EXPREVALSTRINGVA 
RIABLETOOLONG 


DTS_E_COMPONENT_NOIN 
TERFACE 


DESCRIPTION 


The function "%1" requires 
%2!d! parameters, not 
%3!d! parameter. The 
function name was 
recognized, but the number 
of parameters is not valid.> 


The function "%1" requires 
%2'd! parameter, not %3!d! 
parameters. The function 
name was recognized, but 
the number of parameters 
is not valid.> 


The function "%1" requires 
%2'd! parameters, not 
%3!d! parameters. The 
function name was 
recognized, but the number 
of parameters is not valid.> 


Attempt to parse the 
expression "%1" failed 
because there was an out- 
of-memory error. 


The %1 failed to be able to 
perform its required 
product level check and 
returned error code 
0x%2!8.8X!. 


SSIS Error Code 
DTS_E_PRODUCTLEVELTOL 
OW. The %1 cannot run on 
installed %2 of Integration 
Services. It requires %3 or 
higher. 


A string literal in the 
expression exceeds the 
maximum allowed length of 
%1!d! characters. 


The variable %1 contains a 
string that exceeds the 
maximum allowed length of 
%2'd! characters. 


The %1 was found, but it 
does not support a 
required Integration 
Services interface 
(IDTSRuntimeComponent10 
0). Obtain an updated 
version of this component 
from the >component 
provider. 


HEXADECIMAL CODE 


0xC0048000 


0xC0048001 


0xC0048002 


0xC0048003 


0xC0048004 


0xC0048005 


0xC0048006 


0xC0048007 


0xC0048008 


0xC0048009 


0xC004800B 


DECIMAL CODE 


-1073446912 


-1073446911 


-1073446910 


-1073446909 


-1073446908 


-1073446907 


-1073446906 


-1073446905 


-1073446904 


-1073446903 


-1073446901 


SYMBOLIC NAME 


DTS_E_CANNOTOPENREGIS 
TRYKEY 


DTS_E_INVALIDCOMPONE 
NTFILENAME 


DTS_E_UNKNOWNCOMPO 
NENTHASINVALIDCLSID 


DTS_E_COMPONENTHASIN 
VALIDCLSID 


DTS_E_INVALIDINDEX 


DTS_E_CANNOTACCESSDTS 
APPLICATIONOBJECT 


DTS_E_ERROROCCURREDW 
HILERETRIEVINGFILENAME 


DTS_E_CANNOTRETRIEVEPR 
OPERTYFORCOMPONENT 


DTS_E_DUPLICATEIDFOUN 
D 


DTS_E_CANNOTRETRIEVEBY 
LINEAGE 


DTS_E_CANNOTMAPRUNTI 
MECONNECTIONMANAGE 
R 


DESCRIPTION 


The registry key "%1" 
cannot be opened. 


Cannot get the file name 
for the component with a 
CLSID of "%1". Verify that 
the component is registered 
properly or that the CLSID 
provided is correct. 


The CLSID for one of the 
components is not valid. 
Verify that all the 
components in the pipeline 
have valid CLSIDs. 


The CLSID for one of the 
components with ID %1!d! 
is not valid. 


The index is not valid. 


The Application object 
cannot be accessed. Verify 
that SSIS is correctly 
installed. 


Retrieving the file name for 
a component failed with 
error code 0x%1!8.8X!. 


Cannot retrieve property 
"%1" from component with 
ID %2!d!. 


Attempting to use ID %1!d! 
more than once in the Data 
Flow Task. 


Cannot retrieve an item by 
lineage ID from a collection 
that does not contain 
columns. 


Cannot find the connection 
manager with ID "%1" in 
the connection manager 
collection due to error code 
0x%2!8.8X!. That 
connection manager is 
needed by >"%3" in the 
connection manager 
collection of "%4". Verify 
that a connection manager 
in the connection manager 
collection, Connections, has 
been created with that ID. 


HEXADECIMAL CODE 


OxC004800E 


0xC004800F 


0xC0048011 


0xC0048012 


0xC0048013 


0xC0048014 


0xC0048015 


0xC0048016 


0xC0048017 


DECIMAL CODE 


-1073446898 


-1073446897 


-1073446895 


-1073446894 


-1073446893 


-1073446892 


-1073446891 


-1073446890 


-1073446889 


SYMBOLIC NAME 


DTS_E_INPUTNOTKNOWN 


DTS_E_GETRTINTERFACEFAI 
LED 


DTS_E_CANTGIVEAWAYBUF 
FER 


DTS_E_CANTCREATEVIEWB 
UFFER 


DTS_E_UNUSABLETEMPOR 
ARYPATH 


DTS_E_DIRECTTONONERRO 
ROUTPUT 


DTS_E_BUFFERISPRIVATE 


DTS_E_BUFFERISFLAT 


DTS_E_BUFFERISPRIMEOUT 
PUT 


DESCRIPTION 


Thread "%1" received a 
buffer for input %2!d!, but 
this thread is not 
responsible for that input. 
An error occurred, causing 
the Data Flow engine 
scheduler to build a bad 
>execution plan. 


The component "%1" 
(%2!d!) cannot provide an 
IDTSRuntimeComponent10 
0 interface. 


The Data Flow task engine 
attempted to copy a buffer 
to assign another thread, 
but failed. 


The Data Flow task engine 
failed to create a view buffer 
of type %1!d! over type 
%2'd! for buffer %3!d. 


The buffer manager could 
not create a temporary file 
on the path "%1". The path 
will not be considered for 
temporary storage again. 


The buffer manager 
attempted to push an error 
row to an output that was 
not registered as an error 
output. There was a call to 
DirectErrorRow on an 
output that >does not have 
the IsErrorOut property set 
to TRUE. 


A call was made to a buffer 
method on a private buffer 
and private buffers do not 
support this operation. 


Private mode buffers do not 
support this operation. 


This operation cannot be 
called on a buffer passed to 
PrimeOutput. A call was 
made to a buffer method 
during PrimeOutput, but 
that call is not allowed 
during >PrimeOutput. 


HEXADECIMAL CODE 


0xC0048018 


0xC0048019 


0xC004801A 


0xC004801B 


0xC004801C 


0xC004801D 


0xC004801F 


0xC0048020 


0xC0048021 


DECIMAL CODE 


-1073446888 


-1073446887 


-1073446886 


-1073446885 


-1073446884 


-1073446883 


-1073446881 


-1073446880 


-1073446879 


SYMBOLIC NAME 


DTS_E_BUFFERISPROCESSIN 
PUT 


DTS_E_BUFFERGETTEMPFIL 
ENAME 


DTS_E_REFERENCECOLUMN 
TOOWIDE 


DTS_E_CANNOTGETRUNTIM 
ECONNECTIONMANAGERI 
D 


DTS_E_EMPTYRUNTIMECO 
NNECTIONMANAGERID 


DTS_E_METADATAREADONL 
Y 


DTS_E_UPGRADEFAILED 


DTS_E_COMPONENTVERSI 
ONMISMATCH 


DTS_E_ERRORCOMPONENT 


DESCRIPTION 


This operation cannot be 
called on a buffer passed to 
ProcessInput. A call was 
made to a buffer method 
during ProcessInput, but 
that call is not allowed 
during >ProcessInput. 


The buffer manager could 
not get a temporary file 
name. 


The code encountered a 
column that was too wide. 


Cannot get the ID of the 
runtime connection 
manager specified by "%1" 
in the connection manager 
collection, Connections, of 
"%2" due to error code 
>0x%3!8.8X!. Verify that the 
ConnectionManager|D 
property of the runtime 
connection object has been 
set for the component. 


The "%1" in the connection 
manager collection, 
Connections, of "%2" does 
not have a value for the ID 
property. Verify that the 
ConnectionManager|D 

> property of the runtime 
connection object has been 
set for the component. 


Metadata cannot be 
changed during execution. 


The component metadata 
for "%1" could not be 
upgraded to the newer 
version of the component. 
The PerformUpgrade 
method failed. 


The version of %1 is not 
compatible with this version 
of the DataFlow. 


The component is missing, 
not registered, not 
upgradeable, or missing 
required interfaces. The 
contact information for this 
component is "%1". 


HEXADECIMAL CODE 


0xC0048022 


0xC0049014 


0xC0049030 


0xC0049031 


0xC0049032 


0xC0049033 


0xC0049034 


0xC0049035 


DECIMAL CODE 


-1073446878 


-1073442796 


-1073442768 


-1073442767 


-1073442766 


-1073442765 


-1073442764 


-1073442763 


SYMBOLIC NAME 


DTS_E_BUFFERISNOTPRIME 
OUTPUT 


DTS_E_EXPREVALSTATIC_CO 
MPUTATIONFAILED 


DTS_E_EXPREVALSTATIC_DI 
VBYZERO 


DTS_E_EXPREVALSTATIC_LIT 
ERALOVERFLOW 


DTS_E_EXPREVALSTATIC_BI 
NARYOPNUMERICOVERFL 
OW 


DTS_E_EXPREVALSTATIC_BI 
NARYOPOVERFLOW 


DTS_E_EXPREVALSTATIC_FU 
NCTIONOVERFLOW 


DTS_E_EXPREVALSTATIC_BI 
NARYTYPEMISMATCH 


DESCRIPTION 


The method was called on 
the wrong buffer. Buffers 
that are not used for 
component output do not 
support this operation. 


An error occurred during 
computation of the 
expression. 


Division by zero occurred in 
the expression. 


The magnitude of the literal 
value was too big to fit in 
the type requested. 


The result of a binary 
operation was too big for 
the maximum size for 
numeric types. The operand 
types could not be implicitly 
cast into a numeric > 
(DT_NUMERIC) result 
without loss of precision or 
scale. To perform this 
operation, one or both 
operands need to be 
explicitly cast with a cast 
operator. 


The magnitude of the result 
of a binary operation 
overflows the maximum size 
for result data type. 


The magnitude of the result 
of a function call was too 
big to fit in the result type, 
and overflowed the type of 
the operand. An explicit cast 
to a larger >type may be 
required. 


Incompatible data types 
were used with a binary 
operator. The operand types 
could not be implicitly cast 
into compatible types for 
the operation. To > perform 
this operation, one or both 
operands need to be 
explicitly cast with a cast 
operator. 


HEXADECIMAL CODE 


0xC0049036 


0xC0049037 


0xC0049038 


0xC0049039 


0xC004903A 


0xC004903B 


0xC004903C 


0xC004903D 


0xC004903E 


DECIMAL CODE 


-1073442762 


-1073442761 


-1073442760 


-1073442759 


-1073442758 


-1073442757 


-1073442756 


-1073442755 


-1073442754 


SYMBOLIC NAME 


DTS_E_EXPREVALSTATIC_UN 
SUPPORTEDBINARYTY PE 


DTS_E_EXPREVALSTATIC_BI 
NARYSIGNMISMATCH 


DTS_E_EXPREVALSTATIC_BI 
NARYOPERATIONFAILED 


DTS_E_EXPREVALSTATIC_BI 
NARYOPERATIONSETTY PEF 
AILED 


DTS_E_EXPREVALSTATIC_ST 
RINGCOMPARISONFAILED 


DTS_E_EXPREVALSTATIC_UN 
SUPPORTEDUNNARYTYPE 


DTS_E_EXPREVALSTATIC_UN 
ARYOPERATIONFAILED 


DTS_E_EXPREVALSTATIC_UN 
ARYOPERATIONSETTYPEFAI 
LED 


DTS_E_EXPREVALSTATIC_PA 
RAMTYPEMISMATCH 


DESCRIPTION 


An unsupported data type 
was used with a binary 
operator. The type of one, 
or both, of the operands is 
not supported for the 
operation. To perform >this 
operation, one or both 
operands need to be 
explicitly cast with a cast 
operator. 


There is a sign mismatch for 
the bitwise binary operator. 
The operands for this 
operator must be both 
positive or both negative. 


A binary operation failed. 
There was an out-of- 
memory condition, or an 
internal error occurred. 


Setting the result type of a 
binary operation failed. 


Cannot compare two 
strings. 


An unsupported data type 
is used with a unary 
operator. The operand type 
is not supported for the 
operation. To perform this 
operation, the operand 
>needs to be explicitly cast 
with a cast operator. 


A unary operation failed. An 
out-of-memory condition 
occurred, or there was an 
internal error. 


Setting the result type of a 
unary operation failed. 


A function has a parameter 
with an unsupported data 
type. The type of the 
parameter cannot be 
implicitly cast into a 
compatible type for the 
function. To > perform this 
operation, the operand 
needs to be explicitly cast 
with a cast operator. 


HEXADECIMAL CODE 


0xC004903F 


0xC0049040 


0xC0049041 


0xC0049042 


0xC0049043 


0xC0049044 


0xC0049045 


0xC0049046 


0xC0049047 


DECIMAL CODE 


-1073442753 


-1073442752 


-1073442751 


-1073442750 


-1073442749 


-1073442748 


-1073442747 


-1073442746 


-1073442745 


SYMBOLIC NAME 


DTS_E_EXPREVALSTATIC_IN 
VALIDFUNCTION 


DTS_E_EXPREVALSTATIC_FN 
SUBSTRINGINVALIDLENGT 
H 


DTS_E_EXPREVALSTATIC_FN 
SUBSTRINGINVALIDSTARTI 
NDEX 


DTS_E_EXPREVALSTATIC_IN 
VALIDNUMBEROFPARAMS 


DTS_E_EXPREVALSTATIC_CH 
ARMAPPINGFAILED 


DTS_E_EXPREVALSTATIC_IN 
VALIDDATEPART 


DTS_E_EXPREVALSTATIC_IN 
VALIDNULLPARAM 


DTS_E_EXPREVALSTATIC_IN 
VALIDNULLPARAMTYPE 


DTS_E_EXPREVALSTATIC_FU 
NCTIONPARAMNOTSTATIC 


DESCRIPTION 


An invalid function name 
appeared in the expression. 
Verify that the function 
name is correct and does 
exist. 


The length parameter was 
not valid for function 
SUBSTRING. The length 
parameter cannot be 
negative. 


The start index was not 
valid for function 
SUBSTRING. The start index 
value must be an integer 
greater than zero. The start 
index is 1-based, >not 0- 
based. 


An incorrect number of 
parameters was given to a 
function. The function name 
was recognized, but the 
number of parameters was 
not correct. 


A character mapping 
function failed. 


An unrecognized date part 
parameter was specified for 
a date function. 


An invalid parameter was 
given for function NULL. 
The parameters of NULL 
must be static, and cannot 
contain dynamic elements 
such as input columns. 


An invalid parameter was 
given for function NULL. A 
parameter of NULL must be 
an integer, or a type that 
can be converted to an 
integer. 


An invalid parameter was 
given for a function. This 
parameter must be static 
and cannot contain 
dynamic elements such as 
input columns. 


HEXADECIMAL CODE 


0xC0049048 


0xC0049049 


0xC004904A 


0xC004904B 


0xC004904C 


0xC004904D 


OxC004904E 


0xC004904F 


0xC0049050 


DECIMAL CODE 


-1073442744 


-1073442743 


-1073442742 


-1073442741 


-1073442740 


-1073442739 


-1073442738 


-1073442737 


-1073442736 


SYMBOLIC NAME 


DTS_E_EXPREVALSTATIC_IN 
VALIDCASTPARAM 


DTS_E_EXPREVALSTATIC_IN 
VALIDCASTPARAMTYPE 


DTS_E_EXPREVALSTATIC_IN 
VALIDCAST 


DTS_E_EXPREVALSTATIC_IN 
VALIDTOKEN 


DTS_E_EXPREVALSTATIC_FAI 
LEDTOPARSEEXPRESSION 


DTS_E_EXPREVALSTATIC_UN 
ARYOPOVERFLOW 


DTS_E_EXPREVALSTATIC_CO 
MPUTEFAILED 


DTS_E_EXPREVALSTATIC_BU 
ILDSTRINGFAILED 


DTS_E_EXPREVALSTATIC_CA 
NNOTCONVERTRESULT 


DESCRIPTION 


An invalid parameter was 
given for a cast operation. 
Parameters of cast 
operators must be static, 
and cannot contain 
dynamic elements such as 
input >columns. 


An invalid parameter was 
given for a cast operation. A 
parameter of a cast 
operator must be an 
integer, or a type that can 
be converted to an 

integer. > 


The expression contained 
an unsupported type cast. 


The expression contained a 
token that was not 
recognized. The expression 
could not be parsed 
because it contains invalid 
elements. 


The expression is not valid 
and could not be parsed. It 
might contain invalid 
elements, or it might not be 
well-formed. 


The result of a unary minus 
(negation) operation 
overflowed the maximum 
size for result data type. The 
magnitude of the result of 
the operation overflows 
>the type of the result. 


Attempt to compute the 
expression failed. 


Attempt to generate a 
string representation of the 
expression failed. 


Cannot convert the 
expression result data type 
to the column data type. 
The result of the expression 
should be written to an 
input/output column, but 
>the data type of the 
expression cannot be 
converted to the data type 
of the column. 


HEXADECIMAL CODE 


0xC0049051 


0xC0049052 


0xC0049053 


0xC0049054 


0xC0049055 


0xC0049056 


0xC0049057 


DECIMAL CODE 


-1073442735 


-1073442734 


-1073442733 


-1073442732 


-1073442731 


-1073442730 


-1073442729 


SYMBOLIC NAME 


DTS_E_EXPREVALSTATIC_CO 
NDITIONALOPINVALIDCON 
DITIONTYPE 


DTS_E_EXPREVALSTATIC_CO 
NDITIONALOPTY PEMISMAT 
CH 


DTS_E_EXPREVALSTATIC_CO 
NDITIONALOPSETTY PEFAIL 
ED 


DTS_E_EXPREVALSTATIC_IN 
PUTCOLUMNNAMENOTFO 
UND 


DTS_E_EXPREVALSTATIC_IN 
PUTCOLUMNIDNOTFOUN 
D 


DTS_E_EXPREVALSTATIC_NO 
INPUTCOLUMNCOLLECTIO 
N 


DTS_E_EXPREVALSTATIC_VA 
RIABLENOTFOUND 


DESCRIPTION 


The conditional expression 
of the conditional operator 
has invalid data type. The 
conditional expression must 
be of type DT_BOOL. 


The data types of the 
operands of the conditional 
operator were incompatible. 
The operand types could 
not be implicitly cast into 
compatible >types for the 
conditional operation. To 
perform this operation, one 
or both operands need to 
be explicitly cast with a cast 
operator. 


Setting the result type of a 
conditional operation failed. 


The input column specified 
was not found in the input 
column collection. 


Attempt to find an input 
column by lineage ID failed. 
The input column was not 
found in the input column 
collection. 


The expression contains an 
unrecognized token that 
appears to be an input 
column reference, but the 
input column collection is 
not available to > process 
input columns. The input 
column collection has not 
been provided to the 
expression evaluator, but an 
input column was included 
in the expression. 


A variable specified was not 
found in the collection. It 
might not exist in the 
correct scope. Verify that 
the variable exists and that 
the scope is >correct. 


HEXADECIMAL CODE 


0xC0049058 


0xC0049059 


0xC004905A 


0xC004905B 


0xC004905C 


0xC004905D 


OxCO004905E 


DECIMAL CODE 


-1073442728 


-1073442727 


-1073442726 


-1073442725 


-1073442724 


-1073442723 


-1073442722 


SYMBOLIC NAME 


DTS_E_EXPREVALSTATIC_IN 
VALIDTOKENSTATE 


DTS_E_EXPREVALSTATIC_IN 
VALIDCASTCODEPAGE 


DTS_E_EXPREVALSTATIC_IN 
VALIDCASTPRECISION 


DTS_E_EXPREVALSTATIC_IN 
VALIDCASTSCALE 


DTS_E_EXPREVALSTATIC_CO 
NDITIONALOPCODEPAGE 
MISMATCH 


DTS_E_EXPREVALSTATIC_ILL 
EGALHEXESCAPEINSTRINGL 
ITERAL 


DTS_E_EXPREVALSTATIC_ILL 
EGALESCAPEINSTRINGLITE 
RAL 


DESCRIPTION 


Attempt to parse the 
expression failed. The 
expression contains an 
invalid or incomplete token. 
It may contain invalid 
elements, be missing part 
of a >required element 
such as closing parentheses, 
or may not be well formed. 


The value specified for the 
code page parameter of the 
cast to data type DT_STR or 
DT_TEXT is not valid. The 
specified code page is not 
installed on >the computer. 


The value specified for the 
precision parameter of a 
cast operation is out of 
range for the type cast. 


The value specified for the 
scale parameter of a cast 
operation is out of range 
for the type cast. Scale must 
not exceed precision and 
must not be >negative. 


The code pages do not 
match in a conditional 
operation. The code page of 
the left operand does not 
match the code page of the 
right operand. >For the 
conditional operator of that 
type, the code pages must 
be the same. 


A string literal contains an 
illegal hexadecimal escape 
sequence. The escape 
sequence is not supported 
in string literals in the 
expression > evaluator. 
Hexadecimal escape 
sequences must be of the 
form \xhhhh where h is a 
valid hexadecimal digit. 


The string literal contains an 
illegal escape sequence. The 
escape sequence is not 
supported in string literals 
in the expression evaluator. 
>If a backslash is needed in 
the string, format it as a 
double backslash, "\\". 


HEXADECIMAL CODE 


0xC004905F 


0xC0049060 


0xC0049061 


0xC0049062 


0xC0049063 


0xC0049064 


0xC0049065 


0xC0049066 


0xC0049067 


0xC0049068 


DECIMAL CODE 


-1073442721 


-1073442720 


-1073442719 


-1073442718 


-1073442717 


-1073442716 


-1073442715 


-1073442714 


-1073442713 


-1073442712 


SYMBOLIC NAME 


DTS_E_EXPREVALSTATIC_UN 
SUPPORTEDTYPE 


DTS_E_EXPREVALSTATIC_DA 
TACONVERSIONOVERFLO 
WwW 


DTS_E_EXPREVALSTATIC_DA 
TACONVERSIONNOTSUPPO 
RTED 


DTS_E_EXPREVALSTATIC_DA 
TACONVERSIONFAILED 


DTS_E_EXPREVALSTATIC_CO 
NDITIONALOPERATIONFAIL 
ED 


DTS_E_EXPREVALSTATIC_CA 
STFAILED 


DTS_E_EXPREVALFAILEDTOC 
ONVERTSTRCOLUMNTOWS 
TR 


DTS_E_EXPREVALSTATIC_FAI 
LEDTOCONVERTSTRCOLU 
MNTOWSTR 


DTS_E_EXPREVALSTATIC_FU 
NCTIONCOMPUTEFAILED 


DTS_E_EXPREVALSTATIC_FU 
NCTIONCONVERTPARAMT 
OMEMBERFAILED 


DESCRIPTION 


An unsupported or 
unrecognized data type was 
used in the expression. 


An overflow occurred while 
converting between data 
types. The source type is 
too large to fit in the 
destination type. 


The expression contains an 
unsupported data type 
conversion. The source type 
cannot be converted to the 
destination type. 


An error occurred while 
attempting to perform data 
conversion. The source type 
could not be converted to 
the destination type. 


The conditional operation 
failed. 


An error occurred while 
attempting to perform a 
type cast. 


Converting "%1" from type 
DT_STR to type DT_WSTR 
failed with error code 
0x%2!8.8X!. An error 
occurred while performing 
the implicit conversion on 
>the input column. 


Converting an input 
column from type DT_STR 
to type DT_WSTR failed. An 
error occurred while 
performing the implicit 
conversion on the input 
>column. 


An error occurred while 
evaluating the function. 


A function parameter 
cannot be converted to a 
static value. The parameter 
must be static and cannot 
contain dynamic elements 
such as >input columns. 


HEXADECIMAL CODE 


0xC0049088 


0xC0049089 


0xC0049096 


0xC0049097 


0xC0049098 


0xC004909B 


OxC004909C 


0xC004909D 


DECIMAL CODE 


-1073442680 


-1073442679 


-1073442666 


-1073442665 


-1073442664 


-1073442661 


-1073442660 


-1073442659 


SYMBOLIC NAME 


DTS_E_EXPREVALSTATIC_FN 
RIGHTINVALIDLENGTH 


DTS_E_EXPREVALSTATIC_FN 
REPLICATEINVALIDREPEATC 
OUNT 


DTS_E_EXPREVALSTATIC_BI 
NARYOPERATORCODEPAGE 
MISMATCH 


DTS_E_EXPREVALSTATIC_VA 
RIABLECOMPUTEFAILED 


DTS_E_EXPREVALSTATIC_VA 
RIABLETYPENOTSUPPORTE 
D 


DTS_E_EXPREVALSTATIC_CA 
STCODEPAGEMISMATCH 


DTS_E_EXPREVALSTATIC_IN 
VALIDTOKENSINGLEQUOTE 


DTS_E_EXPREVALSTATIC_IN 
VALIDTOKENSINGLEEQUAL 


DESCRIPTION 


The length parameter is not 
valid for function RIGHT. 
The length parameter 
cannot be negative. 


The repeat count parameter 
is not valid for function 
REPLICATE. This parameter 
cannot be negative. 


The code pages do not 
match in a binary 
operation. The code page of 
the left operand does not 
match the code page of the 
right operand. For >this 
binary operation, the code 
pages must be the same. 


Retrieving the value for a 
variable failed. 


The expression contains a 
variable with an 
unsupported data type. 


Unable to cast the 
expression because the 
code page of the value 
being cast does not match 
the requested result code 
page. The code page of the 
source >must match the 
code page requested for 
the destination. 


The expression contains an 
unexpected single 
quotation mark. A double 
quotation mark may be 
required. 


The expression contains an 
unexpected equal sign (=). 
This error usually occurs 
when a double equals sign 
==) is needed. 


HEXADECIMAL CODE 


OxC00490AA 


OxC00490AB 


0xC00490AC 


0xC00490D3 


0xC00490D4 


DECIMAL CODE 


-1073442646 


-1073442645 


-1073442644 


-1073442605 


-1073442604 


SYMBOLIC NAME 


DTS_E_EXPREVALSTATIC_A 
MBIGUOUSINPUTCOLUMN 
NAME 


DTS_E_EXPREVALSTATIC_PL 
ACEHOLDERINEXPRESSION 


DTS_E_EXPREVALSTATIC_A 
MBIGUOUSVARIABLENNA 
ME 


DTS_E_EXPREVALSTATIC_BI 
NARYOPDTSTRNOTSUPPOR 
TED 


DTS_E_EXPREVALSTATIC_CO 
NDITIONALOPDTSTRNOTSU 
PPORTED 


DESCRIPTION 


An ambiguous input 
column name was specified. 
The column must be 
qualified as [Component 
Name].[Column Name] or 
referenced by lineage ID. 
This >error occurs when the 
input column exists on 
more than one component, 
and must be differentiated 
by the addition of 
component name or by 
using the lineage ID. 


A placeholder function 
parameter or operand was 
found in an expression. This 
should be replaced with an 
actual parameter or 
operand. 


An ambiguous variable 
name was specified. The 
desired variable must be 
qualifed as 
@[Namespace::Variable]. 
This error occurs when the 
variable > exists in more 
than one namespace. 


For operands of binary 
operation, the data type 
DT_STR is only supported 
for input columns and cast 
operations. A DT_STR 
operand that is not an 
>input column or the result 
of a cast cannot be used 
with a binary operation. To 
perform this operation, the 
operand needs to be 
explicitly cast with a cast 
operator. 


For operands of the 
conditional operator, the 
data type DT_STR is only 
supported for input 
columns and cast 
operations. A DT_STR 
operand >that is not an 
input column or the result 
of a cast cannot be used 
with the conditional 
operation. To perform this 
operation, the operand 
needs to be explicitly cast 
with a cast operator. 


HEXADECIMAL CODE 


0xC00490D5 


0xC00490DD 


OxC00490DE 


OxCO00490DF 


OxC00490E0 


0xC00490E1 


OxC00490E2 


DECIMAL CODE 


-1073442603 


-1073442595 


-1073442594 


-1073442593 


-1073442592 


-1073442591 


-1073442590 


SYMBOLIC NAME 


DTS_E_EXPREVALSTATIC_FN 
FINDSTRINGINVALIDOCCU 
RRENCECOUNT 


DTS_E_EXPREVALSTATIC_IN 
VALIDDATEPARTNODE 


DTS_E_EXPREVALSTATIC_IN 
VALIDCASTLENGTH 


DTS_E_EXPREVALSTATIC_IN 
VALIDNULLLENGTH 


DTS_E_EXPREVALSTATIC_IN 
VALIDNULLCODEPAGE 


DTS_E_EXPREVALSTATIC_IN 
VALIDNULLPRECISION 


DTS_E_EXPREVALSTATIC_IN 
VALIDNULLSCALE 


DESCRIPTION 


The occurrence count 
parameter is not valid for 
function FINDSTRING. This 
parameter must be greater 
than zero. 


The "date part" parameter 
specified for a date function 
is not valid. "Date part" 
parameters must be static 
strings, and cannot contain 
dynamic >elements such as 
input columns. They must 
be of type DT_WSTR. 


The value specified for the 
length parameter of a cast 
operation is not valid. The 
length must be positive. 
The length specified for the 
type cast is >negative. 
Change to a positive value. 


The value specified for the 
length parameter of a NULL 
function is not valid. The 
length must be positive. 
The length specified for the 
NULL function is >negative. 
Change to a positive value. 


The value specified for the 
code page parameter of the 
NULL function with data 
type DT_STR or DT_TEXT is 
not valid. The code page 
specified is not > installed 
on the computer. Either 
change the code page that 
is specified, or install the 
code page on the computer. 


The value specified for the 
precision parameter of a 
NULL function is not valid. 
The precision that was 
specified is out of range for 
the NULL > function. 


The value specified for the 
scale parameter of a NULL 
function is not valid. The 
scale that was specified is 
out of range for the NULL 
function. Scale >must not 
exceed precision and must 
be positive. 


HEXADECIMAL CODE 


OxC00490E8 


OxCO00490F5 


OxC00490F6 


OxCO00490F7 


OxCO0F9304 


OxC00F9310 


0xC0202001 


0xC0202002 


0xC0202003 


0xC0202004 


0xC0202005 


0xC0202007 


DECIMAL CODE 


-1073442584 


-1073442571 


-1073442570 


-1073442569 


-1072721148 


-1072721136 


-1071636479 


-1071636478 


-1071636477 


-1071636476 


-1071636475 


-1071636473 


SYMBOLIC NAME 


DTS_E_XMLSRCERRORSETTI 
NGERROROUTPUTCOLUM 
NDATA 


DTS_E_TXLOOKUP_CANCEL 
_REQUESTED 


DTS_E_LOBLENGTHLIMITEX 
CEEDED 


DTS_E_CANNOTLOADCOM 
PONENT 


DTS_E_OLEDB_EXCEL_NOT_ 
SUPPORTED 


DTS_E_CACHEBADHEADER 


DTS_E_MISSINGSQLCOMM 
AND 


DTS_E_COMERROR 


DTS_E_ACQUIREDCONNECT 
IONUNAVAILABLE 


DTS_E_INCORRECTCOLUM 
NCOUNT 


DTS_E_COLUMNNOTFOUN 
D 


DTS_E_OLEDBRECORD 


DESCRIPTION 


The %1 failed attempting to 
write data to %2 on %3. %4 


Lookup transform has 
received a cancel request 
from the user. 


Processing of character or 
binary large object (LOB) 
data has stopped because 
the 4-GB limit was reached. 


The managed pipeline 
component "%1" could not 
be loaded. The exception 
was: %2. 


SSIS Error Code 
DTS_E_OLEDB_EXCEL_NOT_ 
SUPPORTED: The Excel 
Connection Manager is not 
supported in the 64-bit 
version of SSIS, as no OLE 
DB provider is available.> 


The cache file is damaged, 
or the file was not created 
by using the Cache 
connection manager. 
Provide a valid cache file. 


The SQL command has not 
been set correctly. Check 
SQLCommand property. 


COM error object 
information is available. 
Source: "%1" error code: 
0x%2!8.8X! Description: 
"%3". 


Unable to access the 
acquired connections. 


The number of columns is 
incorrect. 


Column "%1" cannot be 
found at the datasource. 


An OLE DB record is 
available. Source: "%1" 
Hresult: 0x%2!8.8x! 
Description: "%3". 


HEXADECIMAL CODE 


0xC0202009 


0xC020200A 


0xC020200B 


OxC020200E 


0xC0202010 


0xC0202011 


0xC0202014 


0xC0202015 


0xC0202016 


0xC0202017 


0xC0202018 


DECIMAL CODE 


-1071636471 


-1071636470 


-1071636469 


-1071636466 


-1071636464 


-1071636463 


-1071636460 


-1071636459 


-1071636458 


-1071636457 


-1071636456 


SYMBOLIC NAME 


DTS_E_LOLEDBERROR 


DTS_E_ALREADYCONNECTE 
D 


DTS_E_INCORRECTSTOCKPR 
OPERTYVALUE 


DTS_E_CANNOTOPENDATAF 
ILE 


DTS_E_DESTINATIONFLATFI 
LEREQUIRED 


DTS_E_TEXTQUALIFIERNOTF 
OUND 


DTS_E_CANNOTCONVERTTY 
PES 


DTS_E_PROBLEMDETECTIN 
GTYPECOMPATIBILITY 


DTS_E_CANNOTMAPINPUT 
COLUMNTOOUTPUTCOLU 
MN 


DTS_E_INCORRECTMINIMU 
MNUMBEROFOUTPUTS 


DTS_E_INCORRECTEXACTN 
UMBEROFOUTPUTS 


DESCRIPTION 


SSIS Error Code 
DTS_E_OLEDBERROR. An 
OLE DB error has occurred. 
Error code: 0x%1!8.8X!. 


Component is already 
connected. The component 
needs to be disconnected 
before attempting to 
connect it. 


The value of the property 
"%1" is incorrect. 


Cannot open the datafile 
"%1". 


No destination flat file name 
was provided. Make sure 
the flat file connection 
manager is configured with 
a connection string. If the 
flat file connection 
>manager is used by 
multiple components, 
ensure that the connection 
string contains enough file 
names. 


The text qualifier for column 
"%1" cannot be found. 


Conversion from "%1" to 
"%2" is not supported. 


The error code 0x%1!8.8X! 
was returned when 
validating type conversion 
from %2 to %3. 


Cannot find input column 
with lineage ID "%1!d!" 
which is needed by "%2". 
Check 
SourcelnputColumnLineage 
ID custom property of the 
output column. 


The number of outputs is 
incorrect. There must be at 
least %1!d! outputs. 


The number of outputs is 
incorrect. There must be 
exactly %1!d! output(s). 


HEXADECIMAL CODE 


0xC0202019 


0OxC020201A 


0xC020201B 


0xC020201C 


0xC020201D 


0xC020201F 


0xC0202020 


0xC0202021 


0xC0202022 


0xC0202023 


0xC0202024 


0xC0202025 


0xC0202026 


DECIMAL CODE 


-1071636455 


-1071636454 


-1071636453 


-1071636452 


-1071636451 


-1071636449 


-1071636448 


-1071636447 


-1071636446 


-1071636445 


-1071636444 


-1071636443 


-1071636442 


SYMBOLIC NAME 


DTS_E_STRINGCONVERSIO 
NTOOLONG 


DTS_E_INCORRECTEXACTN 
UMBEROFINPUTS 


DTS_E_CANNOTHAVEZEROI 
NPUTCOLUMNS 


DTS_E_CANNOTHAVEINPUT 
S 


DTS_E_PROCESSINPUTCALL 
EDWITHINVALIDINPUTID 


DTS_E_INCORRECTCUSTOM 
PROPERTYTY PE 


DTS_E_INVALIDBUFFERTYPE 


DTS_E_INCORRECTCUSTOM 
PROPERTYVALUE 


DTS_E_CONNECTIONREQUI 
REDFORMETADATA 


DTS_E_CANTCREATECUSTO 
MPROPERTY 


DTS_E_CANTGETCUSTOMPR 
OPERTYCOLLECTION 


DTS_E_CANNOTCREATEACC 
ESSOR 


DTS_E_PRIMEOUTPUTCALL 
EDWITHINVALIDOUTPUTID 


DESCRIPTION 


A string was too long to be 
converted. 


The number of inputs is 
incorrect. There must be 
exactly %1!d! inputs. 


The number of input 
columns for %1 cannot be 
zero. 


This component has %1!d! 
inputs. No input is allowed 
on this component. 


ProcessInput was called 
with an invalid input ID of 
%1'd!. 


The custom property "%1" 
needs to be of type %2. 


The buffer type is not valid. 
Make sure the Pipeline 
layout and all components 
pass validation. 


The value for custom 
property "%1" is incorrect. 


An error occurred due to no 
connection. A connection is 
required when requesting 
metadata. If you are 
working offline, uncheck 
Work Offline on the SSIS 
menu >to enable the 
connection. 


The custom property "%1" 
cannot be created. 


The custom property 
collection cannot be 
retrieved for initialization. 


Cannot create an OLE DB 
accessor. Verify that the 
column metadata is valid. 


PrimeOutput was called 
with an invalid output ID of 
%1!d!. 


HEXADECIMAL CODE 


0xC0202027 


0xC0202028 


OxC020202C 


0xC020202D 


0xC0202030 


0xC0202031 


0xC020203A 


0xC020203B 


0xC020203E 


0xC020203F 


0xC0202040 


0xC0202041 


0xC0202042 


0xC0202043 


DECIMAL CODE 


-1071636441 


-1071636440 


-1071636436 


-1071636435 


-1071636432 


-1071636431 


-1071636422 


-1071636421 


-1071636418 


-1071636417 


-1071636416 


-1071636415 


-1071636414 


-1071636413 


SYMBOLIC NAME 


DTS_E_INCORRECTSTOCKPR 
OPERTY 


DTS_E_CONNECTIONREQUI 
REDFORREAD 


DTS_E_ERRORWHILEREADI 
NGHEADERROWS 


DTS_E_DUPLICATECOLUMN 
NAME 


DTS_E_CANNOTGETCOLUM 
NNAME 


DTS_E_CANTDIRECTROW 


DTS_E_CANNOTCREATEBUL 
KINSERTHREAD 


DTS_E_BULKINSERTHREADI 
NITIALIZATIONFAILED 


DTS_E_BULKINSERTTHREAD 
ALREADY RUNNING 


DTS_E_BULKINSERTTHREAD 
ABNORMALCOMPLETION 


DTS_E_CANNOTGETIROWSE 
TFASTLOAD 


DTS_E_CONNECTREQUIRED 
FORMETADATAVALIDATION 


DTS_E_DESTINATIONTABLE 
NAMENOTPROVIDED 


DTS_E_ICONVERTTYPEUNA 
VAILABLE 


DESCRIPTION 


The value for property "%1" 
on "%2" is not valid. 


A connection is required to 
read data. 


An error occurred while 
reading header rows. 


Duplicate column name 
nog" 


Cannot get the name of the 
column with ID %1!dl. 


Direct row to output "%1" 
(%2!d!) failed. 


Cannot create the bulk 
insert thread due to error 
n964" 


The thread for the SSIS Bulk 
Insert task failed 
initialization. 


The thread for the SSIS Bulk 
Insert task is already 
running. 


The thread for the SSIS Bulk 
Insert task terminated with 
errors or warnings. 


Failed to open a fastload 
rowset for "%1". Check that 
the object exists in the 
database. 


Error due to no connection. 
A connection is required 
before metadata validation 
can proceed. 


A destination table name 
has not been provided. 


The OLE DB provider used 
by the OLE DB adapter 
does not support 
IConvertType. Set the 
adapter's 
ValidateColumnMetaData 
property to FALSE. 


HEXADECIMAL CODE 


0xC0202044 


0xC0202045 


0xC0202047 


0xC0202048 


0xC0202049 


0xC020204A 


0xC020204B 


OxC020204C 


0xC020204D 


0xC0202053 


0xC0202055 


0xC0202058 


DECIMAL CODE 


-1071636412 


-1071636411 


-1071636409 


-1071636408 


-1071636407 


-1071636406 


-1071636405 


-1071636404 


-1071636403 


-1071636397 


-1071636395 


-1071636392 


SYMBOLIC NAME 


DTS_E_LOLEDBPROVIDERDA 
TATYPECONVERSIONUNSU 
PPORTED 


DTS_E_VALIDATECOLUMN 
METADATAFAILED 


DTS_E_ATTEMPTINGTOINSE 
RTINTOAROWIDCOLUMN 


DTS_E_ATTEMPTINGTOINSE 
RTINTOAROWVERCOLUMN 


DTS_E_ATTEMPTINGTOINSE 
RTINTOAREADONLYCOLU 
MN 


DTS_E_UNABLETORETRIEVE 
COLUMNINFO 


DTS_E_CANTLOCKBUFFER 


DTS_E_INVALIDCOMPARIS 
ONFLAGS 


DTS_E_COLUMNMETADATA 
UNAVAILABLEFORVALIDATI 
ON 


DTS_E_CANNOTWRITETODA 
TAFILE 


DTS_E_COLUMNDELIMITER 
NOTFOUND 


DTS_E_COLUMNPARSEFAIL 
ED 


DESCRIPTION 


The OLE DB provider used 
by the OLE DB adapter 
cannot convert between 
types "%1" and "%2" for 
"%3". 


Column metadata 
validation failed. 


"%1" is a row ID column 
and cannot be included in a 
data insertion operation. 


Attempting insertion into 
the row version column 
"%1". Cannot insert into a 
row version column. 


Failure inserting into the 
read-only column "%1". 


Unable to retrieve column 
information from the data 
source. Make sure your 
target table in the database 
is available. 


A buffer could not be 
locked. The system is out of 
memory or the buffer 
manager has reached its 
quota. 


The %1 has a 
ComparisonFlags property 
that includes extra flags 
with the value %2!d!. 


The column metadata was 
unavailable for validation. 


Cannot write to the data 
file. 


The column delimiter for 
column "%1" was not 
found. 


Failed to parse the column 
"%1" in the data file. 


HEXADECIMAL CODE 


0xC020205A 


0xC020205B 


OxC020205C 


0xC020205D 


OxC020205E 


0xC020205F 


0xC0202060 


0xC0202061 


0xC0202062 


DECIMAL CODE 


-1071636390 


-1071636389 


-1071636388 


-1071636387 


-1071636386 


-1071636385 


-1071636384 


-1071636383 


-1071636382 


SYMBOLIC NAME 


DTS_E_RAWFILENAMEREQU 
IRED 


DTS_E_RAWFILECANTOPEN 


DTS_E_RAWFILECANTBUFFE 
R 


DTS_E_RAWCANTWRITE 


DTS_E_RAWBADHEADER 


DTS_E_RAWEXISTSCREATEO 
NCE 


DTS_E_RAWCANTAPPENDTR 
UNCATE 


DTS_E_RAWBADVERSION 


DTS_E_RAWVERSIONINCO 
MPATIBLEAPPEND 


DESCRIPTION 


The file name is not 
properly specified. Supply 
the path and name to the 
raw file either directly in the 
FileName property or by 
specifying a variable in the 
>FileNameVariable 
property. 


File "%1" cannot be opened 
for writing. Error may occur 
when there are no file 

privileges or the disk is full. 


An I/O buffer cannot be 
created for the output file. 
Error may occur when there 
are no file privileges or the 
disk is full. 


Cannot write %1!d! bytes to 
file "%2". See previous error 
messages for details. 


Encountered bad metadata 
in file header. The file is 
damaged or not a SSIS- 
produced raw data file. 


Error occurred because the 
output file already exists 
and the WriteOption is set 
to Create Once. Set the 
WriteOption property to 
Create Always, or delete the 
file. 


Error caused by conflicting 
property settings. Both the 
AllowAppend property and 
the ForceTruncate property 
are set to TRUE. Both 
properties cannot be set to 
TRUE. >Set one of the two 
properties to FALSE. 


The file had bad version and 
flags information. The file is 
damaged or not a SSIS- 
produced raw data file. 


The output file was written 
by an incompatible version 
and cannot be appended. 
The file may be an older file 
format that is no longer 
useable. 


HEXADECIMAL CODE 


0xC0202064 


0xC0202065 


0xC0202067 


0xC0202068 


0xC0202069 


0xC020206A 


0xC020206B 


OxC020206C 


DECIMAL CODE 


-1071636380 


-1071636379 


-1071636377 


-1071636376 


-1071636375 


-1071636374 


-1071636373 


-1071636372 


SYMBOLIC NAME 


DTS_E_RAWMETADATAMIS 
MATCH 


DTS_E_RAWMETADATACOU 
NTMISMATCH 


DTS_E_ERRORRETRIEVINGC 
OLUMNCODEPAGE 


DTS_E_RAWCANTREAD 


DTS_E_RAWUNEXPECTEDEO 
F 


DTS_E_RAWNOLONGTYPES 


DTS_E_RAWUNEXPECTEDTY 
PE 


DTS_E_RAWSTRINGTOOLON 
G 


DESCRIPTION 


Cannot append output file 
because no column in the 
existing file matches column 
"%1" from the input. Old file 
does not match in 
metadata. 


Cannot append output file 
because the number of 
columns in the output file 
does not match the number 
of columns in this 
destination. The old file 
does not match >in 
metadata. 


There was an error 
retrieving column code 
page information. 


Cannot read %1!d! bytes 
from file "%2". The cause of 
the failure should have 
been previously reported. 


Unexpected end-of-file 
encountered while reading 
%1!d! bytes from file "%2". 
The file ended prematurely 
because of an invalid file 
format. 


The column %1 cannot be 

used. The raw adapters do 

not support image, text, or 
ntext data. 


The adapter encountered 
an unrecognized data type 
of %1!d!. This could be 
caused by a damaged input 
file (source) or by an invalid 
buffer type (destination). 


String too long. The adapter 
read a string that was %1!d! 
bytes long, and expected a 
string no longer than %2!d! 
bytes, at offset %3!d!. This 
could indicate a damaged 
>input file. The file shows a 
string length that is too 
large for the buffer column. 


HEXADECIMAL CODE 


OxC020206E 


OxC020206F 


0xC0202070 


0xC0202071 


0xC0202072 


0xC0202073 


0xC0202074 


0xC0202075 


0xC0202076 


0xC0202077 


DECIMAL CODE 


-1071636370 


-1071636369 


-1071636368 


-1071636367 


-1071636366 


-1071636365 


-1071636364 


-1071636363 


-1071636362 


-1071636361 


SYMBOLIC NAME 


DTS_E_RAWSKIPFAILED 


DTS_E_RAWREADFAILED 


DTS_E_RAWFILENAMEINVA 
LID 


DTS_E_BULKINSERTAPIPREP 
ARATIONFAILED 


DTS_E_INVALIDDATABASEO 
BJECTNAME 


DTS_E_INVALIDORDERCLA 
USE 


DTS_E_RAWFILECANTOPEN 
READ 


DTS_E_TIMEGENCANTCREA 
TE 


DTS_E_TIMEGENCANTCONF 
IGURE 


DTS_E_TIMEGENCANTCON 
VERT 


DESCRIPTION 


The raw adapter attempted 
to skip %1!d! bytes in the 
input file for unreferenced 
column "%2" with lineage 
ID %3!d!, but there was an 
error. The error returned 
from the >operating 
system should have been 
previously reported. 


The raw adapter attempted 
to read %1!d! bytes in the 
input file for column "%2" 
with lineage ID %3!d!, but 
there was an error. The 
error returned from the 
operating system >should 
have been previously 
reported. 


The file name property is 
not valid. The file name is a 
device or contains invalid 
characters. 


Unable to prepare the SSIS 
bulk insert for data 
insertion. 


Database object name "%1" 
is not valid. 


Order clause is not valid. 


File "%1" cannot be opened 
for reading. Error may occur 
when there are no 
privileges or the file is not 
found. Exact cause is 
reported in previous error 
message. 


Unable to create the 
Microsoft.AnalysisServices.Ti 
meDimGeneratorTimeDimG 
enerator. 


Unable to configure the 
Microsoft.AnalysisServices.Ti 
meDimGenerator. 


Unsupported datatype for 
column %1!d!. 


HEXADECIMAL CODE 


0xC0202079 


0xC020207A 


0xC020207B 


OxC020207C 


0xC020207D 


OxC020207E 


0xC020207F 


0xC0202080 


0xC0202081 


0xC0202082 


0xC0202083 


0xC0202084 


DECIMAL CODE 


-1071636359 


-1071636358 


-1071636357 


-1071636356 


-1071636355 


-1071636354 


-1071636353 


-1071636352 


-1071636351 


-1071636350 


-1071636349 


-1071636348 


SYMBOLIC NAME 


DTS_E_TIMEGENCANTREAD 


DTS_E_TIMEGENCANTREAD 
COLUMN 


DTS_E_RSTDESTBADVARIAB 
LENAME 


DTS_E_RSTDESTRSTCONFIG 
PROBLEM 


DTS_E_RSTDESTRSTWRITEPR 


OBLEM 


DTS_E_FILENAMEINVALID 


DTS_E_FILENAMEINVALIDW 
ITHPARAM 


DTS_E_CMDDESTNOPARAM 
S 


DTS_E_CMDDESTNOTBOUN 
D 


DTS_E_TXPIVOTBADUSAGE 


DTS_E_TXPIVOTTOOMANYP 
IVOTKEYS 


DTS_E_TXPIVOTNOPIVOTKE 
Y 


DESCRIPTION 


The attempt to read from 
the 
Microsoft.AnalysisServices.Ti 
meDimGenerator failed with 
error code 0x%1!8.8X!. 


The attempt to read column 
"%2!d!" data from the 
Microsoft.AnalysisServices.Ti 
meDimGenerator failed with 
error code 0x%2!8.8X!. 


The VariableName property 
is not set to the name of a 
valid variable. Need a 
runtime variable name to 
write to. 


Unable to create or 
configure the 
ADODB.Recordset object. 


Error writing to the 
ADODB.Recordset object. 


The file name is not valid. 
The file name is a device or 
contains invalid characters. 


The file name "%1" is not 
valid. The file name is a 
device or contains invalid 
characters. 


Unable to retrieve 
destination column 
descriptions from the 
parameters of the SQL 
command. 


Parameters are not bound. 
All parameters in the SQL 

command must be bound 
to input columns. 


The PivotUsage value for 
the input column "%1" 
(%2!d!) is not valid. 


Too many Pivot Keys found. 
Only one input column can 
be used as the Pivot Key. 


No Pivot Key found. One 
input column must be used 
as the Pivot Key. 


HEXADECIMAL CODE 


0xC0202085 


0xC0202086 


0xC0202087 


0xC0202088 


0xC0202089 


0xC020208A 


0xC020208B 


0xC020208D 


OxC020208E 


0xC020208F 


0xC0202090 


0xC0202091 


DECIMAL CODE 


-1071636347 


-1071636346 


-1071636345 


-1071636344 


-1071636343 


-1071636342 


-1071636341 


-1071636339 


-1071636338 


-1071636337 


-1071636336 


-1071636335 


SYMBOLIC NAME 


DTS_E_TXPIVOTINPUTALRE 
ADYMAPPED 


DTS_E_TXPIVOTCANTMAPPI 
VOTKEY 


DTS_E_TXPIVOTCANTMAPPI 
NGNOTFOUND 


DTS_E_TXPIVOTEMPTYPIVO 
TKEYVALUE 


DTS_E_TXPIVOTDUPLICATE 
PIVOTKEYVALUE 


DTS_E_TXPIVOTOUTPUTNO 
TMAPPED 


DTS_E_TXPIVOTCANTCOMP 
ARESETKEYS 


DTS_E_TXPIVOTNOBLOB 


DTS_E_TXPIVOTBADOUTPU 
TTYPE 


DTS_E_TXPIVOTPROCESSER 
ROR 


DTS_E_TXPIVOTBADPIVOTK 
EYVALUE 


DTS_E_ERRORWHILESKIPPI 
NGDATAROWS 


DESCRIPTION 


More than one output 
column (such as "%1" 
(%2!d!)) is mapped to input 
column "%3" (%4!d!). 


Output column "%1" 
(%2!d!) cannot be mapped 
to PivotKey input column. 


Output column "%1" 
(%2!d!) has a SourceColumn 
%3!d! that is not a valid 
input column lineage ID. 


Output column "%1" 
(%2!d!) is mapped to a 
Pivoted Value input column, 
but its PivotKeyValue 
property value is missing. 


Output column "%1" 
(%2!d!) is mapped to a 
Pivoted Value input column 
with a non-unique 
PivotKeyValue property 
value. 


Input column "%1" (%2!d!) 
is not mapped to any 
output column. 


Failure occurred while 
comparing values for the 
set keys. 


The Input column "%1" 
(%2!d!) cannot be used as a 
Set Key, Pivot Key, or Pivot 
Value because it contains 
long data. 


Incorrect output type. The 
output column "%1" (%2!d!) 
must have the same data 
type and metadata as the 
input column to which it is 
mapped. 


Failure when trying to pivot 
the source records. 


The pivot key value "%1" is 
not valid. 


An error occurred while 
skipping data rows. 


HEXADECIMAL CODE 


0xC0202092 


0xC0202093 


0xC0202094 


0xC0202095 


0xC0202096 


0xC0202097 


0xC0202098 


0xC0202099 


OxC020209A 


0xC020209B 


OxC020209C 


0xC020209D 


OxC020209E 


DECIMAL CODE 


-1071636334 


-1071636333 


-1071636332 


-1071636331 


-1071636330 


-1071636329 


-1071636328 


-1071636327 


-1071636326 


-1071636325 


-1071636324 


-1071636323 


-1071636322 


SYMBOLIC NAME 


DTS_E_LERRORWHILEREADI 
NGDATAROWS 


DTS_E_FAILEDTOINITIALIZEF 
LATFILEPARSER 


DTS_E_UNABLETORETRIEVE 
COLUMNINFOFROMEFLATFI 
LECONNECTIONMANAGER 


DTS_E_FAILEDTOWRITEOUT 
COLUMNNAME 


DTS_E_INVALIDFLATFILECO 
LUMNTYPE 


DTS_E_DISKIOBUFFEROVER 
FLOW 


DTS_E_FAILEDTOWRITEOUT 
HEADER 


DTS_E_FAILEDTOGETFILESIZ 


E 


DTS_E_FAILEDTOSETFILEPOI 
NTER 


DTS_E_UNABLETOSETUPDIS 
KIOBUFFER 


DTS_E_COLUMNDATAOVER 
FLOWDISKIOBUFFER 


DTS_E_DISKIOFAILED 


DTS_E_DISKIOTIMEDOUT 


DESCRIPTION 


An error occurred while 
processing file "%1" on data 
row %2!164d!. 


An error occurred while 
initializing the flat file parser. 


Unable to retrieve column 
information from the flat file 
connection manager. 


Failed to write out column 
name for column "%1". 


The column type for column 
"%1" is incorrect. It is type 
"%2". It can only be either 
"%3" or "%A". 


The attempt to write data 
of %1!d! bytes into the disk 
I/O failed. The disk 1/O 
buffer has %2!d! free bytes. 


An error occurred while 
writing out the file header. 


An error occurred while 
getting the file size for file 
nop" 


An error occurred while 
setting the file pointer for 
file "%1". 


An error occurred while 
setting up the disk I/O 
buffer. 


The column data for column 
"%1" overflowed the disk 
\/O buffer. 


An unexpected disk I/O 
error occurred while reading 
the file. 


An disk I/O time out 
occurred while reading the 
file. 


HEXADECIMAL CODE 


OxC020209F 


OxC02020A0 


OxC02020A1 


OxC02020A2 


0xC02020A3 


OxC02020A4 


0xC02020A5 


OxC02020A6 


OxC02020A7 


DECIMAL CODE 


-1071636321 


-1071636320 


-1071636319 


-1071636318 


-1071636317 


-1071636316 


-1071636315 


-1071636314 


-1071636313 


SYMBOLIC NAME 


DTS_E_INPUTSNOTREADON 
LY 


DTS_E_CANNOTCOPYORCO 
NVERTFLATFILEDATA 


DTS_E_FAILEDCOLUMNDAT 
ACONVERSIONSTATUS 


DTS_E_VARIABLESCOLLECTI 
ONUNAVAILABLE 


DTS_E_TXUNPIVOTDUPLICA 
TEPIVOTKEYVALUE 


DTS_E_TXUNPIVOTNOUNPI 
VOTDESTINATION 


DTS_E_TXUNPIVOTBADKEYL 
IST 


DTS_E_TXUNPIVOTBADUNP 
IVOTMETADATA 


DTS_E_TXPIVOTBADPIVOTK 
EYCONVERT 


DESCRIPTION 


The Usage Type specified 
for the input columns to 
this transform cannot be 
read/write. Change the 
Usage Type to be read-only. 


Cannot copy or convert flat 
file data for column "%1". 


Data conversion failed. The 
data conversion for column 
"%1" returned status value 
%2!'d! and status text "%3". 


The Variables collection is 
not available. 


Duplicate PivotKeyValue. 
Input column "%1" (%2!d!) 
is mapped to a Pivoted 
Value output column and 
has a non-unique 
PivotKeyValue. 


No unpivot destination 
found. At least one input 
column must be mapped 
with a PivotKeyValue to an 
DestinationColumn in the 
output. 


PivotKeyValue is not valid. 
In an UnPivot transform 
with more than one 
unpivoted 
DestinationColumn, the set 
of PivotKeyValues per 
destination must match 
exactly. 


Incorrect UnPivot metadata. 
In an UnPivot transform, all 
input columns with a 
PivotKeyValue that is set, 
and are pointing to the 
same DestinationColumn, 
must >have metadata that 
exactly matches the 
DestinationColumn. 


Cannot convert the pivot 
key value "%1" to the data 
type of the pivot key 
column. 


HEXADECIMAL CODE 


0xC02020A8 


OxC02020A9 


OxCO02020AA 


OxC02020AB 


O0xC02020AC 


0xC02020AD 


OxCO02020AE 


OxCO2020AF 


0xC02020B0 


0xC02020B1 


DECIMAL CODE 


-1071636312 


-1071636311 


-1071636310 


-1071636309 


-1071636308 


-1071636307 


-1071636306 


-1071636305 


-1071636304 


-1071636303 


SYMBOLIC NAME 


DTS_E_TXUNPIVOTTOOMA 
NYPIVOTKEYS 


DTS_E_TXUNPIVOTUNMAP 
PEDOUTPUT 


DTS_E_TXUNPIVOTNOPIVO 
T 


DTS_E_TXUNPIVOTNOTINP 
UTMAP 


DTS_E_TXUNPIVOTDUPLICA 
TEDESTINATION 


DTS_E_TOTALINPUTCOLSCA 
NNOTBEZERO 


DTS_E_TXMERGEJOINMUST 
HAVESAMENUMBEROFINP 
UTANDOUTPUTCOLS 


DTS_E_INPUTMUSTBESORT 
ED 


DTS_E_TXMERGEJOININVAL 
IDJOINTY PE 


DTS_E_TXMERGEJOININVAL 
IDNUMKEYCOLS 


DESCRIPTION 


Too many Pivot Keys 
specified. Only one output 
column can be used as the 
Pivot Key. 


Output column "%1" 
(%2!d!) is not mapped by 
any input column's 
DestinationColumn 


property. 


No output column is 
marked as the PivotKey. 


Input column "%1" (%2!d!) 
has a DestinationColumn 
property value that does 
not refer to a valid output 
column LineagelD. 


Duplicate destination error. 
More than one non-pivoted 
input column is mapped to 
the same destination 
output column. 


No input columns found. At 
least one input column 
must be mapped to an 
output column. 


The number of input and 
output columns are not 
equal. The total number of 
input columns on all inputs 
must be the same as the 
total >number of output 
columns. 


The input is not sorted. The 
"%1" must be sorted. 


The JoinType custom 
property for the %1 
contains a value of %2!Id!, 
which is not valid. Valid 
values are 0 (full), 1 (left), or 
2 (inner). 


The NumKeyColumns value 
is not valid. In the %1, the 
value for the 
NumKeyColumns custom 
property must be between 
1 and %2!lu!. 


HEXADECIMAL CODE 


OxC02020B2 


0xC02020B3 


OxC02020B4 


0xC02020B5 


OxC02020B6 


0xC02020B7 


OxC02020B8 


OxC02020B9 


OxC02020BA 


0xC02020BB 


OxCO02020BC 


DECIMAL CODE 


-1071636302 


-1071636301 


-1071636300 


-1071636299 


-1071636298 


-1071636297 


-1071636296 


-1071636295 


-1071636294 


-1071636293 


-1071636292 


SYMBOLIC NAME 


DTS_E_NOKEYCOLS 


DTS_E_TXMERGEJOINNOTE 
NOUGHKEYCOLS 


DTS_E_TXMERGEJOINDATAT 
YPEMISMATCH 


DTS_E_TXMERGEJOININVAL 
IDSORTKEYPOS 


DTS_E_TXMERGEJOINSORT 
DIRECTIONMISMATCH 


DTS_E_TXMERGEJOINOUTP 
UTCOLMUSTHAVEASSOCIA 
TEDINPUTCOL 


DTS_E_TXMERGEJOINREAD 
ONLYINPUTCOLSWITHNO 
OUTPUTCOL 


DTS_E_TXMERGEJOINNONS 
TRINGCOMPARISONFLAGS 
NOTZERO 


DTS_E_TXMERGEJOINCOM 
PARISONFLAGSMISMATCH 


DTS_E_TXPIVOTBADPIVOTK 
EYVALUENOSTRING 


DTS_E_TXLINEAGEINVALIDL 
INEAGEITEM 


DESCRIPTION 


No key columns are found. 
The %1 must have at least 
one column with a 
SortKeyPosition that is non- 
zero. 


Not enough key columns. 
The %1 must have at least 
%2!Id! columns with non- 
zero SortKeyPosition values. 


Datatype mismatch 
occurred. The datatypes for 
the columns with 
SortKeyPosition value 
%1!Id! do not match. 


The column with the 
SortKeyPosition value of 
%1!Id! is not valid. It should 
be %2!Id!. 


Sort direction mismatch. 
The sort directions for the 
columns with 
SortKeyPosition value 
%1!Id! do not match. 


Missing column. The %1 
must have an associated 
input column. 


Input columns must have 
output columns. There are 
input columns with a usage 
type of read-only that do 
not have associated output 
columns. 


The comparison flags are 
not zero. The comparison 
flags for non-string 
columns must be zero. 


The comparison flags for 
the columns with 
SortKeyPosition value 
%1!Id! do not match. 


Unrecognized pivot key 
value. 


Lineage item value %1!Id! is 
not valid. The valid range is 
between %2!Id! and %3!Id!. 


HEXADECIMAL CODE 


0xC02020BD 


OxCO02020BE 


OxC02020BF 


0xC02020C1 


0xC02020C3 


OxC02020C4 


0xC02020C5 


OxC02020C6 


OxC02020C7 


0xC02020C8 


OxC02020C9 


OxC02020CA 


DECIMAL CODE 


-1071636291 


-1071636290 


-1071636289 


-1071636287 


-1071636285 


-1071636284 


-1071636283 


-1071636282 


-1071636281 


-1071636280 


-1071636279 


-1071636278 


SYMBOLIC NAME 


DTS_E_CANNOTHAVEANYIN 
PUTCOLUMNS 


DTS_E_TXLINEAGEDATATYP 
EMISMATCH 


DTS_E_TXLINEAGEINVALIDL 
ENGTH 


DTS_E_METADATAMISMATC 
HWITHOUTPUTCOLUMN 


DTS_E_TXMERGESORTKEYP 
OSMISMATCH 


DTS_E ADDROWTOBUFFER 
FAILED 


DTS_E_DATACONVERSIONF 
AILED 


DTS_E_FAILEDTOALLOCATE 
ROWHANDLEBUFFER 


DTS_E_FAILEDTOSENDROW 
TOSQLSERVER 


DTS_E_FAILEDTOPREPAREB 
UFFERSTATUS 


DTS_E_FAILEDTOBUFFERRO 
WSTARTS 


DTS_E_BULKINSERTTHREAD 
TERMINATED 


DESCRIPTION 


Input columns not allowed. 
The number of input 
columns must be zero. 


The datatype for "%1" is not 
valid for the specified 
lineage item. 


The length for "%1" is not 
valid for the specified 
lineage item. 


The metadata for "%1" does 
not match the metadata for 
the associated output 
column. 


There are output columns 
that have SortKeyPosition 
values that don't match the 
associated input columns' 
SortKeyPosition. 


The attempt to add a row 
to the Data Flow task buffer 
failed with error code 
0x%1!8.8X!. 


Data conversion failed while 
converting column "%1" 
(%2!d!) to column "%3" 
(%A4!d!). The conversion 
returned status value %5!d! 
and status text "%6". 


The attempt to allocate a 
row handle buffer failed 
with error code 0x%1!8.8X!. 


The attempt to send a row 
to SQL Server failed with 
error code 0x%1!8.8X!. 


The attempt to prepare the 
buffer status failed with 
error code 0x%1!8.8X!. 


The attempt to retrieve the 
start of the buffer row failed 
with error code 0x%1!8.8X!. 


The thread for the SSIS Bulk 
Insert is no longer running. 
No more rows can be 
inserted. Try increasing the 
bulk insert thread timeout. 


HEXADECIMAL CODE 


OxC02020CB 


OxC02020CC 


0xC02020CD 


OxCO02020CF 


0xC02020D0 


0xC02020D1 


0xC02020D2 


0xC02020D3 


0xC02020D4 


0xC02020D5 


DECIMAL CODE 


-1071636277 


-1071636276 


-1071636275 


-1071636273 


-1071636272 


-1071636271 


-1071636270 


-1071636269 


-1071636268 


-1071636267 


SYMBOLIC NAME 


DTS_E_RAWTOOMANYCOL 
UMNS 


DTS_E_TXUNIONALL_EXTRA 
DANGLINGINPUT 


DTS_E_TXUNIONALL_NOND 
ANGLINGUNATTACHEDINP 
UT 


DTS_E_TXPIVOTRUNTIMED 
UPLICATEPIVOTKEYVALUE 


DTS_E_TXPIVOTRUNTIMED 
UPLICATEPIVOTKEYVALUEN 
OSTRING 


DTS_E_FAILEDTOGETCOMP 
ONENTLOCALEID 


DTS_E_MISMATCHCOMPO 
NENTCONNECTIONMANAG 
ERLOCALEID 


DTS_E_LOCALEIDNOTSET 


DTS_E_RAWBYTESTOOLONG 


DTS_E_TXSAMPLINGINVALI 
DPCT 


DESCRIPTION 


The source file is not valid. 
The source file is returning a 
count of more than 
131,072 columns. This 
usually occurs when the 
source file is not produced 
by the raw >file destination. 


The %1 is an extra 
unattached input and will 
be removed. 


The %1 is not attached but 
is not marked as dangling. 
It will be marked as 
dangling. 


Duplicate pivot key value 
"%1". 


Duplicate pivot key value. 


Failure retrieving 
component locale ID. Error 
code 0x%1!8.8X!. 


Mismatched locale IDs. The 
component locale ID 
(%1!d!) does not match the 
connection manager locale 
ID (%2!d!). 


The component locale ID 
has not been set. Flat file 
adapters need to have the 
locale ID on the flat file 
connection manager set. 


The binary field is too large. 
The adapter attempted to 
read a binary field that was 
%1'!d! bytes long, but 
expected a field no longer 
than %2!d! bytes at offset 
%3!d!. >This usually occurs 
when the input file is not 
valid. The file contains a 
string length that is too 
large for the buffer column. 


The percentage, %2!Idl, is 
not valid for the "%1" 
property. It must be 
between 0 and 100. 


HEXADECIMAL CODE 


0xC02020D6 


0xC02020D7 


0xC02020D9 


0xC02020DB 


0xC02020DC 


0xC02020DD 


OxC02020E5 


OxC02020E8 


OxC02020E9 


OxCO02020EA 


0xC02020EB 


DECIMAL CODE 


-1071636266 


-1071636265 


-1071636263 


-1071636261 


-1071636260 


-1071636259 


-1071636251 


-1071636248 


-1071636247 


-1071636246 


-1071636245 


SYMBOLIC NAME 


DTS_E_TXSAMPLINGINVALI 
DROWS 


DTS_E_RAWSTRINGINPUTT 
OOLONG 


DTS_E_ATLEASTONEINPUT 
MUSTBEMAPPEDTOOUTPU 
T 


DTS_E_CANNOTCONVERTD 
ATATY PESWITHDIFFERENTC 
ODEPAGES 


DTS_E_COLUMNNOTMAPP 
EDTOEXTERNALMETADATA 
COLUMN 


DTS_E_COLUMNMAPPEDT 
ONONEXISTENTEXTERNAL 
METADATACOLUMN 


DTS_E_UNABLETOWRITELO 
BDATATOBUFFER 


DTS_E_CANNOTGETIROWSE 
T 


DTS_E_VARIABLEACCESSFAI 
LED 


DTS_E_CONNECTIONMANA 
GERNOTFOUND 


DTS_E_VERSIONUPGRADEF 
AILED 


DESCRIPTION 


The number of rows, %2!Id!, 
is not valid for the "%1" 
property. It must be greater 
than 0. 


The adapter was asked to 
write a string that was 
%1!164d! bytes long, but all 
data must be less than 
4294967295 bytes in 
length. 


No inputs were mapped to 
an output. The "%1" must 
have at least one input 
column mapped to an 
output column. 


Conversion from "%1" with 
code page %2!d! to "%3" 
with code page %4!d! is not 
supported. 


The external metadata 
column mapping for %1 is 
not valid. The external 
metadata column ID cannot 
be zero. 


The %1 is mapped to an 
external metadata column 
that does not exist. 


Writing long object data of 
type DT_TEXT, DT_NTEXT, or 
DT_IMAGE to Data Flow 
task buffer failed for column 
"%1". 


Opening a rowset for "%1" 
failed. Check that the object 
exists in the database. 


Accessing variable "%1" 
failed with error code 
0x%2!8.8X!. 


The connection manager 
"%1" is not found. A 
component failed to find 
the connection manager in 
the Connections collection. 


The upgrade from version 
"%1" to version %2!d! failed. 


HEXADECIMAL CODE 


OxCO02020EC 


OxC02020ED 


OxCO02020EE 


OxC02020EF 


OxC02020F0 


OxC02020F1 


OxC02020F2 


OxC02020F3 


OxC02020F4 


OxC02020F5 


DECIMAL CODE 


-1071636244 


-1071636243 


-1071636242 


-1071636241 


-1071636240 


-1071636239 


-1071636238 


-1071636237 


-1071636236 


-1071636235 


SYMBOLIC NAME 


DTS_E_RSTDESTBIGBLOB 


DTS_E_CANNOTCONVERTBE 
TWEENUNICODEANDNON 
UNICODESTRINGCOLUMN 
S 


DTS_E_ROWCOUNTBADVA 
RIABLENAME 


DTS_E_ROWCOUNTBADVA 
RIABLETYPE 


DTS_E_NOCOLUMNADVAN 
CETHROUGHFILE 


DTS_E_MERGEJOINSORTED 
OUTPUTHASNOSORTKEYP 
OSITIONS 


DTS_E_METADATAMISMATC 
HWITHINPUTCOLUMN 


DTS_E_RSTDESTBADVARIAB 
LE 


DTS_E_CANTPROCESSCOLU 
MNTYPECODEPAGE 


DTS_E_CANTINSERTCOLUM 
NTYPE 


DESCRIPTION 


A value in an input column 
is too large to be stored in 
the ADODB.Recordset 
object. 


Columns "%1" and "%2" 
cannot convert between 
unicode and non-unicode 
string data types. 


The variable "%1" specified 
by VariableName property 
is not a valid variable. Need 
a valid variable name to 
write to. 


The variable "%1" specified 
by VariableName property 
is not an integer. Change 
the variable to be of type 
VT_l4, VT_UI4, VT_I8, or 
VT_UI8. 


No column was specified to 
allow the component to 
advance through the file. 


The "%1" has IsSorted set 
to TRUE, but the 
SortKeyPosition on all 
output columns are zero. 
Either change the IsSorted 
to FALSE, or select at >least 
one output column to 
contain a non-zero 
SortKeyPosition. 


The "%1" metadata does 
not match the metadata of 
the input column. 


The value of the specified 
variable cannot be located, 
locked, or set. 


The column "%1" cannot be 
processed because more 
than one code page (%2!d! 
and %3!d!) are specified for 
it. 


The column "%1" can't be 
inserted because the 
conversion between types 
%2 and %3 is not 
supported. 


HEXADECIMAL CODE 


OxC02020F6 


OxC02020F8 


OxC02020F9 


OxCO02020FA 


0xC02020FB 


OxCO02020FC 


OxC02020FD 


OxCO2020FE 


OxC02020FF 


0xC0202100 


0xC0203110 


DECIMAL CODE 


-1071636234 


-1071636232 


-1071636231 


-1071636230 


-1071636229 


-1071636228 


-1071636227 


-1071636226 


-1071636225 


-1071636224 


-1071632112 


SYMBOLIC NAME 


DTS_E_CANNOTCONVERTBE 
TWEENUNICODEANDNON 
UNICODESTRINGCOLUMN 


DTS_E_COULDNOTFINDINP 
UTBUFFERCOLUMNBYLINE 
AGE 


DTS_E_COULDNOTGETCOL 
UMNINFOFORINPUTBUFFE 
R 


DTS_E_COULDNOTGETCOL 
UMNINFOFORCOPYBUFFE 
R 


DTS_E_COULDNOTREGISTE 
RCOPYBUFFER 


DTS_E_COULDNOTCREATEC 
OPYBUFFER 


DTS_E_DATAREADERDESTRE 
ADFAILED 


DTS_E_NOSCHEMAINFOFO 
UND 


DTS_E_GETSCHEMATABLEFA 
ILED 


DTS_E_SOURCETABLENAME 
NOTPROVIDED 


DTS_E_CACHE_INVALID_IN 
DEXPOS 


DESCRIPTION 


Column "%1" cannot 
convert between unicode 
and non-unicode string 
data types. 


The %1 cannot find the 
column with LineagelD 
%2!' Id! in its input buffer. 


The %1 cannot get the 
column information for 
column %2!lu! from its 
input buffer. 


The %1 cannot get the 
column information for 
column "%2!lu!" from its 
copy buffer. 


The %1 cannot register a 
buffer type for its copy 
buffer. 


The %1 cannot create a 
buffer to copy its data into 
for sorting. 


DataReader client has failed 
to call Read or has closed 
the DataReader. 


No column information was 
returned by the SQL 
command. 


The %1 was unable to 
retrieve column information 
for the SQL command. The 
following error occurred: %2 


A source table name has 
not been provided. 


The cache index position, 
%1!d!, is not valid. For non- 
index columns, the index 
position should be 0. For 
index columns, the index 
position should be a 
sequential, > positive 
number. 


HEXADECIMAL CODE 


0xC0203111 


0xC0203112 


0xC0203113 


0xC0204000 


0xC0204002 


0xC0204003 


0xC0204004 


0xC0204006 


0xC0204007 


DECIMAL CODE 


-1071632111 


-1071632110 


-1071632109 


-1071628288 


-1071628286 


-1071628285 


-1071628284 


-1071628282 


-1071628281 


SYMBOLIC NAME 


DTS_E_CACHE_DUPLICATE_| 
NDEXPOS 


DTS_E_CACHE_TOO_FEW_| 
NDEX_COLUMNS 


DTS_E_CACHE_INDEXPOS_ 
NOT_CONTINUOUS 


DTS_E_PROPERTYNOTSUPP 
ORTED 


DTS_E_CANTCHANGEPROP 
ERTYTYPE 


DTS_E_CANTADDOUTPUTID 


DTS_E_CANTDELETEOUTPU 
TID 


DTS_E_FAILEDTOSETPROPER 
TY 


DTS_E_FAILEDTOSETOUTPU 
TCOLUMNTYPE 


DESCRIPTION 


The index position, %1!d!, is 
a duplicate. For non-index 
columns, the index position 
should be 0. For index 
columns, the index position 
should be a sequential, 

> positive number. 


At least one index column 
should be specified for the 
Cache connection manager. 
To specify an index column, 
set the Index Position 
property of the cache 
>column. 


Cache index positions must 
be contiguous. For non- 
index columns, the index 
position should be 0. For 
index columns, the index 
position should be a 
>sequential, positive 
number. 


The property "%1" cannot 
be set on "%2". The 
property being set is not 
supported on the specified 
object. Check the property 
name, case, and spelling. 


The property type cannot 
be changed from the type 
that was set by the 
component. 


Output ID %1!d! failed 
during insert. The new 
output was not created. 


Cannot delete output ID 
%1'!d! from the output 
collection. The ID may not 
be valid, or the ID may have 
been the default or error 
output. 


Failed to set property "%1" 
on "%2". 


Failed to set the type of %1 
to type: "%2", length: %3!d!, 
precision: %4!d!, scale: 
%5!d!, codepage: %6!d!. 


HEXADECIMAL CODE 


0xC0204008 


0xC020400A 


0xC020400B 


OxC020400E 


0xC020400F 


0xC0204010 


0xC0204011 


DECIMAL CODE 


-1071628280 


-1071628278 


-1071628277 


-1071628274 


-1071628273 


-1071628272 


-1071628271 


SYMBOLIC NAME 


DTS_E_MORETHANONEERR 
OROUTPUTFOUND 


DTS_E_CANTSETOUTPUTCO 
LUMNPROPERTY 


DTS_E_CANTMODIFYERROR 
OUTPUTCOLUMNDATATYP 
E 


DTS_E_CANONLYSETISSORT 
EDONSOURCE 


DTS_E_CANONLYSETSORTK 
EYONSOURCE 


DTS_E_CANONLYSETCOMP 
FLAGSONSOURCE 


DTS_E_NONSTRINGCOMPA 
RISONFLAGSNOTZERO 


DESCRIPTION 


More than one error output 
was found on the 
component, and there can 
be only one. 


The property on an output 
column cannot be set. 


The data type for "%1" 
cannot be modified in the 
error "%2". 


The "%1" cannot have its 
IsSorted property set to 
TRUE because it is not a 
source output. A source 
output has a 
SynchronousInputID value 
of zero. 


The "%1" cannot have a 
SortKeyPosition property 
set to non-zero because 
"%2" is not a source output. 
The output column 
"colname" (ID) cannot have 
its >SortKeyPosition 
property set to non-zero 
because its output 
“outputname’ (ID) is not a 
source output. 


The ComparisonFlags 
property cannot be set to a 
non-zero value for "%1" 
because the "%2" is not a 
source output. The output 
column "colname' (ID) 
cannot have >a 
ComparisonFlags property 
set to non-zero because its 
output "outputname’ (ID) is 
not a source output. 


The comparison flags for 
"%1" must be zero because 
its type is not a string type. 
ComparisonFlags can only 
be non-zero for string type 
columns. 


HEXADECIMAL CODE 


0xC0204012 


0xC0204013 


0xC0204014 


0xC0204015 


0xC0204016 


0xC0204017 


0xC0204018 


0xC0204019 


0OxC020401A 


0xC020401B 


0xC020401C 


DECIMAL CODE 


-1071628270 


-1071628269 


-1071628268 


-1071628267 


-1071628266 


-1071628265 


-1071628264 


-1071628263 


-1071628262 


-1071628261 


-1071628260 


SYMBOLIC NAME 


DTS_E_COMPFLAGSONLYO 
NSORTCOL 


DTS_E_READONLYSTOCKPR 
OPERTY 


DTS_E_INVALIDDATATYPE 


DTS_E_CODEPAGEREQUIRE 
D 


DTS_E_INVALIDSTRINGLEN 
GTH 


DTS_E_INVALIDSCALE 


DTS_E_INVALIDPRECISION 


DTS_E_PROPVALUEIGNORE 
D 


DTS_E_CANTSETOUTPUTCO 
LUMNDATATYPEPROPERTIE 
S 


DTS_E_INVALIDDATATYPEF 
ORERRORCOLUMNS 


DTS_E_NOERRORDESCFOR 
COMPONENT 


DESCRIPTION 


The "%1" cannot have a 
ComparisonFlags property 
set to non-zero because its 
SortKeyPosition is set to 
zero. An output column's 
ComparisonFlags can only 
be non-zero >if its 
SortKeyPosition is also non- 
zero. 


The property is read-only. 


The %1 had an invalid 
datatype value (%2! Id!) set. 


The "%1" requires a code 
page to be set but the 
value passed was zero. 


The "%1" has a length that 
is not valid. The length 
must be between %2! Id! 
and %3!lId!. 


The "%1" has a scale that is 
not valid. The scale must be 
between %2!Id! and %3!lId!. 


The "%1" has a precision 
that is not valid. The 
precision must be between 
%2!\\d! and %3!Id!. 


The "%1" has a value set for 
length, precision, scale, or 
code page that is a value 
other than zero, but the 
data type requires the value 
to be zero. 


The %1 does not allow 
setting output column 
datatype properties. 


The "%1" contains an invalid 
data type. "%1 " is a special 
error column, and the only 

valid data type is DT_I4. 


The component does not 
supply error code 
descriptions. 


HEXADECIMAL CODE 


0xC020401D 


0xC020401F 


0xC0204020 


0xC0204023 


0xC0204024 


0xC0204025 


0xC0204026 


0xC0204027 


0xC0204028 


DECIMAL CODE 


-1071628259 


-1071628257 


-1071628256 


-1071628253 


-1071628252 


-1071628251 


-1071628250 


-1071628249 


-1071628248 


SYMBOLIC NAME 


DTS_E_UNRECOGNIZEDERR 
ORCODE 


DTS_E_TRUNCATIONTRIGGE 
REDREDIRECTION 


DTS_E_CANTSETUSAGETYPE 
TOREADWRITE 


DTS_E_CANTSETUSAGETYPE 


DTS_E_FAILEDTOSETUSAGET 
YPE 


DTS_E_FAILEDTOSETOUTPU 
TCOLUMNDATATY PEPROPE 
RTIES 


DTS_E_UNABLETORETRIEVE 
METADATA 


DTS_E_CANNOTMAPOUTP 
UTCOLUMN 


DTS_E_UNSUPPORTEDVARI 
ABLETYPE 


DESCRIPTION 


The specified error code is 
not associated with this 
component. 


A truncation caused a row 
to be redirected, based on 
the truncation disposition 
settings. 


The "%1" is unable to make 
the column with lineage ID 
%2!d! read/write because 
that usage type is not 
allowed on this column. An 
attempt was made to 
change >the usage type of 
an input column to a type, 
UT_READWRITE, that is not 
supported on this 
component. 


The %1 has forbidden the 
requested use of the input 
column with lineage ID 
%2!\d!. 


The "%1" was unable to 
make the requested change 
to the input column with 
lineage ID %2!d!. The 
request failed with error 
code 0x%3!8.8X!. The 
specified error >occurred 
while attempting to set the 
usage type of an input 
column. 


Attempt to set the data 
type properties on "%1" 
failed with error code 
0x%2!8.8X!. The error 
occurred while attempting 
to set one or more of the 
>data type properties of 
the output column. 


The metadata for "%1" 
cannot be retrieved. Make 
sure the object name is 
correct and the object 
exists. 


The output column cannot 
be mapped to an external 
metadata column. 


The variable %1 is required 
to be of type "%2". 


HEXADECIMAL CODE 


0xC020402A 


0xC020402B 


0xC020402C 


0xC020402D 


0xC0207000 


0xC0207001 


0xC0207002 


0xC0207003 


0xC0207004 


0xC0207005 


DECIMAL CODE 


-1071628246 


-1071628245 


-1071628244 


-1071628243 


-1071616000 


-1071615999 


-1071615998 


-1071615997 


-1071615996 


-1071615995 


SYMBOLIC NAME 


DTS_E_CANTSETEXTERNAL 
METADATACOLUMNDATAT 
YPEPROPERTIES 


DTS_E_IDNOTINPUTNOROU 
TPUT 


DTS_E_METADATACOLLECTI 
ONNOTUSED 


DTS_E_NOBUFFERTYPEONS 
YNCOUTPUT 


DTS_E_INPUTCOLUMNUSA 
GETYPENOTREADONLY 


DTS_E_MISSINGCUSTOMPR 
OPERTY 


DTS_E_ILLEGALCUSTOMOU 
TPUTPROPERTY 


DTS_E_INVALIDOUTPUTEXC 
LUSIONGROUP 


DTS_E_PROPERTYISEMPTY 


DTS_E_CREATEEXPRESSION 
OBJECTFAILED 


DESCRIPTION 


The %1 does not allow 
setting external metadata 
column datatype 
properties. 


The ID, %1!lu!, is neither an 
input ID nor an output ID. 
The specified ID must be 
the input ID or the output 
ID that the external 
metadata collection is 
associated >with. 


The external metadata 
collection on "%1" is 
marked as not used, so no 
operations can be 
performed on it. 


The %1 is a synchronous 
output and the buffer type 
cannot be retrieved for a 
synchronous output. 


The input column "%1" 
must be read-only. The 
input column has a usage 
type other than read-only, 
which is not allowed. 


The "%1" is missing the 
required property "%2". The 
object is required to have 
the specified custom 


property. 


The output %1 cannot not 
have property "%2", but 
currently has that property 
assigned. 


The %1 must be in 
exclusion group %2!d!. All 
outputs must be in the 
specified exclusion group. 


The property "%1" is empty. 
The property cannot be 
empty. 


Memory cannot be 
allocated for the expression 
"%1". There was an out-of- 
memory error while 
creating an internal object 
to hold the expression. 


HEXADECIMAL CODE 


0xC0207006 


0xC0207007 


0xC0207008 


0xC020700A 


0xC020700B 


0xC020700C 


0xC020700E 


0xC020700F 


0xC0207011 


DECIMAL CODE 


-1071615994 


-1071615993 


-1071615992 


-1071615990 


-1071615989 


-1071615988 


-1071615986 


-1071615985 


-1071615983 


SYMBOLIC NAME 


DTS_E_EXPRESSIONPARSEFA 
ILED 


DTS_E_EXPRESSIONCOMPU 
TEFAILED 


DTS_E_FAILEDTOCREATEEXP 
RESSIONARRAY 


DTS_E_FAILEDTOCREATEEXP 
RESSIONMANANGER 


DTS_E_SPLITEXPRESSIONN 
OTBOOLEAN 


DTS_E_EXPRESSIONVALIDAT 
IONFAILED 


DTS_E_COLUMNNOTMATC 
HED 


DTS_E_SETRESULTCOLUMN 
FAILED 


DTS_E_FAILEDTOGETLOCAL 
EIDFROMPACKAGE 


DESCRIPTION 


Cannot parse the 
expression "%1". The 
expression was not valid, or 
there is an out-of-memory 
error. 


Computing the expression 
"%1" failed with error code 
0x%2!8.8X!. The expression 
may have errors, such as 
divide by zero, that cannot 
be detected at parse time, 
or >there may be an out- 
of-memory error. 


Memory cannot be 
allocated for the Expression 
objects. An out-of memory 
error occurred while 
creating the array of 
Expression object pointers. 


The %1 failed with error 
code 0x%2!8.8X! while 
creating the Expression 
Manager. 


The expression "%1" is not 
Boolean. The result type of 
the expression must be 
Boolean. 


The expression "%1" on 
"%2" is not valid. 


The column "%1" (%2!d!) 
cannot be matched to any 
input file column. The 
output column name or 
input column name cannot 
be found in the file. 


Attempting to set the result 
column for the expression 
"%1" on %2 failed with error 
code 0x%3!8.8X!. The input 
or output column that was 
to receive the result of >the 
expression cannot be 
determined, or the 
expression result cannot be 
cast to the column type. 


The %1 failed to get the 
locale ID from the package. 


HEXADECIMAL CODE 


0xC0207012 


0xC0207013 


0xC0207014 


0xC0207015 


0xC0207016 


0xC0208001 


0xC0208002 


0xC0208003 


0xC0208004 


0xC0208005 


0xC0208007 


0xC0208008 


DECIMAL CODE 


-1071615982 


-1071615981 


-1071615980 


-1071615979 


-1071615978 


-1071611903 


-1071611902 


-1071611901 


-1071611900 


-1071611899 


-1071611897 


-1071611896 


SYMBOLIC NAME 


DTS_E_INCORRECTPARAME 
TERMAPPINGFORMAT 


DTS_E_NOTENOUGHPARA 
METERSPROVIDED 


DTS_E_PARAMETERNOTFOU 
NDINMAPPING 


DTS_E_DUPLICATEDATASO 
URCECOLUMNNAME 


DTS_E_DATASOURCECOLU 
MNWITHNONAMEFOUND 


DTS_E_DISCONNECTEDCO 
MPONENT 


DTS_E_INVALIDCOMPONE 
NTID 


DTS_E_INVALIDINPUTCOUN 
T 


DTS_E_INVALIDOUTPUTCO 
UNT 


DTS_E_NOINPUTSOROUTP 
UTS 


DTS_E_CANTALLOCATECOL 
UMNINFO 


DTS_E_OUTPUTCOLUMNN 
OTININPUT 


DESCRIPTION 


The parameter mapping 
string is not in the correct 
format. 


The SQL command requires 
%1!d! parameters, but the 
parameter mapping only 
has %2!d! parameters. 


The SQL command requires 
a parameter named "%1", 
which is not found in the 
parameter mapping. 


There is more than one 
data source column with 
the name "%1". The data 
source column names must 
be unique. 


There is a data source 
column with no name. Each 
data source column must 
have a name. 


A component is 
disconnected from the 
layout. 


The ID for a layout 
component is not valid. 


A component has an invalid 
number of inputs. 


A component has an invalid 
number of outputs. 


A component does not 
have any inputs or outputs. 


Not enough memory was 
available to allocate a list of 
the columns that are being 
manipulated by this 
component. 


Output column "%1" 
(%2!d!) references input 
column with lineage ID 
%3!d!, but no input could 
be found with that lineage 
ID. 


HEXADECIMAL CODE 


0xC0208009 


O0xC020800A 


0xC020800D 


OxCO020800E 


OxC020800F 


0xC0208010 


0xC0208011 


0xC0208014 


0xC0208016 


0xC0208017 


0xC0208018 


0xC0208019 


DECIMAL CODE 


-1071611895 


-1071611894 


-1071611891 


-1071611890 


-1071611889 


-1071611888 


-1071611887 


-1071611884 


-1071611882 


-1071611881 


-1071611880 


-1071611879 


SYMBOLIC NAME 


DTS_E_SORTNEEDSONEKEY 


DTS_E_SORTDUPLICATEKEY 
WEIGHT 


DTS_E_CANTMODIFYINVALI 
D 


DTS_E_CANTADDINPUT 


DTS_E_CANTADDOUTPUT 


DTS_E_CANTDELETEINPUT 


DTS_E_CANTDELETEOUTPU 
T 


DTS_E_CANTCHANGEUSAG 
ETYPE 


DTS_E_INVALIDUSAGETYPE 
FORCUSTOMPROPERTY 


DTS_E_READWRITECOLUM 
NMISSINGREQUIREDCUST 
OMPROPERTY 


DTS_E_CANTDELETECOLUM 
N 


DTS_E_CANTADDCOLUMN 


DESCRIPTION 


At least one input column 
must be marked as a sort 
key, but no keys were 
found. 


Both column "%1" (%2!d!) 
and column "%3" (%4!d!) 
were marked with sort key 
weight %5!d!. 


The component cannot 
perform the requested 
metadata change until the 
validation problem is fixed. 


An input cannot be added 
to the inputs collection. 


An output cannot be added 
to the outputs collection. 


An input cannot be deleted 
from the inputs collection. 


An output cannot be 
removed from the outputs 
collection. 


The usage type of the 
column cannot be changed. 


The %1 must be read/write 
to have custom property 
"%2". The input or output 
column has the specified 
custom property, but is not 
read/write. Remove the 

> property, or make the 
column read/write. 


The %1 is read/write and is 
required to have custom 
property "%2". Add the 
property, or make remove 
the read/write attribute 
from the column.> 


The column cannot be 
deleted. The component 
does not allow columns to 
be deleted from this input 
or output. 


The component does not 
allow adding columns to 
this input or output. 


HEXADECIMAL CODE 


OxC020801A 


0xC020801B 


0xC020801C 


0xC020801D 


OxC020801E 


0xC020801F 


0xC0208020 


0xC0208021 


0xC0208023 


0xC0208024 


DECIMAL CODE 


-1071611878 


-1071611877 


-1071611876 


-1071611875 


-1071611874 


-1071611873 


-1071611872 


-1071611871 


-1071611869 


-1071611868 


SYMBOLIC NAME 


DTS_E_CANNOTTFINDRUNT 
IMECONNECTIONOBJECT 


DTS_E_CANNOTFINDRUNTI 
MECONNECTIONMANAGE 
R 


DTS_E_CANNOTACQUIREC 
ONNECTIONFROMCONNE 
CTIONMANAGER 


DTS_E_ACQUIREDCONNECT 
IONISINVALID 


DTS_E_INCORRECTCONNEC 
TIONMANAGERTY PE 


DTS_E_CANNOTACQUIREM 
ANAGEDCONNECTIONFRO 
MCONNECTIONMANAGER 


DTS_E_CANTINITINPUT 


DTS_E_CANTINITOUTPUT 


DTS_E_EXTRACTORCANTWR 
ITE 


DTS_E_INCORRECTCONNEC 
TIONOBJECTTYPE 


DESCRIPTION 


The connection "%1" cannot 
be found. Verify that the 
connection manager has a 
connection with that name. 


The runtime connection 
manager with the ID "%1" 
cannot be found. Verify that 
the connection manager 
collection has a connection 
manager with that ID. 


SSIS Error Code 
DTS_E_CANNOTACQUIREC 
ONNECTIONFROMCONNE 
CTIONMANAGER. The 
AcquireConnection method 
call to the connection 
manager "%1" failed >with 
error code 0x%2!8.8X!. 
There may be error 
messages posted before 
this with more information 
on why the 
AcquireConnection method 
call failed. 


The connection acquired 
from the connection 
manager "%1" is not valid. 


The connection manager 

"%1" is an incorrect type. 

The type required is "%2". 
The type available to the 

component is "%3". 


Cannot acquire a managed 
connection from the run- 
time connection manager. 


An input cannot be created 
to initialize the inputs 
collection. 


An output cannot be 
created to initialize the 
outputs collection. 


Writing to the file "%1" 
failed with error code 
0x%2!8.8X!. 


The connection manager 
"%1" returned an object of 
an incorrect type from the 
AcquireConnection method. 


HEXADECIMAL CODE 


0xC0208025 


0xC0208026 


0xC0208027 


0xC0208028 


0xC0208029 


0xC020802A 


0xC020802B 


0xC020802C 


0xC020802D 


DECIMAL CODE 


-1071611867 


-1071611866 


-1071611865 


-1071611864 


-1071611863 


-1071611862 


-1071611861 


-1071611860 


-1071611859 


SYMBOLIC NAME 


DTS_E_INPUTCOLPROPERTY 
NOTFOUND 


DTS_E_EXTRACTORUNREFER 
ENCED 


DTS_E_EXTRACTORREFEREN 
CEDCOLUMNNOTFOUND 


DTS_E_EXTRACTORDATACO 
LUMNNOTBLOB 


DTS_E_INSERTERREFERENCE 


DCOLUMNNOTFOUND 


DTS_E_INSERTERCANTREAD 


DTS_E_TXSCD_NOTYPEDCO 
LUMNSATINPUT 


DTS_E_TXSCD_INVALIDINP 
UTCOLUMNTYPE 


DTS_E_TXSCD_CANNOTMA 
PDIFFERENTTYPES 


DESCRIPTION 


The "%3" property is 
required on input column 
"261" (%2Id!), but is not 
found. The missing 
property should be added. 


The "%1" is marked read- 
only, but is not referenced 
by any other column. 
Unreferenced columns are 
not allowed. 


The "%1" references column 
ID %2!d!, and that column 
is not found on the input. A 
reference points to a 
nonexistent column. 


The "%1" references "%2", 
and that column is not of a 
BLOB type. 


The "%1" references output 
column ID %2!d!, and that 
column is not found on the 
output. 


Reading from the file "%1" 
failed with error code 
0x%2!8.8X!. 


There must be at least one 
column of Fixed, Changing, 
or Historical type on the 
input of a Slowly Changing 
Dimension transform. Verify 
that at least one >column is 
a FixedAttribute, 
ChangingAttribute, or 
HistoricalAttribute. 


The ColumntType property 
of "%1" is not valid. The 
current value is outside the 
range of acceptable values. 


The input column "%1" 
cannot be mapped to 
external column "%2" 
because they have different 
data types. The Slowly 
Changing Dimension 
transform does not >allow 
mapping between column 
of different types except for 
DT_STR and DT_WSTR. 


HEXADECIMAL CODE 


0xC020802E 


0xC020802F 


0xC0208030 


0xC0208031 


0xC0208032 


0xC0208033 


0xC0208034 


0xC0208035 


DECIMAL CODE 


-1071611858 


-1071611857 


-1071611856 


-1071611855 


-1071611854 


-1071611853 


-1071611852 


-1071611851 


SYMBOLIC NAME 


DTS_E_NTEXTDATATYPENOT 
SUPPORTEDWITHANSIFILES 


DTS_E_TEXTDATATYPENOTS 
UPPORTEDWITHUNICODEF 
ILES 


DTS_E_IMAGEDATATYPENO 
TSUPPORTED 


DTS_E_FLATFILEFORMATNO 
TSUPPORTED 


DTS_E_EXTRACTORFILENAM 
ECOLUMNNOTSTRING 


DTS_E_EXTRACTORCANTAP 
PENDTRUNCATE 


DTS_E_EXTRACTORCOLUM 
NALREADYREFERENCED 


DTS_E_CONNECTIONMANA 
NGERNOTASSIGNED 


DESCRIPTION 


The data type for "%1" is 
DT_NTEXT, which is not 
supported with ANSI files. 
Use DT_TEXT instead and 
convert the data to 
DT_NTEXT using the data 
>conversion component. 


The data type for "%1" is 
DT_TEXT, which is not 
supported with Unicode 
files. Use DT_NTEXT instead 
and convert the data to 
DT_TEXT using the data 
>conversion component. 


The data type for "%1" is 
DT_IMAGE, which is not 
supported. Use DT_TEXT or 
DT_NTEXT instead and 
convert the data from, or 
to, DT_IMAGE using the 
data conversion 
>component. 


Format "%1" is not 
supported by Flat File 
Connection Manager. 
Supported formats are 
Delimited, FixedWidth, 
RaggedRight, and Mixed. 


The "%1" should contain a 
file name, but it is not of a 
String type. 


Error caused by conflicting 
property settings. The "%1" 
has both the AllowAppend 
property and the 
ForceTruncate property set 
to TRUE. Both properties 
cannot >be set to TRUE. Set 
one of the two properties 
to FALSE. 


The %1 references column 
ID %2!d!, but that column is 
already referenced by %3. 
Remove one of the two 
reference to the column. 


A connection manager has 
not been assigned to the 
%1. 


HEXADECIMAL CODE 


0xC0208036 


0xC0208037 


0xC0208038 


0xC0208039 


0xC020803A 


0xC020803B 


0xC020803C 


DECIMAL CODE 


-1071611850 


-1071611849 


-1071611848 


-1071611847 


-1071611846 


-1071611845 


-1071611844 


SYMBOLIC NAME 


DTS_E_INSERTERCOLUMNA 
LREADY REFERENCED 


DTS_E_INSERTERCOLUMNN 
OTREFERENCED 


DTS_E_INSERTERDATACOLU 
MNNOTBLOB 


DTS_E_INSERTERFILENAME 
COLUMNNOTSTRING 


DTS_E_INSERTEREXPECTBO 
MINVALIDTYPE 


DTS_E_INSERTERINVALIDDA 
TACOLUMNSETTYPE 


DTS_E_TXSCD_FIXEDATTRIB 
UTECHANGE 


DESCRIPTION 


The %1 references the 
output column with ID 
%2!'d!, but that column is 
already referenced by %3. 


The "%1" is not referenced 
by any input column. Each 
output column must be 
referenced by exactly one 
input column. 


The "%1" references "%2", 
and that column is not the 
correct type. It must be 
DT_TEXT, DT_NTEXT, or 
DT_IMAGE. A reference 
points to a column that 
must be a BLOB.> 


The "%1" should contain a 
file name, but it is not a 
String type. 


The "%1" has the 
ExpectBOM property set to 
TRUE for %2, but the 
column is not NT_NTEXT. 
The ExpectBOM specifies 
that the Import Column 
transformation expects >a 
byte-order mark (BOM). 
Either set the ExpectBOM 
property to false or change 
the output column data 
type to DT_NTEXT. 


Data output columns must 
be DT_TEXT, DT_NTEXT, or 
DT_IMAGE. The data output 
column may only be set to 
a BLOB type. 


If the 
FailOnFixedAttributeChange 
property is set to TRUE, the 
transformation will fail when 
a fixed attribute change is 
detected. To send rows to 
the Fixed >Attribute 
output, set the 
FailOnFixedAttributeChange 
property to FALSE. 


HEXADECIMAL CODE 


0xC020803D 


0xC020803E 


0xC020803F 


0xC0208040 


0xC0208107 


0xC0208108 


0xC0208201 


0xC0208202 


0xC0208203 


0xC0208204 


0xC0208205 


0xC0208206 


0xC0208207 


DECIMAL CODE 


-1071611843 


-1071611842 


-1071611841 


-1071611840 


-1071611641 


-1071611640 


-1071611391 


-1071611390 


-1071611389 


-1071611388 


-1071611387 


-1071611386 


-1071611385 


SYMBOLIC NAME 


DTS_E_TXSCD_LOOKUPFAIL 
URE 


DTS_E_TXSCD_INVALIDNU 
MBERSOFPARAMETERS 


DTS_E_TXSCD_CANNOTFIN 
DEXTERNALCOLUMN 


DTS_E_TXSCD_INFFEREDIN 
DICATORNOTBOOL 


DTS_E_ERRORROWDISPMU 
STBENOTUSED 


DTS_E_TRUNCROWDISPMU 
STBENOTUSED 


DTS_E_TXAGG_INPUTNOTF 
OUNDFOROUTPUT 


DTS_E_TXAGG_INVALIDOUT 
PUTDATATYPEFORAGGREG 
ATE 


DTS_E_TXAGG_INVALIDINP 
UTDATATYPEFORAGGREGA 
TE 


DTS_E_TXAGG_INPUTOUTP 
UTDATATYPEMISMATCH 


DTS_E_UNABLETOGETINPU 
TBUFFERHANDLE 


DTS_E_UNABLETOGETOUTP 
UTBUFFERHANDLE 


DTS_E_UNABLETOFINDCOL 
UMNHANDLEINOUTPUTBU 
FFER 


DESCRIPTION 


The Lookup transformation 
failed to retrieve any rows. 
The transform fails when 
the FailOnLookupFailure is 
set to TRUE and no rows 
are retrieved. 


There must be at least one 
column type of Key on the 
input of a Slowly Changing 
Dimension transformation. 
Set at least one column 
type to Key. 


Cannot find external 
column with name "%1". 


Inferred indicator column 
"%1" must be of type 
DT_BOOL. 


The %1 must have its error 
row disposition value set to 
RD_NotUsed. 


The %1 must have its 
truncation row disposition 
value set to RD_NotUsed. 


Cannot find input column 
with lineage ID %1!d! 
needed by output column 
with ID %2!dl. 


Invalid output data type for 
aggregate type specified at 
output column ID %1!d!. 


Invalid input data type for 
%1 used for the specified 
aggregate at %2. 


Data types of input column 
lineage ID %1!d! and 
output column ID %2!d! do 
not match. 


Cannot get input buffer 
handle for input ID %1!d!. 


Cannot get output buffer 
handle for output ID %1!d!. 


Cannot find column with 
lineage ID %1!d! in output 
buffer. 


HEXADECIMAL CODE 


0xC0208208 


0xC0208209 


0xC020820A 


0xC020820B 


0xC020820D 


0xC020820E 


0xC020820F 


0xC0208210 


0xC0208211 


0xC0208212 


0xC0208213 


DECIMAL CODE 


-1071611384 


-1071611383 


-1071611382 


-1071611381 


-1071611379 


-1071611378 


-1071611377 


-1071611376 


-1071611375 


-1071611374 


-1071611373 


SYMBOLIC NAME 


DTS_E_UNABLETOFINDCOL 
UMNHANDLEININPUTBUFF 
ER 


DTS_E_CANNOTHAVEZERO 
OUTPUTCOLUMNS 


DTS_E_CONNECTIONMANA 
GERCOLUMNCOUNTMISM 
ATCH 


DTS_E_MISMATCHCONNEC 
TIONMANAGERCOLUMN 


DTS_E_EXTERNALMETADAT 
ACOLUMNISALREADY MAP 
PED 


DTS_E_TXAGG_STRING_TOO 
_LONG 


DTS_E_DERIVEDRESULT_TO 
O_LONG 


DTS_E_TXAGG_MEMALLOC 
ERROUTPUTDESCRIPTORS 


DTS_E_TXAGG_MEMALLOC 
ERRWORKSPACEDESCRIPTO 
RS 


DTS_E_TXAGG_MEMALLOC 
ERRSORTORDERDESCRIPTO 
RS 


DTS_E_TXAGG_MEMALLOC 
ERRNUMERICDESCRIPTORS 


DESCRIPTION 


Cannot find column with 
lineage ID %1!d! in input 
buffer. 


The number of output 
columns for %1 cannot be 
zero. 


The number of columns in 
the flat file connection 
manager must be the same 
as the number of columns 
in the flat file adapter. The 
number of columns >for 
the flat file connection 
manager is %1!d!, while the 
number of columns for the 
flat file adapter is %2!dl. 


The column "%1" at index 
%2!'d! in the flat file 
connection manager was 
not found at index %3!d! in 
the column collection of the 
flat file adapter. 


The external metadata 
column with ID %1!d! has 
already been mapped to 
%2. 


The transform encountered 
a key column that was 
larger than %1!u! 
characters. 


The transform encountered 
a result value that was 
longer than %1!u! bytes. 


Unable to allocate memory. 


Unable to allocate memory. 


Unable to allocate memory. 


Unable to allocate memory. 


HEXADECIMAL CODE 


0xC0208214 


0xC0208215 


0xC0208216 


0xC0208217 


0xC0208218 


0xC0208219 


0xC020821A 


0xC020821B 


0xC020821E 


0xC020821F 


0xC0208220 


0xC0208221 


0xC0208222 


DECIMAL CODE 


-1071611372 


-1071611371 


-1071611370 


-1071611369 


-1071611368 


-1071611367 


-1071611366 


-1071611365 


-1071611362 


-1071611361 


-1071611360 


-1071611359 


-1071611358 


SYMBOLIC NAME 


DTS_E_TXAGG_MEMALLOC 
ERRCOUNTDISTINCTDESCR 
IPTOR 


DTS_E_TXAGG_MEMALLOC 
ERRWORKSPACESORTORDE 
RDESCRIPTORS 


DTS_E_TXAGG_MEMALLOC 
ERRWORKSPACENUMERIC 
DESCRIPTORS 


DTS_E_TXAGG_MEMALLOC 
ERRWORKSPACEBUFFCOLS 


DTS_E_UNREFERENCEDINP 
UTCOLUMN 


DTS_E_CANTBUILDTHREAD 
POOL 


DTS_E_QUEUEWORKITEMF 
AILED 


DTS_E_SORTTHREADSTOPP 
ED 


DTS_E_SORTBADTHREADCO 
UNT 


DTS_E_DTPXMLLOADFAILU 
RE 


DTS_E_DTPXMLSAVEFAILUR 
E 


DTS_E_DTPXMLINT32CONV 
ERTERR 


DTS_E_DTPXMLBOOLCONV 
ERTERR 


DESCRIPTION 


Unable to allocate memory. 


Unable to allocate memory. 


Unable to allocate memory. 


Unable to allocate memory. 


The input column "%1" is 
not referenced. 


The Sort transformation 
could not create a thread 
pool with %1!d! threads. 
Not enough memory is 
available. 


The Sort transformation 
cannot queue a work item 
to its thread pool. There is 
not enough memory 
available. 


A worker thread in the Sort 
transformation stopped 
with error code 0x%1!8.8X!. 
A catastrophic error was 
encountered while sorting a 
buffer. 


MaxThreads was %1!Id!, 
and should be between 1 
and %2!Id!, inclusive or -1 
to default to the number of 
CPUs. 


Unable to load from XML. 


Unable to save to XML. 


Unable to convert the value 
"%1" to an integer. 


Unable to convert the value 
"%1" to a Boolean. 


HEXADECIMAL CODE 


0xC0208223 


0xC0208226 


0xC0208228 


0xC0208229 


0xC020822A 


0xC020822B 


0xC020822D 


0xC020822E 


0xC0208230 


0xC0208231 


0xC0208232 


0xC0208233 


0xC0208234 


DECIMAL CODE 


-1071611357 


-1071611354 


-1071611352 


-1071611351 


-1071611350 


-1071611349 


-1071611347 


-1071611346 


-1071611344 


-1071611343 


-1071611342 


-1071611341 


-1071611340 


SYMBOLIC NAME 


DTS_E_DTPXMLPARSEERRO 
RNEARID 


DTS_E_DTPXMLPROPERTYT 
YPEERR 


DTS_E_DTPXMLSETUSAGETY 
PEERR 


DTS_E_DTPXMLDATATYPEER 
R 


DTS_E_UNMAPPEDINPUTC 
OLUMN 


DTS_E_INPUTCOLUMNBAD 
MAP 


DTS_E_MULTIPLYMAPPEDO 
UTCOL 


DTS_E_TXAGG_STRINGPRO 
MOTIONFAILED 


DTS_E_DTPXMLIDLOOKUPE 
RR 


DTS_E_DTPXMLINVALIDXM 
LPERSISTPROPERTY 


DTS_E_DTPXMLPROPERTYST 
ATEERR 


DTS_E_CANTGETCUSTOMPR 
OPERTY 


DTS_E_UNABLETOLOCATEIN 
PUTCOLUMNID 


DESCRIPTION 


Load error encountered 
near object with ID %1!d!. 


The value "%1" is not valid 
for the attribute "%2". 


The value "%1" is not valid 
for the attribute "%2". 


The value "%1" is not valid 
for the attribute "%2". 


The %1 is not mapped to 
an output column. 


The %1 has a mapping that 
is not valid. An output 
column with an ID of %2!!Id! 
does not exist on this 
component. 


The %1 is mapped to an 
output column that already 
has a mapping on this 
input. 


Could not convert input 
column with Lineage ID 
%1'!Id! to DT_WSTR due to 
error 0x%2!8.8X!. 


Referenced object with ID 
%1!d! not found in package. 


Cannot read a persistence 
property required for the 
pipelinexml module. The 
property was not provided 
by the pipeline. 


The value "%1" is not valid 
for the attribute "%2". 


Cannot retrieve custom 
property "%1". 


An input column with the 
lineage ID %1!d!, referenced 
in the ParameterMap 
custom property with the 
parameter on position 
number %2!d!, cannot be 
found in the >input 
columns collection. 


HEXADECIMAL CODE 


0xC0208235 


0xC0208236 


0xC0208237 


0xC0208238 


0xC0208239 


0xC020823A 


0xC020823B 


0xC020823C 


0xC020823D 


0xC020823E 


0xC020823F 


DECIMAL CODE 


-1071611339 


-1071611338 


-1071611337 


-1071611336 


-1071611335 


-1071611334 


-1071611333 


-1071611332 


-1071611331 


-1071611330 


-1071611329 


SYMBOLIC NAME 


DTS_E_TXLOOKUP_UNABLE 
TOLOCATEREFCOLUMN 


DTS_E_TXLOOKUP_INCOMP 
ATIBLEDATATYPES 


DTS_E_TXLOOKUP_PARAM 
METADATAMISMATCH 


DTS_E_TXLOOKUP_INCORR 
ECTNUMOFPARAMETERS 


DTS_E_TXLOOKUP_INVALID 
JOINTYPE 


DTS_E_TXLOOKUP_INVALID 
COPYTYPE 


DTS_E_INSERTERINVALIDCO 
LUMNDATATY PE 


DTS_E_EXTRACTORINVALID 
COLUMNDATATYPE 


DTS_E_TXCHARMAPINVALI 
DCOLUMNDATATYPE 


DTS_E_SORTCANTCREATEEV 
ENT 


DTS_E_SORTCANTCREATETH 
READ 


DESCRIPTION 


Unable to locate reference 
column "%1". 


%1 and reference column 
named "%2" have 
incompatible data types. 


The parameterized SQL 
statement yields metadata 
which does not match the 
main SQL statement. 


The parameterized SQL 
statement contains an 
incorrect number of 
parameters. Expected %1!d!, 
but found %2!dl. 


%1 has a datatype which 
cannot be joined on. 


%1 has a datatype which 
cannot be copied. 


The %1 has an 
unsupported datatype. It 
must be DT_STR or 
DT_WSTR. 


The %1 has an 
unsupported datatype. It 
must be DT_STR, DT_WSTR, 
DT_TEXT, DT_NTEXT, or 
DT_IMAGE. 


The %1 has an 
unsupported datatype. It 
must be DT_STR, DT_WSTR, 
DT_TEXT, or DT_NTEXT. 


The Sort transformation 
cannot create an event to 
communicate with its 
worker threads. Not 
enough system handles are 
available to the Sort 
transformation. 


The Sort transformation 
cannot create a worker 
thread. Not enough 
memory is available to Sort 
transformation. 


HEXADECIMAL CODE 


0xC0208240 


0xC0208242 


0xC0208243 


0xC0208244 


0xC0208245 


0xC0208246 


0xC0208247 


0xC0208248 


0xC0208249 


0xC020824A 


0xC020824B 


0xC020824C 


DECIMAL CODE 


-1071611328 


-1071611326 


-1071611325 


-1071611324 


-1071611323 


-1071611322 


-1071611321 


-1071611320 


-1071611319 


-1071611318 


-1071611317 


-1071611316 


SYMBOLIC NAME 


DTS_E_SORTCANTCOMPARE 


DTS_E_TXLOOKUP_TOOFEW 
REFERENCECOLUMNS 


DTS_E_TXLOOKUP_MALLOC 
ERR_REFERENCECOLUMNI 
NFO 


DTS_E_TXLOOKUP_MALLOC 
ERR_REFERENCECOLUMNP 
AIR 


DTS_E_TXLOOKUP_MALLOC 
ERR_BUFFCOL 


DTS_E_TXLOOKUP_MAINW 
ORKSPACE_CREATEERR 


DTS_E_TXLOOKUP_HASHTA 
BLE_MALLOCERR 


DTS_E_TXLOOKUP_HASHN 
ODEHEAP_CREATEERR 


DTS_E_TXLOOKUP_HASHN 
ODEHEAP_MALLOCERR 


DTS_E_TXLOOKUP_LRUNO 
DEHEAP_CREATEERR 


DTS_E_TXLOOKUP_LRUNO 
DEHEAP_MALLOCERR 


DTS_E_TXLOOKUP_OLEDBE 
RR_LOADCOLUMNMETADA 
TA 


DESCRIPTION 


The Sort transformation 
failed to compare row %1!d! 
in buffer ID %2!d! to row 
%3!d! in buffer ID %4!d!. 


The Lookup transformation 
reference metadata 
contains too few columns. 
Check the SQLCommand 
property. The SELECT 
statement must return at 
least one column.> 


Unable to allocate memory 
for an array of Columninfo 
structures. 


Could not allocate memory 
for an array of ColumnPair 
structures. 


Unable to allocate memory 
for an array of BUFFCOL 
structures for the creation 
of a main workspace. 


Unable to create a main 
workspace buffer. 


Unable to allocate memory 
for hash table. 


Unable to allocate memory 
to create a heap for hash 
nodes. 


Unable to allocate memory 
for a hash node heap. 


Unable to create a heap for 
LRU nodes. An out-of 
memory condition 
occurred. 


Unable to allocate memory 
for the LRU node heap. An 
out-of-memory condition 
occurred. 


OLE DB error occurred 
while loading column 
metadata. Check 
SQLCommand and 
SqlCommandParam 
properties. 


HEXADECIMAL CODE 


0xC020824D 


0xC020824E 


0xC020824F 


0xC0208250 


0xC0208251 


0xC0208252 


0xC0208253 


0xC0208254 


0xC0208255 


0xC0208256 


DECIMAL CODE 


-1071611315 


-1071611314 


-1071611313 


-1071611312 


-1071611311 


-1071611310 


-1071611309 


-1071611308 


-1071611307 


-1071611306 


SYMBOLIC NAME 


DTS_E_TXLOOKUP_OLEDBE 
RR_GETIROWSET 


DTS_E_TXLOOKUP_OLEDBE 
RR_FILLBUFFER 


DTS_E_TXLOOKUP_OLEDBE 
RR_BINDPARAMETERS 


DTS_E_TXLOOKUP_OLEDBE 
RR_CREATEBINDING 


DTS_E_TXLOOKUP_INVALID 
_CASE 


DTS_E_TXLOOKUP_MAINW 
ORKSPACE_MALLOCERR 


DTS_E_TXLOOKUP_OLEDBE 
RR_GETPARAMIROWSET 


DTS_E_TXLOOKUP_OLEDBE 
RR_GETPARAMSINGLEROW 


DTS_E_TXAGG_MAINWORK 
SPACE_MALLOCERR 


DTS_E_TXAGG_MAINWORK 
SPACE_CREATEERR 


DESCRIPTION 


OLE DB error occurred 
while fetching rowset. 
Check SQLCommand and 
SqlCommandParam 
properties. 


OLE DB error occurred 
while populating internal 
cache. Check SQLCommand 
and SqlCommandParam 
properties. 


OLE DB error occurred 
while binding parameters. 
Check SQLCommand and 
SqlCommandParam 
properties. 


OLE DB error occurred 
while creating bindings. 
Check SQLCommand and 
SqlCommandParam 
properties. 


An invalid case was 
encountered in a switch 
statement during runtime. 


Unable to allocate memory 
for a new row for the main 
workspace buffer. An out- 
of-memory condition 
occurred. 


OLE DB error occurred 
while fetching 
parameterized rowset. 
Check SQLCommand and 
SqlCommandParam 
properties. 


OLE DB error occurred 
while fetching 
parameterized row. Check 
SQLCommand and 
SqlCommandParam 
properties. 


Unable to allocate memory 
for a new row for the main 
workspace buffer. An out- 
of-memory condition 
occurred. 


Unable to create a main 
workspace buffer. 


HEXADECIMAL CODE 


0xC0208257 


0xC0208258 


0xC0208259 


0xC020825A 


0xC020825B 


0xC020825C 


0xC020825D 


0xC020825E 


0xC020825F 


0xC0208260 


0xC0208261 


0xC0208262 


DECIMAL CODE 


-1071611305 


-1071611304 


-1071611303 


-1071611302 


-1071611301 


-1071611300 


-1071611299 


-1071611298 


-1071611297 


-1071611296 


-1071611295 


-1071611294 


SYMBOLIC NAME 


DTS_E_TXAGG_HASHTABLE_ 
MALLOCERR 


DTS_E_TXAGG_HASHNODE 
HEAP_CREATEERR 


DTS_E_TXAGG_HASHNODE 
HEAP_MALLOCERR 


DTS_E_TXAGG_CDNODEHE 
AP_CREATEERR 


DTS_E_TXAGG_CDNODEHE 
AP_MALLOCERR 


DTS_E_TXAGG_CDCHAINHE 
AP_CREATEERR 


DTS_E_TXAGG_CDHASHTAB 
LE_CREATEERR 


DTS_E_TXAGG_CDWORKSP 
ACE_MALLOCERR 


DTS_E_TXAGG_CDWORKSP 
ACE_CREATEERR 


DTS_E_TXAGG_CDCOLLASS 
EARRAY_MALLOCERR 


DTS_E_TXAGG_CDCHAINHE 
AP_MALLOCERR 


DTS_E_TXCOPYMAP_MISM 
ATCHED_COLUMN_METAD 
ATA 


DESCRIPTION 


Unable to allocate memory 
for the hash table. 


Unable to allocate memory 
to create a heap for the 
hash nodes. 


Unable to allocate memory 
for the hash node heap. 


Unable to allocate memory 
to create a heap for 
CountDistinct nodes. 


Unable to allocate memory 
for CountDistinct node 
heap. 


Unable to allocate memory 
to create a heap for 
CountDistinct chains. 


Unable to allocate memory 
for CountDistinct hash 
table. 


Unable to allocate memory 
for a new row for the 
CountDistinct workspace 
buffer. 


Unable to create a 
CountDistinct workspace 
buffer. 


Unable to allocate memory 
for CountDistinct Collapse 
array. 


Unable to allocate memory 
for CountDistinct chains. 


Columns with lineage IDs 
%1!d! and %2!d! have 
mismatched metadata. The 
input column that is 
mapped to an output 
column for copymap does 
not have the >same 
metadata (datatype, 
precision, scale, length, or 
codepage). 


HEXADECIMAL CODE 


0xC0208263 


0xC0208265 


0xC0208266 


0xC0208267 


0xC0208273 


0xC0208274 


0xC0208275 


0xC0208276 


0xC0208277 


0xC0208278 


0xC0208279 


0xC0208280 


0xC0208281 


DECIMAL CODE 


-1071611293 


-1071611291 


-1071611290 


-1071611289 


-1071611277 


-1071611276 


-1071611275 


-1071611274 


-1071611273 


-1071611272 


-1071611271 


-1071611264 


-1071611263 


SYMBOLIC NAME 


DTS_E_TXCOPYMAP_INCOR 
RECT_OUTPUT_COLUMN_ 
MAPPING 


DTS_E_CANTGETBLOBDATA 


DTS_E_CANTADDBLOBDATA 


DTS_E_MCASTOUTPUTCOL 
UMNS 


DTS_E_UNABLETOGETLOCA 
LIZEDRESOURCE 


DTS_E_DTPXMLEVENTSCAC 
HEERR 


DTS_E_DTPXMLPATHLOADE 
RR 


DTS_E_DTPXMLINPUTLOAD 
ERR 


DTS_E_DTPXMLOUTPUTLOA 
DERR 


DTS_E_DTPXMLINPUTCOLU 
MNLOADERR 


DTS_E_DTPXMLOUTPUTCOL 
UMNLOADERR 


DTS_E_DTPXMLPROPERTYL 
OADERR 


DTS_E_DTPXMLCONNECTIO 
NLOADERR 


DESCRIPTION 


The output column with 
lineage ID "%1!d!" is 
incorrectly mapped to an 
input column. The 
CopyColumnld property of 
the output column is not 

> correct. 


Failed to retrieve long data 
for column "%1". 


Long data was retrieved for 
a column but cannot be 
added to the Data Flow 
task buffer. 


Output "%1" (%2!d!) has 
output columns, but 
multicast outputs do not 
declare columns. The 
package is damaged. 


Unable to load a localized 
resource ID %1!d!. Verify 
that the RLL file is present. 


Cannot acquire Events 
Interface. An invalid Events 
interface was passed to the 
data flow module for 
persisting to XML. 


An error occurred while 
setting a path object during 
XML load. 


Error setting input object 
during XML load. 


Error setting output object 
during XML load. 


Error setting input column 
object during XML load. 


Error setting output column 
object during XML load. 


Error setting property 
object during XML load. 


Error setting connection 
object during XML load. 


HEXADECIMAL CODE 


0xC0208282 


0xC0208283 


0xC0208284 


0xC0208285 


0xC0208286 


0xC0208287 


0xC0208288 


0xC0208289 


0xC020828A 


0xC020828B 


DECIMAL CODE 


-1071611262 


-1071611261 


-1071611260 


-1071611259 


-1071611258 


-1071611257 


-1071611256 


-1071611255 


-1071611254 


-1071611253 


SYMBOLIC NAME 


DTS_E_FG_MISSING_OUTPU 
T.COLUMNS 


DTS_E_FG_PREPARE_TABLES 
_AND_ACCESSORS 


DTS_E_FG_COPY_INPUT 


DTS_E_FG_GENERATE_GRO 


UPS 


DTS_E_FG_LEADING_TRAILI 


NG 


DTS_E_FG_PICK_CANONICA 
L 


DTS_E_FG_NOBLOBS 


DTS_E_FG_FUZZY_MATCH_ 
ON_NONSTRING 


DTS_E_FUZZYGROUPINGIN 
TERNALPIPELINEERROR 


DTS_E_CODE_PAGE_NOT_S 
UPPORTED 


DESCRIPTION 


Special transformation- 
specific columns are either 
missing or have incorrect 


types. 


Fuzzy Grouping 
transformation failed to 
create required tables and 
accessors. 


Fuzzy Grouping 
transformation failed to 
copy input. 


Fuzzy Grouping 
transformation failed to 
generate groups. 


An unexpected error 
occurred in Fuzzy Grouping 
when applying the settings 
of property '%1'. 


The Fuzzy Grouping 
transformation failed to pick 
a canonical row of data to 
use in standardizing the 
data. 


Fuzzy Grouping does not 
support input columns of 
type IMAGE, TEXT, or 
NTEXT. 


A fuzzy match is specified 
on column "%1" (%2!d!) 
that is not a data type of 
DT_STR or DT_WSTR. 


A Fuzzy Grouping 
transformation pipeline 
error occurred and returned 
error code 0x%1!8.8X!: 
"%2". 


The code page %1!d! 
specified on column "%2" 
(%3!d!) is not supported. 
You must first convert this 
column to DT_WSTR which 
can be done by inserting a 
Data >Conversion 
Transform before this one. 


HEXADECIMAL CODE 


0xC0208294 


0xC0208296 


0xC02082F9 


OxC02082FA 


0xC02082FB 


OxC02082FC 


0xC02082FD 


OxC02082FE 


0xC02082FF 


0xC0208300 


0xC0208301 


DECIMAL CODE 


-1071611244 


-1071611242 


-1071611143 


-1071611142 


-1071611141 


-1071611140 


-1071611139 


-1071611138 


-1071611137 


-1071611136 


-1071611135 


SYMBOLIC NAME 


DTS_E_SETEODFAILED 


DTS_E_CANTCLONE 


DTS_E_TXCHARMAP_CANTK 
ATAKANAHIRAGANA 


DTS_E_TXCHARMAP_CANTS 
IMPLECOMPLEX 


DTS_E_TXCHARMAP_CANTF 
ULLHALF 


DTS_E_TXCHARMAP_CANTC 
HINAJAPAN 


DTS_E_TXCHARMAP_CANTC 
ASECHINESE 


DTS_E_TXCHARMAP_CANTC 
ASEJAPANESE 


DTS_E_TXCHARMAP_CANTB 
OTHCASE 


DTS_E_TXCHARMAP_CANTL 
INGUISTIC 


DTS_E_TXCHARMAP_INVALI 
DMAPFLAGANDDATATY PE 


DESCRIPTION 


Failure encountered while 
setting end of data flag for 
the buffer driving output 
"61" (%2!Idl). 


The input buffer could not 
be cloned. An out-of 
memory condition occurred 
or there was an internal 
error. 


Column "%1" requests that 
Katakana and Hiragana 
characters be produced at 
the same time. 


Column "%1" requests that 
Simple Chinese and 
Traditional Chinese 
characters be produced at 
the same time. 


Column "%1" requests 

operations to generate 
both full width and half 
width characters. 


Column "%1" combines 
operations on Japanese 
characters with operations 
for Chinese characters. 


Column "%1" combines 
operations on Chinese 
characters with uppercase 
and lowercase operations. 


Column "%1" combines 
operations on Japanese 
characters with uppercase 
and lowercase operations. 


Column "%1" maps the 
column to both uppercase 
and lowercase. 


Column "%1" combines 
flags other than uppercase 
and lowercase with the 
linguistic casing operation. 


The data type of column 
"%1" cannot be mapped as 
specified. 


HEXADECIMAL CODE 


0xC0208302 


0xC0208303 


0xC0208304 


0xC0208305 


0xC0208306 


0xC0208307 


DECIMAL CODE 


-1071611134 


-1071611133 


-1071611132 


-1071611131 


-1071611130 


-1071611129 


SYMBOLIC NAME 


DTS_E_TXFUZZYLOOKUP_U 
NSUPPORTED_MATCH_IND 
EX_VERSION 


DTS_E_TXFUZZYLOOKUP_IN 
VALID_MATCH_INDEX 


DTS_E_TXFUZZYLOOKUP_U 
NABLE_TO_READ_MATCH_I 
NDEX 


DTS_E_TXFUZZYLOOKUP_N 
O_JOIN_COLUMNS 


DTS_E_TXFUZZYLOOKUP_IN 
DEX_DOES_NOT_CONTAIN_ 
COLUMN 


DTS_E_TXFUZZYLOOKUP_ID 
ENTIFIER_PROPERTY 


DESCRIPTION 


The version (%1) of the pre- 
existing match index "%2" is 
not supported. The version 
expected is "%3". This error 
occurs if the version 

> persisted in the index 
metadata does not match 
the version which the 
current code was built for. 
Fix the error by rebuilding 
the index with the current 
version of the code. 


The table "%1" does not 
appear to be a valid pre- 
built match index. This error 
occurs if the metadata 
record cannot be loaded 
from the specified >pre- 
built index. 


Unable to read specified 
pre-built match index "%1". 
OLEDB Error code: 
0x%2!8.8X!. 


There were no input 
columns with a valid join to 
a reference table column. 
Make sure that there is at 
least one join defined using 
the input column 

> properties 
JoinToReferenceColumn and 
JoinType. 


The specified pre-existing 
match index "%1" was not 
originally built with fuzzy 
match information for 
column "%2". It must be 
rebuilt to >include this 
information. This error 
occurs when the index was 
built with the column not 
being a fuzzy join column. 


The name "%1" given for 
property "%2" is not a valid 
SQL identifier name. This 
error occurs if the name for 
the property does not 
conform to the 
>specifications for a valid 
SQL identifier name. 


HEXADECIMAL CODE 


0xC0208309 


0xC020830A 


0xC020830B 


0xC020830C 


0xC020830D 


0xC020830E 


0xC020830F 


DECIMAL CODE 


-1071611127 


-1071611126 


-1071611125 


-1071611124 


-1071611123 


-1071611122 


-1071611121 


SYMBOLIC NAME 


DTS_E_TXFUZZYLOOKUP_M 
INSIMILARITY_INVALID 


DTS_E_TXFUZZYLOOKUP_IN 
VALID_PROPERTY_VALUE 


DTS_E_TXFUZZYLOOKUP_IN 
COMPATIBLE_FUZZY_JOIN_ 
DATATYPES 


DTS_E_TXFUZZYLOOKUP_IN 
COMPATIBLE_EXACT_JOIN_ 
DATATYPES 


DTS_E_TXFUZZYLOOKUP_IN 
COMPATIBLE_COPYCOLU 
MN_DATATYPES 


DTS_E_TXFUZZYLOOKUP_IN 
COMPATIBLE_PASSTHRUCO 
LUMN_DATATYPES 


DTS_E_TXFUZZYLOOKUP_U 
NABLETOLOCATEREFCOLU 
MN 


DESCRIPTION 


The MinSimilarity threshold 
property on the Fuzzy 
Lookup transformation 
must be a value greater 
than or equal to 0.0 but 
less than 1.0. 


The value "%1" for property 
"%2" is not valid. 


The fuzzy lookup specified 
between input column "%1" 
and reference column "%2" 
is not valid because fuzzy 
joins are only supported 
between >string columns, 
types DT_STR and DT_WSTR. 


The exact lookup columns, 
"%1" and "%2", do not have 
equal data types or are not 
comparable string types. 
Exact joins are supported 

> between columns with 
equal data types or a 
DT_STR and DT_WSTR 
combination. 


The copy columns, "%1" 
and "%2", do not have 
equal data types or are not 
trivially convertible string 
types. This occurs because 
copying >from reference to 
output between columns 
with equal data types, or a 
DT_STR and DT_WSTR 
combination, is supported, 
but other types are not. 


The passthrough columns, 
"%1" and "%2", do not have 
equal data types. Only 
columns with equal data 
types are supported as 
passthrough >columns 
from input to output. 


Cannot locate reference 
column "%1". 


HEXADECIMAL CODE 


0xC0208311 


0xC0208312 


0xC0208313 


0xC0208314 


0xC0208315 


0xC0208316 


DECIMAL CODE 


-1071611119 


-1071611118 


-1071611117 


-1071611116 


-1071611115 


-1071611114 


SYMBOLIC NAME 


DTS_E_TXFUZZYLOOKUP_O 
UTPUT_COLUMN_MUST_BE 
_PASSTHRU_COLUMN_OR_ 
A_COPY_COLUMN 


DTS_E_TXFUZZYLOOKUP_P 
ASSTHRU_COLUMN_NOT_F 
OUND 


DTS_E_TXFUZZYLOOKUP_IN 
DEXED_COLUMN_NOT_FO 
UND_IN_REF_TABLE 


DTS_E_TXFUZZYLOOKUP_T 
OKEN_TOO_LONG 


DTS_E_RAWMETADATAMIS 
MATCHTYPE 


DTS_E_RAWMETADATAMIS 
MATCHSIZE 


DESCRIPTION 


An output column must 
have exactly one 
CopyColumn or 
PassThruColumn property 
specified. This error occurs 
when >neither the 
CopyColumn or the 
PassThruColumn properties, 
or both the CopyColumn 
and PassThruColumn 
properties, are set to non- 
empty values. 


The source lineage id 
'%1!d!' specified for 
property '%2' on output 
column '%3' was not found 
in the input column 
collection. This occurs when 
the >input column id 
specified on an output 
column as a passthrough 
column is not found in the 
set of inputs. 


The column "%1" in the 
pre-built index "%2" was 
not found in the reference 
table/query. This happens if 
the schema/query of the 
>reference table has 
changed since the pre- 
existing match index was 
built. 


The component 
encountered a token that 
was larger than 
2147483647 characters. 


The output file cannot be 
appended. Column "%1" 
matches by name, but the 
column in the file has type 
%2 and the input column 
has type %3. The metadata 
for the >column does not 
match on data type. 


The output file cannot be 
appended. Column "%1" 
matches by name, but the 
column in the file has 
maximum length %2!d! and 
the input column has 
maximum length >%3!d!. 
The metadata for the 
column does not match in 
length. 


HEXADECIMAL CODE 


0xC0208317 


0xC0208318 


0xC0208319 


0xC020831A 


0xC020831B 


0xC020831D 


0xC020831E 


DECIMAL CODE 


-1071611113 


-1071611112 


-1071611111 


-1071611110 


-1071611109 


-1071611107 


-1071611106 


SYMBOLIC NAME 


DTS_E_RAWMETADATAMIS 
MATCHCODEPAGE 


DTS_E_RAWMETADATAMIS 
MATCHPRECISION 


DTS_E_RAWMETADATAMIS 
MATCHSCALE 


DTS_E_COULD_NOT_DETER 
MINE_DATASOURCE_DBMS 
NAME 


DTS_E_INCORRECT_SQL_SE 
RVER_VERSION 


DTS_E_CANTDELETEERROR 
COLUMNS 


DTS_E_UNEXPECTEDCOLU 
MNDATATY PE 


DESCRIPTION 


The output file cannot be 
appended. Column "%1" 
matches by name, but the 
column in the file has code 
page %2!d! and the input 
column has code page 
%3!d!. The >metadata for 
the named column does 
not match on code page. 


The output file cannot be 
appended. Column "%1" 
matches by name, but the 
column in the file has 
precision %2!d! and the 
input column has precision 
%3!d!. The >metadata for 
the named column does 
not match on precision. 


The output file cannot be 
appended. Column "%1" 
matches by name, but the 
column in the file has scale 
%2'd! and the input column 
has scale %3!d!. The 
metadata >for the named 
column does not match on 
scale. 


Unable to determine the 
DBMS name and version on 
"%1". This occurs if the 
IDBProperties on the 
connection did not return 
information needed to 
>verify the DBMS name 
and version. 


The DBMS type or version 
of "%1" is not supported. A 
connection to Microsoft 
SQL Server version 8.0 or 
later is required. This occurs 
if IDBProperties on >the 
connection did not return a 
the correct version. 


The %1 is a special error 
output column and cannot 
be deleted. 


The data type specified for 
column "%1" is not the 
expected type "%2". 


HEXADECIMAL CODE 


0xC020831F 


0xC0208320 


0xC0208322 


0xC0208323 


0xC0208324 


0xC0208325 


DECIMAL CODE 


-1071611105 


-1071611104 


-1071611102 


-1071611101 


-1071611100 


-1071611099 


SYMBOLIC NAME 


DTS_E_INPUTCOLUMNNOT 
FOUND 


DTS_E_TXGROUPDUPS_INP 
UTCOLUMNNOTJOINED 


DTS_E_TXFUZZYLOOKUP_R 
EF_TABLE_MISSING_IDENTI 
TY_INDEX 


DTS_E_TXFUZZYLOOKUP_R 
EF_CONTAINS_NON_INTEG 
ER_IDENT_COLUMN 


DTS_E_TXFUZZY_MATCHCO 
NTRIBUTION_AND_HIERAR 
CHY_SPECIFIED 


DTS_E_TXFUZZY_HIERARCH 
Y_INCORRECT 


DESCRIPTION 


The input column lineage ID 
"%1" referenced by 
property "%2" on output 
column "%3" could not be 
located in the input column 
collection. 


The input column "%1" 
referenced by the "%2" 
property on output column 
"%3" must have property 
ToBeCleaned=True and have 
a valid ExactFuzzy property 
>value, 


The reference table '%1' 
does not have a clustered 
index on an integer identity 
column, which is required if 
the property 'CopyRefTable’ 
is >set to FALSE. If 
CopyRefTable is false, the 
reference table must have a 
clustered index on an 
integer identity column. 


The reference table '%1' 
contains a non-integer type 
identity column which is not 
supported. Use a view of 
the table without the 
>column '%2'. This error 
occurs because when a 
copy is made of the 
reference table, an integer 
identity column is added, 
and only one identity 
column is allowed per table. 


Both MatchContribution 
and hierarchy information 
cannot be specified at the 
same time. This is not 
allowed because these 
properties are >both 
weighing factors for scoring. 


Levels in hierarchy should 
be unique numbers . Valid 
level in hierarchy values are 
integers greater than or 
equal to 1. The smaller the 
number is, the lower >the 
column is in the hierarchy. 
The default value is 0, 
indicating that the column 
is not part of a hierarchy. 
Overlaps and gaps are not 
allowed. 


HEXADECIMAL CODE 


0xC0208326 


0xC0208329 


0xC020832A 


0xC020832C 


0xC020832F 


0xC0208330 


0xC0208331 


0xC0208332 


0xC0208333 


0xC0208334 


0xC0208335 


0xC0208336 


0xC0208337 


DECIMAL CODE 


-1071611098 


-1071611095 


-1071611094 


-1071611092 


-1071611089 


-1071611088 


-1071611087 


-1071611086 


-1071611085 


-1071611084 


-1071611083 


-1071611082 


-1071611081 


SYMBOLIC NAME 


DTS_E_TXFUZZYGROUPING 
_INSUFFICIENT_FUZZY_JOI 
N_COLUMNS 


DTS_E_TXFUZZYLOOKUP_C 
OLUMNINVALID 


DTS_E_TXFUZZYLOOKUP_U 
NSUPPORTEDDATATY PE 


DTS_E_TXFUZZYLOOKUP_O 
UTPUTLENGTHMISMATCH 


DTS_E_TERMEXTRACTION | 
NCORRECTEXACTNUMBER 
OFINPUTCOLUMNS 


DTS_E_TERMEXTRACTION | 
NCORRECTEXACTNUMBER 
OFOUTPUTCOLUMNS 


DTS_E_TERMEXTRACTION | 
NCORRECTDATATYPEOFINP 
UTCOLUMN 


DTS_E_TERMEXTRACTION | 
NCORRECTDATATYPEOFOU 
TPUTCOLUMN 


DTS_E_TERMEXTRACTION | 
NCORRECTDATATYPEOFREF 
ERENCECOLUMN 


DTS_E_TERMEXTRACTION_ 
UNABLETOLOCATEREFCOL 
UMN 


DTS_E_TERMEXTRACTION | 
NCORRECTTERMTY PE 


DTS_E_TERMEXTRACTION | 
NCORRECTFREQUENCYTHR 
ESHOLD 


DTS_E_TERMEXTRACTION | 
NCORRECTMAXLENOFTER 
M 


DESCRIPTION 


No columns to fuzzy group 
on were defined. There 
must be at least one input 
column with column 
properties 
ToBeCleaned=true and 
>ExactFuzzy=2. 


The column with ID '%1!d!' 
was not valid for an 
undetermined reason. 


The data type of column 
'%1' is not supported. 


The length of output 
column '%1' is less than 
that of its source column 
'%2". 


There should be only one 
input column. 


There should be exactly two 
output columns. 


The input column can only 
have DT_WSTR or DT_NTEXT 
as its data type. 


The output column [%1!d!] 
can only have '%2' as its 
data type. 


The reference column can 
only have DT_STR or 
DT_WSTR as its data type. 


An error occurred while 
locating the reference 
column '%1'. 


The Term Type of the 
transformation can only be 
WordOnly, PhraseOnly or 
WordPhrase. 


The value of Frequency 
Threshold should not be 
lower than '%1!d!'. 


The value of Max Length of 
Term should not be lower 
than '%1!d!'. 


HEXADECIMAL CODE 


0xC0208338 


0xC0208339 


0xC020833A 


0xC020833B 


0xC020833C 


0xC020833D 


0xC020833E 


0xC020833F 


0xC0208340 


0xC0208341 


0xC0208342 


0xC0208343 


DECIMAL CODE 


-1071611080 


-1071611079 


-1071611078 


-1071611077 


-1071611076 


-1071611075 


-1071611074 


-1071611073 


-1071611072 


-1071611071 


-1071611070 


-1071611069 


SYMBOLIC NAME 


DTS_E_TERMEXTRACTION_T 
OOFEWREFERENCECOLUM 
NS 


DTS_E_TERMEXTRACTION_ 
MALLOCERR_REFERENCEC 
OLUMNINFO 


DTS_E_TERMEXTRACTION_ 
MAINWORKSPACE_CREATE 
ERR 


DTS_E_TERMEXTRACTION_ 
OLEDBERR_CREATEBINDIN 
G 


DTS_E_TERMEXTRACTION_ 
OLEDBERR_GETIROWSET 


DTS_E_TERMEXTRACTION_ 
OLEDBERR_FILLBUFFER 


DTS_E_TERMEXTRACTION_P 
ROCESSERR 


DTS_E_TERMEXTRACTIONO 
RLOOKUP_PROCESSERR_DE 
POSITFULL 


DTS_E_TERMEXTRACTION | 
NVALIDOUTTERMTABLEOR 
COLUMN 


DTS_E_TXFUZZYLOOKUP_ST 
RINGCOLUMNTOOLONG 


DTS_E_TERMEXTRACTION_ 
OUTTERMTABLEANDCOLU 
MNNOTSET 


DTS_E_TERMLOOKUP_TOOF 
EWOUTPUTCOLUMNS 


DESCRIPTION 


Term Extraction reference 
metadata contains too few 
columns. 


An error occurred while 
allocating memory. 


An error occurred while 
creating a workspace buffer. 


An OLEDB error occurred 
while creating bindings. 


An OLEDB error occurred 
while fetching rowsets. 


An OLEDB error occurred 
while populating internal 
cache. 


An error occurred while 
extracting terms on row 
%1'Id!, column %2!Id!. The 
error code returned was 
0x%3!8.8X!. Please remove 
it from the input as a work- 
around.> 


The number of the term 
candidates exceeds its limit, 
AG. 


The reference table, view, or 
column that is used for 
Exclusion Terms is not valid. 


The length of string column 
'%1' exceeds 4000 
characters. A conversion 
from DT_STR to DT_WSTR is 
necessary, so a truncation 
would occur. Either reduce 
>the column width or use 
only DT_WSTR column 


types. 


The reference table, view, or 
column to be used for an 
Exclusion Terms has not 
been set. 


Term Lookup contains too 
few output columns. 


HEXADECIMAL CODE 


0xC0208344 


0xC0208345 


0xC0208346 


0xC0208347 


0xC0208348 


0xC0208349 


0xC020834A 


0xC020834B 


0xC020834C 


0xC020834D 


0xC020834E 


0xC020834F 


DECIMAL CODE 


-1071611068 


-1071611067 


-1071611066 


-1071611065 


-1071611064 


-1071611063 


-1071611062 


-1071611061 


-1071611060 


-1071611059 


-1071611058 


-1071611057 


SYMBOLIC NAME 


DTS_E_TERMLOOKUP_INCO 
RRECTDATATYPEOFREFERE 
NCECOLUMN 


DTS_E_TERMLOOKUP_UNA 
BLETOLOCATEREFCOLUMN 


DTS_E_TERMLOOKUP_TOOF 
EWREFERENCECOLUMNS 


DTS_E_TERMEXTRACTIONO 
RLOOKUP_TESTOFFSETERR 
OR 


DTS_E_TERMLOOKUP_MAI 
NWORKSPACE_CREATEERR 


DTS_E_TERMLOOKUP_OLED 
BERR_CREATEBINDING 


DTS_E_TERMLOOKUP_OLED 
BERR_GETIROWSET 


DTS_E_TERMLOOKUP_OLED 
BERR_FILLBUFFER 


DTS_E_TERMLOOKUP_PRO 
CESSERR 


DTS_E_TERMLOOKUP_TEXTI 
DINPUTCOLUMNNOTMAP 
PEDWITHOUTPUTCOLUMN 


DTS_E_TERMLOOKUP_INCO 
RRECTEXACTNUMBEROFTE 
XTCOLUMNS 


DTS_E_TERMLOOKUP_TEXTI 
NPUTCOLUMNHAVEINCOR 
RECTDATATYPE 


DESCRIPTION 


The reference column can 
only have DT_STR or 
DT_WSTR as its data type. 


An error occurred while 
locating the reference 
column '%1'. 


Term Lookup reference 
metadata contains too few 
columns. 


An error occurred while 
normalizing words. 


An error occurred while 
creating a workspace buffer. 


An OLEDB error occurred 
while creating bindings. 


An OLEDB error occurred 
while fetching rowsets. 


An OLEDB error occurred 
while populating internal 
cache. 


An error occurred while 
looking up terms on row 
%1'Id!, column %2!Id!. The 
error code returned was 
0x%3!8.8X!. Please remove 
it from the input as a work- 
around. 


At least one Passthrough 
column is not mapped to 
an output column. 


There should be exactly one 
input column mapped to 
one reference column. 


The input column mapped 
to a reference column can 
only have DT_NTXT or 

DT_WSTR as its data type. 


HEXADECIMAL CODE 


0xC0208354 


0xC0208355 


0xC0208356 


0xC0208357 


0xC0208358 


0xC0208359 


0xC020835A 


0xC020835B 


DECIMAL CODE 


-1071611052 


-1071611051 


-1071611050 


-1071611049 


-1071611048 


-1071611047 


-1071611046 


-1071611045 


SYMBOLIC NAME 


DTS_E_TXFUZZYLOOKUP_IN 
VALID_MATCH_INDEX_NA 
ME 


DTS_E_TERMEXTRACTION_T 
ERMFILTERSTARTITERATION 
ERROR 


DTS_E_TERMEXTRACTION_E 
MPTYTERMRESULTERROR 


DTS_E_TERMEXTRACTION_S 
TDLENGTHERROR 


DTS_E_TERMLOOKUP_SAVE 
WORDWITHPUNCTERROR 


DTS_E_TERMLOOKUP_ADD 
REFERENCETERM 


DTS_E_TERMLOOKUP_SORR 
EFERENCETERM 


DTS_E_TERMLOOKUP_COU 
NTTERM 


DESCRIPTION 


The reference table name 
"%1" is not a valid SQL 
identifier. This error occurs if 
the table name cannot be 
parsed from the input 
string. There may >be 
unquoted spaces in the 
name. Verify that the name 
is correctly quoted. 


An error occurred while the 
Term Filter was starting its 
iteration. 


An error occurred while 
reclaiming the buffer used 
for caching terms. The error 
code returned was 
0x%1!8.8X!. 


An std::length_error 
occurred from the STL 
containers. 


An error occurred while 
saving words with 
punctuation characters. The 
error code returned was 
0x%1!8.8X!. 


An error occurred while 
processing the %1!Id!th 
reference term. The error 
code returned was 
0x%2!8.8X!. Please remove 
the reference term from 
your reference >table as a 
work-around. 


An error occurred while 
sorting reference terms. The 
error code returned was 
0x%1!8.8X!. 


An error occurred while 
counting term candidates. 
The error code returned 
was 0x%1!8.8X!. 


HEXADECIMAL CODE 


0xC020835C 


0xC020835D 


0xC020835E 


0xC020835F 


0xC0208360 


0xC0208361 


0xC0208362 


0xC0208363 


DECIMAL CODE 


-1071611044 


-1071611043 


-1071611042 


-1071611041 


-1071611040 


-1071611039 


-1071611038 


-1071611037 


SYMBOLIC NAME 


DTS_E_FUZZYLOOKUP_REFE 
RENCECACHEFULL 


DTS_E_TERMLOOKUP_INITI 
ALIZE 


DTS_E_TERMLOOKUP_PRO 
CESSSENTENCE 


DTS_E_TEXTMININGBASE_A 
PPENDTOTEMPBUFFER 


DTS_E_TERMEXTRACTION_S 
AVEPOSTAG 


DTS_E_TERMEXTRACTION_C 
OUNTTERM 


DTS_E_TERMEXTRACTION | 
NITPOSPROCESSOR 


DTS_E_TERMEXTRACTION | 
NITFSA 


DESCRIPTION 


Fuzzy Lookup was unable 
to load the entire reference 
table into main memory as 
is required when the 
Exhaustive property is 
enabled. Either we ran out 
of >system memory or a 
limit was specified for 
MaxMemoryUsage which 
was not sufficient to load 
the reference table. Either 
set MaxMemoryUsage to 0 
or increase it significantly. 
Alternatively, disable 
Exhaustive. 


An error occurred while 
initializing the engine of 
Term Lookup. The error 
code returned was 
0x%1!8.8X!. 


An error occurred while 
processing sentences. The 
error code returned was 
0x%1!8.8X!. 


An error occurred while 
adding strings to an 
internal buffer. The error 
code returned was 
0x%1!8.8X!. 


An error occurred while 
saving part-of- speech tags 
from an internal buffer. The 
error code returned was 
0x%1!8.8X!. 


An error occurred while 
counting term candidates. 
The error code returned 
was 0x%1!8.8X!. 


An error occurred while 
initializing the part-of- 
speech processor. The error 
code returned was 
0x%1!8.8X!. 


An error occurred while 
loading the finite state 
automata. The error code 
returned was 0x%1!8.8X!. 


HEXADECIMAL CODE 


0xC0208364 


0xC0208365 


0xC0208366 


0xC0208367 


0xC0208368 


0xC0208369 


0xC020836A 


0xC020836B 


0xC020836C 


0xC020836D 


DECIMAL CODE 


-1071611036 


-1071611035 


-1071611034 


-1071611033 


-1071611032 


-1071611031 


-1071611030 


-1071611029 


-1071611028 


-1071611027 


SYMBOLIC NAME 


DTS_E_TERMEXTRACTION | 
NITIALIZE 


DTS_E_TERMEXTRACTION_P 
ROCESSSENTENCE 


DTS_E_TERMEXTRACTION | 
NITPOSTAGVECTOR 


DTS_E_TERMEXTRACTION_S 
AVEPTRSTRING 


DTS_E_TERMEXTRACTION_A 
DDWORDTODECODER 


DTS_E_TERMEXTRACTION_ 
DECODE 


DTS_E_TERMEXTRACTION_S 
ETEXCLUDEDTERM 


DTS_E_TERMEXTRACTION_P 
ROCESSDOCUMENT 


DTS_E_TEXTMININGBASE_T 
ESTPERIOD 


DTS_E_TERMLOOKUP_ENGI 
NEADDREFERENCETERM 


DESCRIPTION 


An error occurred while 
initializing the engine of 
Term Extraction. The error 
code returned was 
0x%1!8.8X!. 


An error occurred while 
processing within a 
sentence. The error code 
returned was 0x%1!8.8X!. 


An error occurred while 
initializing the part-of- 
speech processor. The error 
code returned was 
0x%1!8.8X!. 


An error occurred while 
adding strings to an 
internal buffer. The error 
code returned was 
0x%1!8.8X!. 


An error occurred while 
adding words to a statistical 
decoder. The error code 
returned was 0x%1!8.8X!. 


An error occurred while 
decoding for a sentence. 
The error code returned 
was 0x%1!8.8X!. 


An error occurred while 
setting exclusion terms. The 
error code returned was 
0x%1!8.8X!. 


An error occurred while 

processing a document in 
the input. The error code 
returned was 0x%1!8.8X!. 


An error occurred while 
testing whether a dot is a 
part of an acronym. The 
error code returned was 
0x%1!8.8X!. 


An error occurred while 
setting reference terms. The 
error code returned was 
0x%1!8.8X!. 


HEXADECIMAL CODE 


0xC020836E 


0xC020836F 


0xC0208370 


0xC0208371 


0xC0208372 


0xC0208373 


0xC0208374 


DECIMAL CODE 


-1071611026 


-1071611025 


-1071611024 


-1071611023 


-1071611022 


-1071611021 


-1071611020 


SYMBOLIC NAME 


DTS_E_TERMLOOKUP_PRO 
CESSDOCUMENT 


DTS_E_INVALIDBULKINSERT 
PROPERTYVALUE 


DTS_E_INVALIDBULKINSERT 
FIRSTROWLASTROWVALUE 
S 


DTS_E_FUZZYLOOKUPUNA 
BLETODELETEEXISTINGMAT 
CHINDEX 


DTS_E_TERMEXTRACTION | 
NCORRECTSCORETY PE 


DTS_E_FUZZYLOOKUPREFT 
ABLETOOBIG 


DTS_E_FUZZYLOOKUPUNA 
BLETODETERMINEREFEREN 
CETABLESIZE 


DESCRIPTION 


An error occurred while 

processing a document in 
the input. The error code 
returned was 0x%1!8.8X!. 


The value for the property 
%1 is %2!d!, which is not 
allowed. The value must be 
greater than or equal to 
%3!d!. 


The value for the property 
%1 is %2!d!, which must be 
less than or equal to the 
value of %3!d! for property 
SA. 


An error was encountered 
when trying to delete the 
existing fuzzy match index 
named "%1". It is possible 
that this table was not 
created by >Fuzzy Lookup 
(or this version of Fuzzy 
Lookup), it has been 
damaged, or there is 
another problem. Try 
manually deleting the table 
named "%2" or specify a 
different name for the 
MatchIndexName property. 


The Score Type of the 
transformation can only be 
Frequency or TFIDF. 


The reference table specified 
has too many rows. Fuzzy 
Lookup only works with 
reference tables having less 
than 1 billion rows. 
Consider using a smaller 
view of >your reference 
table. 


Unable to determine the 
size of the reference table 
'%1'. It is possible that this 
object is a view and not a 
table. Fuzzy Lookup does 
>not support views when 
CopyReferentaceTable= false. 
Make sure that the table 
exists and that 
CopyReferenceTable=true. 


HEXADECIMAL CODE 


0xC0208377 


0xC0208378 


0xC0208379 


0xC020837A 


0xC020837B 


0xC020837C 


0xC020837D 


0xC020837F 


0xC0208380 


0xC0208381 


0xC0208382 


DECIMAL CODE 


-1071611017 


-1071611016 


-1071611015 


-1071611014 


-1071611013 


-1071611012 


-1071611011 


-1071611009 


-1071611008 


-1071611007 


-1071611006 


SYMBOLIC NAME 


DTS_E_XMLSRCOUTPUTCO 
LUMNDATATY PENOTSUPP 
ORTED 


DTS_E_XMLSRCCANNOTFIN 
DCOLUMNTOSETDATATYPE 


DTS_E_CUSTOMPROPERTYI 
SREADONLY 


DTS_E_OUTPUTCOLUMNH 
ASNOERRORCOLUMN 


DTS_E_ERRORCOLUMNHAS 
NOOUTPUTCOLUMN 


DTS_E_ERRORCOLUMNHAS 
INCORRECTPROPERTIES 


DTS_E_ADOSRCOUTPUTCO 
LUMNDATATY PECANNOTBE 
CHANGED 


DTS_E_ADOSRCDATATY PEM 
ISMATCH 


DTS_E_ADOSRCCOLUMNN 
OTINSCHEMAROWSET 


DTS_E_TERMLOOKUP_INVA 
LIDREFERENCETERMTABLE 
ORCOLUMN 


DTS_E_TERMLOOKUP_REFE 
RENCETERMTABLEANDCOL 
UMNNOTSET 


DESCRIPTION 


The SSIS Data Flow Task 
data type "%1" on the %2 is 
not supported for the %3. 


Unable to set data type 
properties for the output 
column with ID %1!d! on 
the output with ID %2!dl. 
The output or column could 
not be found. 


The value of custom 
property "%1" on the %2 
cannot be changed. 


The %1 on the non-error 
output has no 
corresponding output 
column on the error output. 


The %1 on the error output 
has no corresponding 
output column on the non- 
error output. 


The %1 on the error output 
has properties that do not 
match the properties of its 
corresponding data source 
column. 


The data type of output 
columns on the %1 cannot 
be changed, except for 
DT_WSTR and DT_NTEXT 
columns. 


The data type of "%1" does 
not match the data type 
"%2" of the source column 
"%3". 


The %1 does not have a 
matching source column in 
the schema. 


The reference table/view or 
column used for the 
reference terms is invalid. 


The reference table/view or 
column used for the 
reference terms has not 
been set. 


HEXADECIMAL CODE 


0xC0208383 


0xC0208384 


0xC0208385 


0xC0208386 


0xC0208387 


0xC0208388 


0xC0208389 


0xC020838A 


0xC020838B 


0xC020838D 


0xC020838E 


0xC020838F 


DECIMAL CODE 


-1071611005 


-1071611004 


-1071611003 


-1071611002 


-1071611001 


-1071611000 


-1071610999 


-1071610998 


-1071610997 


-1071610995 


-1071610994 


-1071610993 


SYMBOLIC NAME 


DTS_E_COLUMNMAPPEDT 
OALREADYMAPPEDEXTERN 
ALMETADATACOLUMN 


DTS_E_TXFUZZYLOOKUP_T 
OOMANYPREFIXES 


DTS_E_MGDSRCSTATIC_OV 
ERFLOW 


DTS_E_DATAREADERDESTRE 
ADERISCLOSED 


DTS_E_DATAREADERDESTRE 
ADERISATEND 


DTS_E_DATAREADERDESTIN 
VALIDCOLUMNORDINAL 


DTS_E_DATAREADERDESTCA 
NNOTCONVERT 


DTS_E_DATAREADERDESTIN 
VALIDCODEPAGE 


DTS_E_XMLSRCEXTERNALM 
ETADATACOLUMNNOTINSC 
HEMA 


DTS_E_TXTERMLOOKUP_MI 
SMATCHED_COLUMN_MET 
ADATA 


DTS_E_DATAREADERDESTRE 
ADERTIMEOUT 


DTS_E_ADOSRCINVALIDSQ 
LCOMMAND 


DESCRIPTION 


The %1 is mapped to the 
external metadata column 
with ID %2!Id!, which is 
already mapped to another 
column. 


The SQL object name '%1' 
specified for property '%2' 
contains more than the 
maximum number of 
prefixes. The maximum is 2. 


The value was too large to 
fit in the column. 


The SSIS |DataReader is 
closed. 


The SSIS IDataReader is past 
the end of the result set. 


The ordinal position of the 
column is not valid. 


Cannot convert the %1 
from data type "%2" to data 
type "%3". 


The %1 has unsupported 
code page %2!d!. 


The %1 has no mapping to 
the XML schema. 


Columns with lineage IDs 
%1!d! and %2!d! have 
mismatched metadata. The 
input column that is 
mapped to an output 
column does not have the 
same >metadata (datatype, 
precision, scale, length, or 
codepage). 


The SSIS |DataReader is 
closed. The read timeout 
has expired. 


An error occurred executing 
the provided SQL 
command: "%1". %2 


HEXADECIMAL CODE 


0xC0208390 


0xC0208392 


0xC0208393 


0xC0208394 


0xC0208446 


0xC0208447 


0xC0208448 


0xC020844B 


0xC020844C 


DECIMAL CODE 


-1071610992 


-1071610990 


-1071610989 


-1071610988 


-1071610810 


-1071610809 


-1071610808 


-1071610805 


-1071610804 


SYMBOLIC NAME 


DTS_E_JOINTYPEDOESNTM 
ATCHETI 


DTS_E_SQLCEDESTDATATYP 
ENOTSUPPORTED 


DTS_E_DATAREADERDESTD 
ATATY PENOTSUPPORTED 


DTS_E_RECORDSETDESTDAT 
ATYPENOTSUPPORTED 


DTS_E_TXSCRIPTMIGRATIO 
NCOULDNOTADDREFEREN 
CE 


DTS_E_TXSCRIPTMIGRATIO 
NMULTIPLEENTRYPOINTSF 
OUND 


DTS_E_TXSCRIPTMIGRATIO 
NNOENTRYPOINTFOUND 


DTS_E_ADODESTINSERTION 
FAILURE 


DTS_E_ADODESTCONNECTI 
ONTYPENOTSUPPORTED 


DESCRIPTION 


The JoinType property 
specified for input column 
'%1' differs from the 
JoinType specified for the 
corresponding reference 
table column when the 
Match Index was > initially 
created. Either rebuild the 
Match Index with the given 
JoinType or change the 
JoinType to match the type 
used when the Match Index 
was created. 


The data type "%1" found 
on column "%2" is not 
supported for the %3. 


The data type "%1" found 
on %2 is not supported for 
the %3. 


The data type of the %1 is 
not supported for the %2. 


Failed to add project 
reference "%1" while 
migrating %2. Migration 
might need to be 
completed manually. 


Multiple entry points with 
the name "%1" were found 
during the migration of %2. 
Migration might need to be 
completed manually. 


No entry point was found 
during the migration of %1. 
Migration might need to be 
completed manually. 


An exception has occurred 
during data insertion, the 
message returned from the 
provider is: %1 


Failed to retrieve the 
provider invariant name 
from %1, it is currently not 
supported by ADO NET 
Destination component 


HEXADECIMAL CODE 


0xC020844D 


0xC020844E 


0xC020844F 


0xC0208450 


0xC0208451 


0xC0208452 


0xC0208453 


0xC0208454 


0xC0208455 


0xC0208456 


DECIMAL CODE 


-1071610803 


-1071610802 


-1071610801 


-1071610800 


-1071610799 


-1071610798 


-1071610797 


-1071610796 


-1071610795 


-1071610794 


SYMBOLIC NAME 


DTS_E_ADODESTARGUMEN 
TEXCEPTION 


DTS_E_ADODESTWRONGBA 
TCHSIZE 


DTS_E_ADODESTERRORUP 
DATEROW 


DTS_E_ADODESTEXECUTER 
EADEREXCEPTION 


DTS_E_ADODESTDATATY PE 
NOTSUPPORTED 


DTS_E_ADODESTFAILEDTOA 
CQUIRECONNECTION 


DTS_E_ADODESTNOTMANA 
GEDCONNECTION 


DTS_E_ADODESTNOERROR 
OUTPUT 


DTS_E_ADODESTNOLINEAG 
EID 


DTS_E_ADODESTEXTERNAL 
COLNOTEXIST 


DESCRIPTION 


An argument exception has 
occurred while data 
provider tried to insert data 
to destination. The returned 
message is : %1 


The BatchSize property 
must be a non-negative 
integer 


An error has occurred while 
sending this row to 
destination data source. 


Executing tSQL command 
throws an exception, the 
message is : %1 


The data type "%1" found 
on column "%2" is not 
supported for the %3. 


ADO NET Destination has 
failed to acquire the 
connection %1. The 
connection may have been 
corrupted. 


The specified connection %1 
is not managed, please use 
managed connection for 
ADO NET destination. 


The destination component 
does not have an error 
output. It may have been 
corrupted. 


The lineagelD %1 
associated with external 
column %2 does not exist 
at run time. 


The %1 does not exist in 
the database. It may have 
been removed or renamed. 


HEXADECIMAL CODE 


0xC0208457 


0xC0208458 


0xC0208459 


0xC020845A 


0xC020845B 


0xC0209001 


0xC0209002 


0xC0209011 


0xC0209012 


DECIMAL CODE 


-1071610793 


-1071610792 


-1071610791 


-1071610790 


-1071610789 


-1071607807 


-1071607806 


-1071607791 


-1071607790 


SYMBOLIC NAME 


DTS_E_ADODESTGETSCHEM 
ATABLEFAILED 


DTS_E_ADODESTCOLUMNE 
RRORDISPNOTSUPPORTED 


DTS_E_ADODESTCOLUMNT 
RUNDISPNOTSUPPORTED 


DTS_E_ADODESTINPUTTRU 
NDISPNOTSUPPORTED 


DTS_E_ADODESTTABLENAM 
EERROR 


DTS_E_FAILEDTOFINDCOLU 
MNINBUFFER 


DTS_E_FAILEDTOGETCOLU 
MNINFOFROMBUFFER 


DTS_E_TXAGG_ARITHMETIC 
OVERFLOW 


DTS_E_FAILEDTOGETCOLINF 
O 


DESCRIPTION 


Failed to get properties of 
external columns. The table 
name you entered may not 
exist, or you do not have 
SELECT permission on the 
table object and an 
>alternative attempt to get 
column properties through 
connection has failed. 
Detailed error messages 
are: %1 


Input column error 
disposition is not supported 
by ADO NET Destination 
component. 


Input column truncation 
disposition is not supported 
by ADO NET Destination 
component. 


Input truncation row 
disposition is not supported 
by ADO NET Destination 
component. 


The Table or View name is 
not expected. \n\t If you are 
quoting the table name, 
please use the prefix %1 

and the suffix %2 of your 
selected data provider for 

> quotation. \n\t If you are 
using multipart name, 
please use at most three 
parts for the table name. 


Failed to find column "%1" 
with lineage ID %2!d! in the 
buffer. The buffer manager 
returned error code 
0x%3!8.8X!. 


Failed to get information for 
column "%1" (%2!d!) from 
the buffer. The error code 
returned was 0x%3!8.8X!. 


Arithmetic overflow 
encountered while 
aggregating "%1". 


Failed to get information for 
row %1!Id!, column %2!Id! 
from the buffer. The error 
code returned was 
0x%3!8.8X!. 


HEXADECIMAL CODE 


0xC0209013 


0xC0209015 


0xC0209016 


0xC0209017 


0xC0209018 


0xC0209019 


0xC020901B 


0xC020901C 


0xC020901D 


OxC020901E 


0xC020901F 


0xC0209022 


0xC0209023 


0xC0209024 


DECIMAL CODE 


-1071607789 


-1071607787 


-1071607786 


-1071607785 


-1071607784 


-1071607783 


-1071607781 


-1071607780 


-1071607779 


-1071607778 


-1071607777 


-1071607774 


-1071607773 


-1071607772 


SYMBOLIC NAME 


DTS_E_FAILEDTOSETCOLINF 
O 


DTS_E_REQUIREDBUFFERIS 
NOTAVAILBLE 


DTS_E_FAILEDTOGETBUFFER 
BOUNDARYINFO 


DTS_E_FAILEDTOSETBUFFER 
ENDOFROWSET 


DTS_E_FAILEDTOGETDATAF 
ORERROROUTPUTBUFFER 


DTS_E_FAILEDTOREMOVER 
OWFROMBUFFER 


DTS_E_FAILEDTOSETBUFFER 
ERRORINFO 


DTS_E_COLUMNSTATUSERR 
OR 


DTS_E_TXLOOKUP_METADA 
TAXMLCACHEERR 


DTS_E_TXLOOKUP_ROWLO 
OKUPERROR 


DTS_E_INVALIDERRORDISP 
OSITION 


DTS_E_FAILEDTODIRECTERR 
ORROW 


DTS_E_FAILEDTOPREPAREC 
OLUMNSTATUSESFORINSER 
T 


DTS_E_FAILEDTOFINDCOLU 
MNBYLINEAGEID 


DESCRIPTION 


Failed to set information for 
row %1!Id!, column %2!Id! 
into the buffer. The error 
code returned was 
0x%3!8.8X!. 


A required buffer is not 
available. 


The attempt to get buffer 
boundary information failed 
with error code 0x%1!8.8X!. 


Setting the end of rowset 
for the buffer failed with 
error code 0x%1!8.8X!. 


Failed to get data for the 
error output buffer. 


Removing a row from the 
buffer failed with error code 
0x%1!8.8X!. 


The attempt to set buffer 
error information failed with 
error code 0x%1!8.8X!. 


There was an error with %1 
on %2. The column status 
returned was: "%3". 


Unable to cache reference 
metadata. 


Row yielded no match 
during lookup. 


The %1 has an invalid error 
or truncation row 
disposition. 


Directing the row to the 
error output failed with 
error code 0x%1!8.8X!. 


Preparing column statuses 
for insert failed with error 
code 0x%1!8.8X!. 


An attempt to find %1 with 
lineage ID %2!d! in the Data 
Flow Task buffer failed with 
error code 0x%3!8.8X!. 


HEXADECIMAL CODE 


0xC0209025 


0xC0209029 


0xC020902A 


0xC020902B 


0xC020902C 


DECIMAL CODE 


-1071607771 


-1071607767 


-1071607766 


-1071607765 


-1071607764 


SYMBOLIC NAME 


DTS_E_FAILEDTOFINDNONS 
PECIALERRORCOLUMN 


DTS_E_INDUCEDTRANSFOR 
MFAILUREONERROR 


DTS_E_INDUCEDTRANSFOR 
MFAILUREONTRUNCATION 


DTS_E_TXSPLITEXPRESSION 
EVALUATEDTONULL 


DTS_E_TXSPLITSTATIC_EXPR 
ESSIONEVALUATEDTONULL 


DESCRIPTION 


Failed to find any non- 
special error column in %1. 


SSIS Error Code 
DTS_E_INDUCEDTRANSFOR 
MFAILUREONERROR. The 
"%1" failed because error 
code 0x%2!8.8X! occurred, 
and the error row 
disposition on "%3" 
>specifies failure on error. 
An error occurred on the 
specified object of the 
specified component. There 
may be error messages 
posted before this with 
more information about the 
failure. 


The "%1" failed because 
truncation occurred, and 
the truncation row 
disposition on "%2" 
specifies failure on 
truncation. A truncation 
error occurred >on the 
specified object of the 
specified component. 


The expression "%1" on 
"%2" evaluated to NULL, 
but the "%3" requires a 
Boolean results. Modify the 
error row disposition on the 
output to treat this >result 
as False (Ignore Failure) or 
to redirect this row to the 
error output (Redirect Row). 
The expression results must 
be Boolean for a 
Conditional Split. A NULL 
expression result is an error. 


The expression evaluated to 
NULL, but a Boolean result 
is required. Modify the error 
row disposition on the 
output to treat this result 
as False > (Ignore Failure) or 
to redirect this row to the 
error output (Redirect Row). 
The expression results must 
be Boolean for a 
Conditional Split. A NULL 
expression result is an error. 


HEXADECIMAL CODE 


0xC020902D 


0xC020902E 


0xC020902F 


0xC020903E 


0xC020903F 


0xC0209069 


0xC020906A 


0xC020906B 


OxC020906C 


0xC020906D 


OxC020906E 


0xC020906F 


DECIMAL CODE 


-1071607763 


-1071607762 


-1071607761 


-1071607746 


-1071607745 


-1071607703 


-1071607702 


-1071607701 


-1071607700 


-1071607699 


-1071607698 


-1071607697 


SYMBOLIC NAME 


DTS_E_UTF16BIGENDIANFO 
RMATNOTSUPPORTED 


DTS_E_UTF8FORMATNOTSU 
PPORTEDASUNICODE 


DTS_E_DTPXMLCANTREADI 
DATTR 


DTS_E_TXLOOKUP_INDEXC 
OLUMNREUSED 


DTS_E_TXLOOKUP_INDEXC 
OLUMNSMISMATCH 


DTS_E_COMMANDDESTINA 
TIONADAPTERSTATIC_CANT 
CONVERTVALUE 


DTS_E_COMMANDDESTINA 
TIONADAPTERSTATIC_SCHE 
MAVIOLATION 


DTS_E_COMMANDDESTINA 
TIONADAPTERSTATIC_TRUN 
CATED 


DTS_E_COMMANDDESTINA 
TIONADAPTERSTATIC_SIGN 
MISMATCH 


DTS_E_COMMANDDESTINA 
TIONADAPTERSTATIC_DATA 
OVERFLOW 


DTS_E_COMMANDDESTINA 
TIONADAPTERSTATIC_UNA 
VAILABLE 


DTS_E_COMMANDDESTINA 
TIONADAPTERSTATIC_PER 
MISSIONDENIED 


DESCRIPTION 


The file format of UTF-16 
big endian is not 
supported. Only UTF-16 
little endian format is 
supported. 


The file format of UTF-8 is 
not supported as Unicode. 


Cannot read ID attribute. 


The cache index column %1 
is referenced by more than 
one lookup input column. 


Lookup does not reference 
all cache connection 
manager index columns. 
Number of joined columns 
in lookup: %1!d!. Number of 
index columns: %2!d!. 


The data value cannot be 
converted for reasons other 
than sign mismatch or data 
overflow. 


The data value violated the 
schema constraint. 


The data was truncated. 


Conversion failed because 
the data value was signed 
and the type used by the 
provider was unsigned. 


Conversion failed because 
the data value overflowed 
the type used by the 
provider. 


No status is available. 


The user did not have the 
correct permissions to write 
to the column. 


HEXADECIMAL CODE 


0xC0209070 


0xC0209071 


0xC0209072 


0xC0209073 


0xC0209074 


0xC0209075 


0xC0209076 


0xC0209077 


0xC0209078 


0xC0209079 


0xC020907A 


0xC020907B 


0xC020907C 


DECIMAL CODE 


-1071607696 


-1071607695 


-1071607694 


-1071607693 


-1071607692 


-1071607691 


-1071607690 


-1071607689 


-1071607688 


-1071607687 


-1071607686 


-1071607685 


-1071607684 


SYMBOLIC NAME 


DTS_E_COMMANDDESTINA 
TIONADAPTERSTATIC_INTE 
GRITYVIOLATION 


DTS_E_LOLEDBSOURCEADA 
PTERSTATIC_UNAVAILABLE 


DTS_E_LOLEDBSOURCEADA 
PTERSTATIC_CANTCONVERT 
VALUE 


DTS_E_LOLEDBSOURCEADA 
PTERSTATIC_TRUNCATED 


DTS_E_OLEDBSOURCEADA 
PTERSTATIC_SIGNMISMATC 
H 


DTS_E_LOLEDBSOURCEADA 
PTERSTATIC_DATAOVERFLO 
W 


DTS_E_OLEDBDESTINATION 
ADAPTERSTATIC_SCHEMAVI 
OLATION 


DTS_E_OLEDBDESTINATION 
ADAPTERSTATIC_CANTCON 
VERTVALUE 


DTS_E_OLEDBDESTINATION 
ADAPTERSTATIC_TRUNCATE 
D 


DTS_E_OLEDBDESTINATION 
ADAPTERSTATIC_SIGNMIS 
MATCH 


DTS_E_OLEDBDESTINATION 
ADAPTERSTATIC_DATAOVE 
RFLOW 


DTS_E_OLEDBDESTINATION 
ADAPTERSTATIC_UNAVAILA 
BLE 


DTS_E_OLEDBDESTINATION 
ADAPTERSTATIC_PERMISSI 
ONDENIED 


DESCRIPTION 


The data value violated the 
integrity constraints for the 
column. 


No status is available. 


The data value cannot be 
converted for reasons other 
than sign mismatch or data 
overflow. 


The data was truncated. 


Conversion failed because 
the data value was signed 
and the type used by the 
provider was unsigned. 


Conversion failed because 
the data value overflowed 
the type used by the 
provider. 


The data value violated the 
schema constraint. 


The data value cannot be 
converted for reasons other 
than sign mismatch or data 
overflow. 


The data was truncated. 


Conversion failed because 
the data value was signed 
and the type used by the 
provider was unsigned. 


Conversion failed because 
the data value overflowed 
the type used by the 
provider. 


No status is available. 


The user did not have the 
correct permissions to write 
to the column. 


HEXADECIMAL CODE 


0xC020907D 


0xC020907F 


0xC0209080 


0xC0209081 


0xC0209082 


0xC0209083 


0xC0209084 


0xC0209085 


0xC0209086 


0xC0209087 


OxC020908E 


0xC0209090 


0xC0209091 


DECIMAL CODE 


-1071607683 


-1071607681 


-1071607680 


-1071607679 


-1071607678 


-1071607677 


-1071607676 


-1071607675 


-1071607674 


-1071607673 


-1071607666 


-1071607664 


-1071607663 


SYMBOLIC NAME 


DTS_E_OLEDBDESTINATION 
ADAPTERSTATIC_INTEGRITY 
VIOLATION 


DTS_E_TXDATACONVERTST 
ATIC_CANTCONVERTVALUE 


DTS_E_TXDATACONVERTST 
ATIC_TRUNCATED 


DTS_E_TXDATACONVERTST 
ATIC_SIGNMISMATCH 


DTS_E_TXDATACONVERTST 
ATIC_DATAOVERFLOW 


DTS_E_FLATFILESOURCEAD 
APTERSTATIC_UNAVAILABL 
E 


DTS_E_FLATFILESOURCEAD 
APTERSTATIC_CANTCONVE 
RTVALUE 


DTS_E_FLATFILESOURCEAD 
APTERSTATIC_TRUNCATED 


DTS_E_FLATFILESOURCEAD 
APTERSTATIC_SIGNMISMAT 
CH 


DTS_E_FLATFILESOURCEAD 
APTERSTATIC_DATAOVERFL 
OW 


DTS_E_TXDATACONVERTST 
ATIC_UNAVAILABLE 


DTS_E_FILEOPENERR_FORR 
EAD 


DTS_E_TXFILEINSERTERSTATI 
C_FILEOPENERR_FORREAD 


DESCRIPTION 


The data value violates 
integrity constraints. 


The data value cannot be 
converted for reasons other 
than sign mismatch or data 
overflow. 


The data was truncated. 


Conversion failed because 
the data value was signed 
and the type used by the 
provider was unsigned. 


Conversion failed because 
the data value overflowed 
the type used by the data 
conversion transform. 


No status is available. 


The data value cannot be 
converted for reasons other 
than sign mismatch or data 
overflow. 


The data was truncated. 


Conversion failed because 
the data value was signed 
and the type used by the 
flat file source adapter was 
unsigned. 


Conversion failed because 
the data value overflowed 
the type used by the flat file 
source adapter. 


No status is available. 


Opening the file "%1" for 
reading failed with error 
code 0x%2!8.8X!. 


Failed to open file for 
reading. 


HEXADECIMAL CODE 


0xC0209092 


0xC0209093 


0xC0209094 


0xC0209095 


0xC0209099 


0xC020909A 


OxCO020909E 


OxC020909F 


O0xC02090A0 


OxC02090A1 


0xC02090A2 


0xC02090A3 


DECIMAL CODE 


-1071607662 


-1071607661 


-1071607660 


-1071607659 


-1071607655 


-1071607654 


-1071607650 


-1071607649 


-1071607648 


-1071607647 


-1071607646 


-1071607645 


SYMBOLIC NAME 


DTS_E_FILEOPENERR_FORW 
RITE 


DTS_E_TXFILEEXTRACTORST 
ATIC_FILEOPENERR_FORWR 
ITE 


DTS_E_TXFILEINSERTERSTATI 
C_INSERTERCANTREAD 


DTS_E_TXFILEEXTRACTORST 
ATIC_EXTRACTORCANTWRI 
TE 


DTS_E_DTPXMLINVALIDPRO 
PERTYARRAYTOOMANYVAL 
UES 


DTS_E_DTPXMLINVALIDPRO 
PERTYARRAYNOTENOUGHV 
ALUES 


DTS_E_FILEOPENERR_FORW 
RITE_FILENOTFOUND 


DTS_E_TXFILEEXTRACTORST 
ATIC_FILEOPENERR_FORWR 
ITE_FILENOTFOUND 


DTS_E_FILEOPENERR_FORW 
RITE_PATHNOTFOUND 


DTS_E_TXFILEEXTRACTORST 
ATIC_FILEOPENERR_FORWR 
ITE_PATHNOTFOUND 


DTS_E_FILEOPENERR_FORW 
RITE_TOOMANYOPEMFILES 


DTS_E_TXFILEEXTRACTORST 
ATIC_FILEOPENERR_FORWR 
ITE_TOOMANYOPEMFILES 


DESCRIPTION 


Opening the file "%1" for 
writing failed with error 
code 0x%2!8.8X!. 


Failed to open file for 
writing. 


Failed to read from file. 


Failed to write to file. 


Too many array elements 
were found when parsing a 
property of type array. The 
elementCount is less than 
the number of array 
elements found. 


Too few array elements 
were found when parsing a 
property of type array. The 
elementCount is more than 
the number of array 
elements found. 


Opening the file "%1" for 
writing failed. The file 
cannot be found. 


Opening the file for writing 
failed. The file cannot be 
found. 


Opening the file "%1" for 
writing failed. The path 
cannot be found. 


Opening the file for writing 
failed. The path cannot be 
found. 


Opening the file "%1" for 
writing failed. There are too 
many files open. 


Opening the file for writing 
failed. There are too many 
files open. 


HEXADECIMAL CODE 


OxC02090A4 


0xC02090A5 


O0xC02090A6 


0xC02090A7 


0xC02090A8 


O0xC02090A9 


0xC02090AD 


OxCO2090AE 


OxC02090B9 


DECIMAL CODE 


-1071607644 


-1071607643 


-1071607642 


-1071607641 


-1071607640 


-1071607639 


-1071607635 


-1071607634 


-1071607623 


SYMBOLIC NAME 


DTS_E_FILEOPENERR_FORW 
RITE_ACCESSDENIED 


DTS_E_TXFILEEXTRACTORST 
ATIC_FILEOPENERR_FORWR 
ITE_ACCESSDENIED 


DTS_E_FILEOPENERR_FORW 
RITE_FILEEXISTS 


DTS_E_TXFILEEXTRACTORST 
ATIC_FILEOPENERR_FORWR 
ITE_FILEEXISTS 


DTS_E_INCORRECTCUSTOM 
PROPERTYVALUEFOROBJEC 
T 


DTS_E_COLUMNSHAVEINC 
OMPATIBLEMETADATA 


DTS_E_FILEWRITEERR_DISKF 
ULL 


DTS_E_TXFILEEXTRACTORST 
ATIC_FILEWRITEERR_DISKF 
ULL 


DTS_E_TXAGG_SORTKEYGE 
NFAILED 


DESCRIPTION 


Opening the file "%1" for 
writing failed. You do not 
have the correct 
permissions. 


Opening the file for writing 
failed. You do not have the 
correct permissions. 


Opening the file "%1" for 
writing failed. The file exists 
and cannot be overwritten. 
If the AllowAppend 
property is FALSE and the 
ForceTruncate property >is 
set to FALSE, the existence 
of the file will cause this 
failure. 


Opening a file for writing 
failed. The file already exists 
and cannot be overwritten. 
If both the AllowAppend 
property and the 
>Forcelruncate property 
are set to FALSE, the 
existence of the file will 
cause this failure. 


The value for custom 
property "%1" on %2 is 
incorrect. 


Columns "%1" and "%2" 
have incompatible 
metadata. 


Opening the file "%1" for 
writing failed because the 
disk is full. There is not 
sufficient disk space to save 
this file. 


Attempting to open the file 
for writing failed because 
the disk is full. 


Generating a sort key failed 
with error 0x%1!8.8X!. The 
ComparisonFlags are 
enabled, and generating a 
sortkey with LCMapString 
failed. 


HEXADECIMAL CODE 


OxC02090BA 


0xC02090BB 


OxCO02090BC 


0xC02090BD 


OxCO2090BE 


OxC02090BF 


0xC02090C0 


0xC02090C1 


0xC02090C2 


0xC02090C3 


O0xC02090C4 


DECIMAL CODE 


-1071607622 


-1071607621 


-1071607620 


-1071607619 


-1071607618 


-1071607617 


-1071607616 


-1071607615 


-1071607614 


-1071607613 


-1071607612 


SYMBOLIC NAME 


DTS_E_TXCHARMAPLCMAP 
FAILED 


DTS_E_FILEOPENERR_FORR 
EAD_FILENOTFOUND 


DTS_E_TXFILEINSERTERSTATI 
C_FILEOPENERR_FORREAD_ 
FILENOTFOUND 


DTS_E_FILEOPENERR_FORR 
EAD_PATHNOTFOUND 


DTS_E_TXFILEINSERTERSTATI 
C_FILEOPENERR_FORREAD_ 
PATHNOTFOUND 


DTS_E_FILEOPENERR_FORR 
EAD_TOOMANYOPENMFILES 


DTS_E_TXFILEINSERTERSTATI 
C_FILEOPENERR_FORREAD_ 
TOOMANYOPENFILES 


DTS_E_FILEOPENERR_FORR 
EAD_ACCESSDENIED 


DTS_E_TXFILEINSERTERSTATI 
C_FILEOPENERR_FORREAD_ 
ACCESSDENIED 


DTS_E_INSERTERINVALIDBO 
M 


DTS_E_TXFILEINSERTERSTATI 
C_INSERTERINVALIDBOM 


DESCRIPTION 


Transform failed to map 
string and returned error 
0x%1!8.8X!. The 
LCMapString failed. 


Opening the file "%1" for 
reading failed. The file was 
not found. 


Opening a file for reading 
failed. The file was not 
found. 


Opening the file "%1" for 
reading failed. The path 
cannot be found. 


Opening a file for reading 
failed. The path was not 
found. 


Opening the file "%1" for 
reading failed. There are too 
many files open. 


Opening the file for reading 
failed. There are too many 
files open. 


Attempting to open the file 
"%1" for reading failed. 
Access is denied. 


Opening the file for reading 
failed. You do not have the 
correct permissions. 


The byte order mark (BOM) 
value for the file "%1" is 
0x%2!4.4X!, but the 
expected value is 
0x%3!4.4xX!. The ExpectBOM 
property was set for this 
file, but the BOM value >in 
the file is missing or not 
valid. 


The byte order mark (BOM) 
value for the file is not valid. 
The ExpectBOM property 
was set for this file, but the 
BOM value in the file is 
missing >or not valid. 


HEXADECIMAL CODE 


0xC02090C5 


0xC02090C9 


OxC02090CA 


OxC02090CB 


0xC02090CD 


OxCO02090CF 


0xC02090D0 


0xC02090D1 


0xC02090D2 


0xC02090D6 


DECIMAL CODE 


-1071607611 


-1071607607 


-1071607606 


-1071607605 


-1071607603 


-1071607601 


-1071607600 


-1071607599 


-1071607598 


-1071607594 


SYMBOLIC NAME 


DTS_E_NOCOMPONENTATT 
ACHED 


DTS_E_TXLOOKUP_INVALID 
MAXMEMORYPROP 


DTS_E_TXAGG_COMPFLAG 
S_BADAGGREGATIONTYPE 


DTS_E_TXAGG_COMPFLAG 
S_BADDATATYPE 


DTS_E_TXAGG_AGGREGATI 
ON_FAILURE 


DTS_E_MAPPINGSETUPERR 
OR 


DTS_E_XMLSRCUNABLETOR 
EADXMLDATA 


DTS_E_XMLSRCUNABLETOG 
ETXMLDATAVARIABLE 


DTS_E_NODATATABLEMATC 
HROWID 


DTS_E_TXAGG_BADKEYSVA 
LUE 


DESCRIPTION 


The %1 is not attached to a 
component. It is required 
that a component be 
attached. 


The value for custom 
property %1 is incorrect. It 
should be a number 
between %2!d! and 
%3'164d!. 


The custom property "%1" 
cannot be specified for the 
aggregation type selected 
for this column. The 
comparison flags custom 
property can only be 
>specified for group by and 
count distinct aggregation 
types. 


The comparison flags 
custom property "%1" can 
only be specified for 
columns of with datatype 
DT_STR or DT_WSTR. 


Aggregation on %11 failed 
with error code 0x%2!8.8X!. 


There was an error setting 
up the mapping. %1 


The %1 was unable to read 
the XML data. 


The %1 was unable to get 
the variable specified by the 
"%2" property. 


The %1 contains a RowsetID 
with a value of %2 that 
does not reference a data 
table in the schema. 


The property %1 must 
either be empty, or a 
number between %2!u! and 
%3!u!. The Keys or 
CountDistinctKeys property 
has a invalid value. The 
property should be a 
number >between 0 and 
ULONG_MA\X, inclusive, or 
not be set. 


HEXADECIMAL CODE 


0xC02090D7 


0xC02090D8 


0xC02090D9 


0xC02090DC 


OxC02090E3 


OxCO02090E5 


OxC02090E6 


OxC02090E7 


OxC02090F0 


DECIMAL CODE 


-1071607593 


-1071607592 


-1071607591 


-1071607588 


-1071607581 


-1071607579 


-1071607578 


-1071607577 


-1071607568 


SYMBOLIC NAME 


DTS_E_TXAGG_TOOMANYK 
EYS 


DTS_E_TXAGG_TOOMANYC 
OUNTDISTINCTVALUES 


DTS_E_FAILEDTOWRITETOT 
HEFILENAMECOLUMN 


DTS_E_FAILEDTOFINDERRO 
RCOLUMN 


DTS_E_TXLOOKUP_FAILEDU 
PGRADE_BAD_VERSION 


DTS_E_TERMEXTRACTIONO 
RLOOKUP_NTEXTSPLITED 


DTS_E_TERMEXTRACTION_E 
XCEED_MAXWORDNUM 


DTS_E_XMLSRCFAILEDTOCR 
EATEREADER 


DTS_E_TXLOOKUP_REINITM 
ETADATAFAILED 


DESCRIPTION 


The aggregate component 
encountered too many 
distinct key combinations. It 
cannot accommodate more 
than %1!u! distinct key 
values. There are more than 
ULONG_MAX > distinct key 
values in the main 
workspace. 


The aggregate component 
encountered too many 
distinct values while 
calculating the count 
distinct aggregate. It cannot 
accommodate more than 
%1!u! > distinct values. 
There were more than 
ULONG_MAX distinct 
values while calculating the 
count distinct aggregation. 


The attempt to write to the 
filename column failed with 
error code 0x%1!8.8X!. 


An error occurred, but the 
column that caused the 
error cannot be determined. 


Unable to upgrade lookup 
metadata from version 
%1!d! to %2!d!. The Lookup 
transform was unable to 
upgrade metadata from the 
existing version number in 
>a call to 
PerformUpgrade(). 


Failed to locate the ending 
boundary of a sentence. 


The Term Extraction 
transformation is unable to 
process the input text 
because a sentence from 
the input text is too long. 
The sentence is segmented 
into >several sentences. 


The %1 was unable to read 
the XML data. %2 


The call to Lookup 
transform method, 
ReinitializeMetadata, failed. 


HEXADECIMAL CODE 


0OxC02090F1 


OxC02090F2 


OxC02090F3 


OxCO02090F5 


OxC02090F6 


OxCO02090F7 


OxCO02090F8 


OxCO02090F9 


OxCO02090FA 


DECIMAL CODE 


-1071607567 


-1071607566 


-1071607565 


-1071607563 


-1071607562 


-1071607561 


-1071607560 


-1071607559 


-1071607558 


SYMBOLIC NAME 


DTS_E_TXLOOKUP_NOJOIN 
S 


DTS_E_MANAGEDERR_BAD 
FORMATSPECIFICATION 


DTS_E_MANAGEDERR_UNS 
UPPORTEDTY PE 


DTS_E_DATAREADERSRCUN 
ABLETOPROCESSDATA 


DTS_E_XMLSRCEMPTYPROP 
ERTY 


DTS_E_XMLSRCINVALIDOU 
TPUTNAME 


DTS_E_MGDSRC_OVERFLO 
W 


DTS_E_DATAREADERDESTU 
NABLETOPROCESSDATA 


DTS_E_XMLSRC_INDUCEDT 
RANSFORMFAILUREONTRU 
NCATION 


DESCRIPTION 


The lookup transform must 
contain at least one input 
column joined to a 
reference column, and none 
were specified. You must 
specify at least one join 
column. 


The message string being 
posted by the managed 
error infrastructure contains 
a bad format specification. 
This is an internal error. 


While formatting a message 
string using the managed 
error infrastructure, there 
was a variant type that 
does not have formatting 
support. This is an internal 
> error. 


The %1 was unable to 
process the data. %2 


The property "%1" on the 
%2 was empty. 


Attempting to create an 
output with the name "%1" 
for the XML table with the 
path "%2" failed because 
the name is invalid. 


The value was too large to 
fit in the %1. 


The %1 was unable to 
process the data. 


The "%1" failed because 
truncation occurred, and 
the truncation row 
disposition on "%2" at "%3" 
specifies failure on 
truncation. A truncation 
>error occurred on the 
specified object of the 
specified component. 


HEXADECIMAL CODE 


OxC02090FB 


0xC0209291 


0xC0209292 


0xC0209293 


0xC0209294 


0xC0209295 


0xC0209296 


0xC0209297 


0xC0209298 


0xC0209299 


0xC020929A 


0xC020929B 


O0xC020929C 


DECIMAL CODE 


-1071607557 


-1071607151 


-1071607150 


-1071607149 


-1071607148 


-1071607147 


-1071607146 


-1071607145 


-1071607144 


-1071607143 


-1071607142 


-1071607141 


-1071607140 


SYMBOLIC NAME 


DTS_E_XMLSRC_INDUCEDT 
RANSFORMFAILUREONERR 
OR 


DTS_E_SQLCEDESTSTATIC_F 
AILEDTOSETVALUES 


DTS_E_SQLCEDESTSTATIC_F 
AILEDTOINSERT 


DTS_E_TXFUZZYLOOKUP_O 
LEDBERR_LOADCOLUMNM 
ETADATA 


DTS_E_TXFUZZYLOOKUP_T 
OOFEWREFERENCECOLUM 
NS 


DTS_E_TXSCD_OLEDBERR_L 
OADCOLUMNMETADATA 


DTS_E_TXSCD_TOOFEWREF 
ERENCECOLUMNS 


DTS_E_TXSCD_MALLOCERR 
_REFERENCECOLUMNINFO 


DTS_E_TXSCD_MALLOCERR 
_BUFFCOL 


DTS_E_TXSCD_MAINWORKS 
PACE_CREATEERR 


DTS_E_DTPXMLDOMCREAT 
EERROR 


DTS_E_DTPXMLDOMLOADE 
RROR 


DTS_E_RSTDESTBADVARIAB 
LETYPE 


DESCRIPTION 


The "%1" failed because 
error code 0x%2!8.8X! 
occurred, and the error row 
disposition on "%3" at "%4" 
specifies failure on error. An 
error occurred >on the 
specified object of the 
specified component. 


The SQLCE destination 
could not set the column 
values for the row. 


The SQLCE destination 
could not insert the row. 


Encountered OLEDB error 
while loading column 
metadata. 


Lookup reference metadata 
contains too few columns. 


Encountered OLEDB error 
while loading column 
metadata. 


Lookup reference metadata 
contains too few columns. 


Unable to allocate memory. 


Unable to allocate memory. 


Unable to create workspace 
buffer. 


Unable to instantiate XML 
DOM document, please 
verify that MSXML binaries 
are properly installed and 
registered. 


Unable to load XML data 
into a local DOM for 
processing. 


The type of the runtime 
variable "%1" is incorrect. 
The runtime variable type 
must be Object. 


HEXADECIMAL CODE 


OxC020929E 


0xC020929F 


0xC02092A0 


OxC02092A1 


0xC02092A2 


0xC02092A3 


0xC02092A4 


0xC02092A5 


0xC02092A6 


0xC02092A9 


DECIMAL CODE 


-1071607138 


-1071607137 


-1071607136 


-1071607135 


-1071607134 


-1071607133 


-1071607132 


-1071607131 


-1071607130 


-1071607127 


SYMBOLIC NAME 


DTS_E_XMLDATAREADERM 
ULTIPLEINLINEXMLSCHEM 
ASNOTSUPPORTED 


DTS_E_XMLDATAREADERAN 
YTYPENOTSUPPORTED 


DTS_E_XMLDATAREADERGR 
OUPREFNOTSUPPORTED 


DTS_E_XMLDATAREADERMI 
XEDCONTENTFORCOMPLE 
XTYPESNOTSUPPORTED 


DTS_E_XMLDATAREADERIN 
LINESCHEMAFOUNDINSO 
URCEXML 


DTS_E_XMLDATAREADERN 
OINLINESCHEMAFOUND 


DTS_E_CONNECTIONMANA 
GERTRANSACTEDANDRETAI 
NEDINBULKINSERT 


DTS_E_OUTPUTREDIRECTIN 
TRANSACTIONNOTALLOWE 
D 


DTS_E_FOUNDORPHANEDE 
XTERNALMETADATACOLU 
MN 


DTS_E_RAWDESTNOINPUTC 
OLUMNS 


DESCRIPTION 


The XML Source Adapter 
was unable to process the 
XML data. Multiple inline 
schemas are not supported. 


The XML Source Adapter 
was unable to process the 
XML data. The content of 
an element can not be 
declared as anyType. 


The XML Source Adapter 
was unable to process the 
XML data. The content of 
an element can not contain 
a reference (ref) to a group. 


The XML Source Adapter 
does not support mixed 
content model on Complex 
Types. 


The XML Source Adapter 
was unable to process the 
XML data. An inline schema 
must be the first child node 
in the source Xml. 


The XML Source Adapter 
was unable to process the 
XML data. No inline schema 
was found in the source 
XML, but the 
"UselnlineSchema" property 
was set to >true. 


The component cannot use 
a connection manager that 
retains its connection in a 
transaction with fastload or 
bulk insert. 


The %1 cannot be set to 
redirect on error using a 
connection in a transaction. 


The %1 does not have a 
corresponding input or 
output column. 


There is no selected column 
to be written to the file. 


HEXADECIMAL CODE 


OxC02092AA 


0xC02092AB 


0xC02092AC 


0xC02092AD 


OxC02092AE 


OxC02092AF 


0xC02092B0 


0xC02092B1 


DECIMAL CODE 


-1071607126 


-1071607125 


-1071607124 


-1071607123 


-1071607122 


-1071607121 


-1071607120 


-1071607119 


SYMBOLIC NAME 


DTS_E_RAWDESTBLOBDATA 
TYPE 


DTS_E_RAWDESTWRONGEX 
TERNALMETADATAUSAGE 


DTS_E_RAWDESTMAPPEDIN 
PUTCOLUMN 


DTS_E_RAWFILECANTOPEN 
FORMETADATA 


DTS_E_FAILEDTOACCESSLO 
BCOLUMN 


DTS_E_XMLSRCUNABLETOP 
ROCESSXMLDATA 


DTS_E_XMLSRCSTATIC_UNA 
BLETOPROCESSXMLDATA 


DTS_E_RAWINVALIDACCESS 
MODE 


DESCRIPTION 


The %1 has an invalid data 
type. Columns with data 
types DT_IMAGE, DT_TEXT 
and DT_NTEXT cannot be 
written to raw files. 


The external metadata 
collection is improperly 
used by this component. 
The component should use 
external metadata when 
appending or truncating an 
>existing file. Otherwise, 
the external metadata is not 
needed. 


The %1 is mapped to an 
external metadata column 
with the id %2!d!. Input 
columns should not be 
mapped to external 
metadata columns when 
selected Write Option 
>value is Create Always. 


The file cannot be opened 
for reading the metadata. If 
the file does not exist, and 
the component has already 
defined external metadata, 
you can set the 
>'"ValidateExternalMetadata 
" property to "false" and the 
file will be created at the 
runtime. 


Failed to access LOB data 
from the data flow buffer 
for data source column 
"%1" with error code 
0x%2!8.8X!. 


The %1 was unable to 
process the XML data. %2 


The XML Source Adapter 
was unable to process the 
XML data. 


The value %1!d! is not 
recognized as a valid access 
mode. 


HEXADECIMAL CODE 


0xC02092B2 


0xC02092B3 


0xC02092B4 


0xC02092B5 


0xC02092B6 


0xC02092B7 


0xC0209302 


0xC0209303 


0xC0209306 


0xC0209307 


DECIMAL CODE 


-1071607118 


-1071607117 


-1071607116 


-1071607115 


-1071607114 


-1071607113 


-1071607038 


-1071607037 


-1071607034 


-1071607033 


SYMBOLIC NAME 


DTS_E_INCOMPLETEDATAS 
OURCECOLUMNFOUND 


DTS_E_TXAUDIT_ONLYSTRI 
NGLENGTHCHANGEALLOW 
ED 


DTS_E_ROWSETUNAVAILAB 
LE 


DTS_E_COMMITFAILED 


DTS_E_USEBINARYFORMAT 
REQUIRESANSIFILE 


DTS_E_USEBINARYFORMAT 
REQUIRESBYTES 


DTS_E_OLEDB_NOPROVIDE 
R_ERROR 


DTS_E_OLEDB_NOPROVIDE 
R_64BIT_ERROR 


DTS_E_MULTICACHECOLM 
APPINGS 


DTS_E_COLNOTMAPPEDTO 
CACHECOL 


DESCRIPTION 


Complete metadata 
information for the data 
source column "%1" is not 
available. Make sure the 
column is correctly defined 
in the data source. 


Only lengths of User Name 
column, Package Name 
column, Task Name column 
and Machine Name column 
can be changed. All other 
audit column datatype 
>information is read only. 


A rowset based on the SQL 
command was not returned 
by the OLE DB provider. 


A commit failed. 


The custom property "%1" 
on %2 can only be used 
with ANSI files. 


The custom property "%1" 
on %2 can only be used 
with DT_BYTES. 


SSIS Error Code 
DTS_E_OLEDB_NOPROVIDE 
R_ERROR. The requested 
OLE DB provider %2 is not 
registered. Error code: 
0x%1!8.8X!. 


SSIS Error Code 
DTS_E_OLEDB_NOPROVIDE 
R_64BIT_ERROR. The 
requested OLE DB provider 
%2 is not registered -- 
perhaps no 64-bit provider 
is available. Error > code: 
0x%1!8.8X!. 


The cache column, "%1", is 
mapped to more than one 
column. Remove the 
duplicate column mappings. 


The %1 is not mapped to 
valid cache column. 


HEXADECIMAL CODE 


0xC0209308 


0xC0209309 


0xC020930A 


0xC020930B 


0xC020930C 


0xC020930D 


0xC020930E 


0xC020930F 


0xC0209311 


0xC0209312 


0xC0209313 


0xC0209314 


DECIMAL CODE 


-1071607032 


-1071607031 


-1071607030 


-1071607029 


-1071607028 


-1071607027 


-1071607026 


-1071607025 


-1071607023 


-1071607022 


-1071607021 


-1071607020 


SYMBOLIC NAME 


DTS_E_CACHECOLDATATYP 
EINCOMPAT 


DTS_E_INCORRECTINPUTCA 
CHECOLCOUNT 


DTS_E_INVALIDCACHEFILE 
NAME 


DTS_E_CACHECOLINDEXPO 
SMISMATCH 


DTS_E_FAILEDTOLOADCAC 
HE 


DTS_E_TXLOOKUP_REFCOL 
UMNISNOTINDEX 


DTS_E_FAILEDTOGETCONNE 
CTIONSTRING 


DTS_E_CACHECOLDATATYP 
EPROPINCOMPAT 


DTS_E_CACHECOLUMNOTF 
OUND 


DTS_E_CACHECOLUMNMA 
PPINGFAILED 


DTS_E_CACHELOADEDFRO 
MFILE 


DTS_E_CACHERELOADEDDI 
FFERENTFILES 


DESCRIPTION 


Cannot map the input 
column, "%1", and the 
cache column, "%2", 
because the data types do 
not match. 


The number of input 
columns does not match 
the number of cache 
columns. 


The cache file name is either 
not provided or is not valid. 
Provide a valid cache file 
name. 


The index position of 
column, "%1", is different 
from index position of 
Cache connection manager 
column, "%2". 


Failed to load the cache 
from file, "%1". 


The lookup input column 
%1 references non-index 
cache column %2. 


Failed to get the connection 
string. 


Cannot map the input 
column, "%1", and the 
cache column, "%2", 
because one or more data 
type properties do not 
match. 


Cache column "%1" was not 
found in the cache. 


Failed to map %1 to a cache 
column. The hresult is 
0x%2!8.8X!. 


The %1 cannot write to the 
cache because the cache 
has been loaded from a file 
by %2. 


The %1 cannot load the 
cache from file "%2" 
because the cache has 
already been loaded from 
file "%3". 


HEXADECIMAL CODE 


0xC0209316 


0xC0209317 


0xC0209318 


0xC0209319 


0xC020931A 


OxCO020F42A 


Warning Messages 


DECIMAL CODE 


-1071607018 


-1071607017 


-1071607016 


-1071607015 


-1071607014 


-1071582166 


SYMBOLIC NAME 


DTS_E_OUTPUTNOTUSED 


DTS_E_CACHEFILEWRITEFAI 
LED 


DTS_E_XMLDATATYPECHAN 
GED 


DTS_E_TXLOOKUP_UNUSED 
INPUTCOLUMN 


DTS_E_SORTSTACKOVERFLO 
WwW 


DTS_E_OLEDB_OLDPROVID 
ER_ERROR 


DTS_E_INITTASKOBJECTFAIL 
ED 


DTS_E_GETCATMANAGERFA 
ILED 


DTS_E_COMPONENTINITFAI 
LED 


DESCRIPTION 


The output with ID %1!d! of 
Aggregate component is 
not used by any 
component. Please either 
remove it or associate it 
with an input of some 
component. 


The %1 failed to write the 
cache to file "%2". The 
hresult is 0x%3!8.8X!. 


The XML schema data type 
information for "%1" on 
element "%2" has changed. 
Please re-initialize the 
metadata for this 
component and review 
column mappings. 


%1 not used in join or copy. 
Please remove the unused 
column from the input 
column list. 


The sort failed due to a 
stack overflow while sorting 
an incoming buffer. Please 
reduce the 
DefaultBufferMaxRows 
property on the Data Flow 
Task. 


Consider changing the 
PROVIDER in the 
connection string to %1 or 
visit 
https://www.microsoft.com/ 
downloads to find and 
install support for %2. 


Failed to initialize the task 
object for task "%1!s!", type 
"%2!s!" due to error 
0x%3!8.8X! "%Als!". 


Failed to create COM 
Component Categories 
Manager due to error 
0x%1!8.8X! "%2!s!". 


Component %1!s! failed to 
initialize due to error 
0x%2!8.8X! "%3!s!". 


The symbolic names of Integration Services warning messages begin with DTS_W_. 


HEXADECIMAL CODE 


0x80000036 


0x80010015 


0x80012010 


0x80012011 


0x80012012 


0x80012013 


0x80012014 


0x80012015 


0x80012016 


DECIMAL CODE 


-2147483594 


-2147418091 


-2147409904 


-2147409903 


-2147409902 


-2147409901 


-2147409900 


-2147409899 


-2147409898 


SYMBOLIC NAME 


DTS_W_COUNTDOWN 


DTS_W_GENERICWARNING 


DTS_W_FAILEDXMLDOCCRE 
ATION 


DTS_W_FAILEDCONFIGLOA 
D 


DTS_W_CONFIGFILENAMEI 
NVALID 


DTS_W_CONFIGFILEINVALI 
D 


DTS_W_CONFIGFILENOTFO 
UND 


DTS_W_CONFIGKEYNOTFO 
UND 


DTS_W_CONFIGTYPEINVALI 
D 


DESCRIPTION 


There are %1!lu! days left in 
the evaluation. When it 
expires, packages will not be 
able to be executed. 


Warning(s) raised. There 
should be more specific 
warnings preceding this one 
that explain the specifics of 
the warning(s). 


Cannot create an XML 
document object instance. 
Verify that MSXML is 
installed and registered 
correctly. 


Cannot load the XML 
configuration file. The XML 
configuration file may be 
malformed or not valid. 


The configuration file name 
"%1" is not valid. Check the 
configuration file name. 


The configuration file 
loaded, but is not valid. The 
file is not formatted 
correctly, may be missing an 
element, or may be 
>damaged. 


The configuration file "%1" 
cannot be found. Check the 
directory and file name. 


Configuration registry key 
"%1" was not found. A 
configuration entry specifies 
a registry key that is not 
available. Check the 
>registry to ensure that the 
key is there. 


The configuration type in 
one of the configuration 
entries was not valid. Valid 
types are listed in the 
DTSConfigurationType 
>enumeration. 


HEXADECIMAL CODE 


0x80012017 


0x80012018 


0x80012019 


0x8001201A 


0x8001201B 


0x8001201C 


0x8001201D 


0x80012023 


DECIMAL CODE 


-2147409897 


-2147409896 


-2147409895 


-2147409894 


-2147409893 


-2147409892 


-2147409891 


-2147409885 


SYMBOLIC NAME 


DTS_W_CANNOTFINDOBJE 
CT 


DTS_W_CONFIGFORMATIN 
VALID_PACKAGEDELIMITER 


DTS_W_CONFIGFORMATIN 
VALID 


DTS_W_NOPARENTVARIABL 
ES 


DTS_W_CONFIGFILEFAILEDI 
MPORT 


DTS_W_PARENTVARIABLEN 
OTFOUND 


DTS_W_CONFIGFILEEMPTY 


DTS_W_INVALIDCONFIGUR 
ATIONTYPE 


DESCRIPTION 


The package path 
referenced an object that 
cannot be found: "%1". This 
occurs when an attempt is 
made to resolve a package 
path >to an object that 
cannot be found. 


The configuration entry, 
"%1", has an incorrect 
format because it does not 
begin with the package 
delimiter. > Prepend 
"\package" to the package 
path. 


The configuration entry 
"%1" had an incorrect 
format. This can occur 
because of a missing 
delimiter or formatting 
errors, like >an invalid array 
delimiter. 


Configuration from a parent 
variable "%1" did not occur 
because there was no 
parent variable collection. 


Failure importing 
configuration file: "%1". 


Configuration from a parent 
variable "%1" did not occur 
because there was no 
parent variable. Error code: 
0x%2!8.8X!. 


The configuration file was 
empty and contained no 
configuration entries. 


The configuration type for 
configuration "%1" is not 
valid. This may occur when 
an attempt is made to set 
the type > property of a 
configuration object to an 
invalid configuration type. 


HEXADECIMAL CODE 


0x80012025 


0x80012026 


0x80012028 


0x80012032 


0x80012033 


0x80012034 


0x80012035 


0x80012051 


0x80012052 


DECIMAL CODE 


-2147409883 


-2147409882 


-2147409880 


-2147409870 


-2147409869 


-2147409868 


-2147409867 


-2147409839 


-2147409838 


SYMBOLIC NAME 


DTS_W_REGISTRYCONFIGU 
RATIONTY PENOTFOUND 


DTS_W_REGISTRYCONFIGU 
RATIONVALUENOTFOUND 


DTS_W_PROCESSCONFIGU 
RATIONFAILEDSET 


DTS_W_CONFIGUREDVALU 
ESECTIONEMPTY 


DTS_W_CONFIGUREDTYPES 
ECTIONEMPTY 


DTS_W_PACKAGEPATHSECT 
IONEMPTY 


DTS_W_CONFIGUREDVALU 
ETYPE 


DTS_W_SQLSERVERFAILEDI 
MPORT 


DTS_W_INICONFIGURATIO 
NPROBLEM 


DESCRIPTION 


The configuration type for 
the registry configuration 
was not found in key "%1". 
Add a value called 
ConfigType >to the registry 
key and give it a string 
value of "Variable", 
"Property", 
"ConnectionManager", 
"LoggingProvider", or 
"ForEachEnumerator". 


The configuration value for 
the registry configuration 
was not found in key "%1". 
Add a value called Value to 
>the registry key of type 
DWORD or String. 


Process configuration failed 
to set the destination at the 
package path of "%1". This 
occurs when attempting to 
set >the destination 
property or variable fails. 
Check the destination 
property or variable. 


Failed to retrieve value from 
the .ini file. The 
ConfiguredValue section is 
either empty, or does not 
exist: "%1". 


Failed to retrieve value from 
the .ini file. The 
ConfiguredType section is 
either empty, or does not 
exist: "%1". 


Failed to retrieve value from 
the .ini file. The PackagePath 
section is either empty, or 
does not exist: "%1". 


Failed to retrieve value from 
the .ini file. The 
ConfiguredValueType 
section is either empty, or 
does not exist: "%1". 


Configuration from SQL 
Server was not successfully 
imported: "%1". 


The .ini configuration file is 
not valid due to empty or 
missing fields. 


HEXADECIMAL CODE 


0x80012054 


0x80012055 


0x80012057 


0x80012058 


0x80012059 


0x8001205A 


0x80014058 


DECIMAL CODE 


-2147409836 


-2147409835 


-2147409833 


-2147409832 


-2147409831 


-2147409830 


-2147401640 


SYMBOLIC NAME 


DTS_W_NORECORDSFOUN 
DINTABLE 


DTS_W_DUPLICATECUSTO 
MEVENT 


DTS_W_CONFIGREADONLY 
VARIABLE 


DTS_W_CONFIGPROCESSC 
ONFIGURATIONFAILED 


DTS_W_ONEORMORECONF 
IGLOADFAILED 


DTS_W_CONFIGNODEINVA 
LID 


DTS_W_FAILURENOTRESTAR 
TABLE 


DESCRIPTION 


Table "%1" does not have 
any records for 
configuration. This occurs 
when configuring from a 
SQL Server table that has 
no >records for the 
configuration. 


Error using same name for 
different custom events. 
The custom event "%1" was 
defined differently by 
different children of >this 
container. There may be an 
error when executing the 
event handler. 


The configuration 
attempted to change a 
read-only variable. The 
variable is at the package 
path "%1". 


Calling 
ProcessConfiguration on 
the package failed. The 
configuration attempted to 
change the property at the 
> package path "%1". 


Failed to load at least one of 
the configuration entries for 
the package. Check 
configuration entries for 
"%1" and > previous 
warnings to see 
descriptions of which 
configuration failed. 


The configuration entry 
"%1" in the configuration 
file was not valid, or failed 
to configure the variable. 
The name indicates >which 
entry failed. In some cases, 
the name will not be 
available. 


This task or container has 
failed, but because 
FailPackageOnFailure 
property is FALSE, the 
package will continue. This 
>warning is posted when 
the SaveCheckpoints 
property of the package is 
set to TRUE and the task or 
container fails. 


HEXADECIMAL CODE 


0x80017101 


0x80019002 


0x80019003 


0x80019316 


0x80019317 


0x80019318 


0x80019319 


DECIMAL CODE 


-2147389183 


-2147381246 


-2147381245 


-2147380458 


-2147380457 


-2147380456 


-2147380455 


SYMBOLIC NAME 


DTS_W_EMPTYPATH 


DTS_W_MAXIMUMERRORC 
OUNTREACHED 


DTS_W_CONFIGENVVARNO 
TFOUND 


DTS_W_CONNECTIONPROV 
IDERCHANGE 


DTS_W_READEXTMAPFAILE 
D 


DTS_W_DUPLICATEMAPPIN 
GKEY 


DTS_W_IMPLICITUPGRADE 
MAPPING 


DESCRIPTION 


The path is empty. 


SSIS Warning Code 
DTS_W_MAXIMUMERRORC 
OUNTREACHED. The 
Execution method 
succeeded, but the number 
of errors raised >(%1!d!) 
reached the maximum 
allowed (%2!d!); resulting in 
failure. This occurs when the 
number of errors reaches 
the number specified in 
MaximumeErrorCount. 
Change the 
>MaximumErrorCount or 
fix the errors. 


The configuration 
environment variable was 
not found. The environment 
variable was: "%1". This 
occurs when a package 
>specifies an environment 
variable for a configuration 
setting but it cannot be 
found. Check the 
configurations collection in 
the package and verify that 
the specified > environment 
variable is available and 
valid. 


The provider name for the 
connection manager "%1" 
has been changed from 
"%2" to "%3". 


An exception occurred while 
reading the upgrade 
mapping files. The exception 
is "%1". 


There is a duplicate 
mapping in file, "%1". The 
tag is "%2", and the key is 
"%3". 


The extension, "%1", was 
implicitly upgraded to "%2". 
Add a mapping for this 
extension to the 
UpgradeMappings 
directory. 


HEXADECIMAL CODE 


0x8001931A 


0x8001931C 


0x8001C004 


0x8001F02F 


0x8001F203 


0x8001F204 


0x8001F205 


0x8001F300 


DECIMAL CODE 


-2147380454 


-2147380452 


-2147368956 


-2147356625 


-2147356157 


-2147356156 


-2147356155 


-2147355904 


SYMBOLIC NAME 


DTS_W_INVALIDEXTENSION 
MAPPING 


DTS_W_ADOCONNECTION 
DATATYPECOMPATCHANGE 


DTS_W_FILEENUMEMPTY 


DTS_W_COULDNOTRESOLV 
EPACKAGEPATH 


DTS_W_ITERATIONEXPRESSI 
ONISNOTASSIGNMENT 


DTS_W_INITIALIZATIONEXP 
RESSIONISNOTASSIGNMEN 
T 


DTS_W_LOGPROVIDERNOT 
DEFINED 


DTS_W_PACKAGEUPGRADE 
D 


DESCRIPTION 


A mapping in the file, "%1", 
is not valid. Values cannot 
be null or empty. The tag is 
"%2", the key is "%3", and 
the value >is "%4". 


The DataTypeCompatibility 
property of ADO type 
connection manager "%1" 
was set to 80 for backward 
compatibility >reasons. 


The For Each File 
enumerator is empty. The 
For Each File enumerator 
did not find any files that 
matched the file pattern, or 
the >specified directory was 
empty. 


Cannot resolve a package 
path to an object in the 

package "%1". Verify that 
the package path is valid. 


The iteration expression is 
not an assignment 
expression: "%1". This error 
usually occurs when the 
expression >in the 
assignment expression on 
the ForLoop is not an 
assignment expression. 


The initialization expression 
is not an assignment 
expression: "%1". This error 
usually occurs when the 
>expression in the iterate 
expressions on the ForLoop 
is not an assignment 
expression. 


The executable "%1" was 
pasted successfully. 
However a log provider that 
was associated with the 
executable was not found in 
>the collection 
"LogProviders". The 
executable was pasted 
without log provider 
information. 


Succeeded in upgrading the 
package. 


HEXADECIMAL CODE 


0x8001F42B 


0x80020918 


0x800283A5 


0x80029164 


0x80029185 


0x800291C6 


0x800291C7 


0x800291C8 


0x8002927A 


0x8002928C 


0x8002928D 


0x80029291 


0x80029292 


0x8002F304 


DECIMAL CODE 


-2147355605 


-2147350248 


-2147318875 


-2147315356 


-2147315323 


-2147315258 


-2147315257 


-2147315256 


-2147315078 


-2147315060 


-2147315059 


-2147315055 


-2147315054 


-2147290364 


SYMBOLIC NAME 


DTS_W_LEGACYPROGID 


DTS_W_FTPTASK_OPERATIO 
NFAILURE 


DTS_W_MSMQTASK_USE_W 
EAK_ENCRYPTION 


DTS_W_FSTASK_OPERATION 
FAILURE 


DTS_W_EXECPROCTASK_FIL 
ENOTINPATH 


DTS_W_SENDMAILTASK_SU 
BJECT_MISSING 


DTS_W_SENDMAILTASK_ER 
ROR_IN_TO_LINE 


DTS_W_SENDMAILTASK_AT_ 
MISSING_IN_FROM 


DTS_W_XMLTASK_DIFFFAIL 
URE 


DTS_W_XMLTASK_DTDVALI 
DATIONWARNING 


DTS_W_XMLTASK_VALIDATI 
ONFAILURE 


DTS_W_TRANSFERDBTASK_ 
ACTIONSETTOCOPY 


DTS_W_TRANSFERDBTASK_ 
METHODSETTOONLINE 


DTS_W_PROBLEMOCCURRE 
DWITHFOLLOWINGMESSA 
GE 


DESCRIPTION 


The "%1" ProglD has been 
deprecated. The new 
ProgID for this component 
"%2" should be used 
instead. 


Operation "%1" failed. 


The encryption algorithm 
"%1" uses weak encryption. 


Task failed to execute 
operation "%1". 


File/Process "%1" is not in 
path. 


The subject is empty. 


The address in the "To" line 
is malformed. It is either 
missing the "@" symbol or 
is not valid. 


The address in the "From" 
line is malformed. It is either 
missing the "@" symbol or 
is not valid. 


The two XML documents 
are different. 


DTD Validation will use the 
DTD file defined in the 
DOCTYPE line in the XML 
document. It will not use 
what is > assigned to the 
property "%1". 


Task failed to validate "%1". 


The transfer action value 
was invalid. It is being set to 


copy. 


The transfer method value 
was invalid. It is being set to 
an online transfer. 


A problem occurred with 
the following messages: 
n964" 


HEXADECIMAL CODE 


0x8002F322 


0x8002F331 


0x8002F332 


0x8002F333 


0x8002F339 


0x8002F343 


0x8002F356 


0x8002F360 


0x8002F364 


0x8002F368 


0x8002F372 


0x8002F376 


0x8002F380 


0x8002F384 


0x8002F388 


0x8002F391 


DECIMAL CODE 


-2147290334 


-2147290319 


-2147290318 


-2147290317 


-2147290311 


-2147290301 


-2147290282 


-2147290272 


-2147290268 


-2147290264 


-2147290254 


-2147290250 


-2147290240 


-2147290236 


-2147290232 


-2147290223 


SYMBOLIC NAME 


DTS_W_ERRMSGTASK_ERRO 
RMESSAGEALREADY EXISTS 


DTS_W_JOBSTASK_JOBEXIST 
SATDEST 


DTS_W_JOBSTASK_SKIPPIN 
GJOBEXISTSATDEST 


DTS_W_JOBSTASK_OVERWR 
ITINGJOB 


DTS_W_LOGINSTASK_ENUM 
VALUEINCORRECT 


DTS_W_LOGINSTASK_OVER 
WRITINGLOGINATDEST 


DTS_W_TRANSOBJECTSTAS 
K_SPALREADYATDEST 


DTS_W_TRANSOBJECTSTAS 
K_RULEALREADYATDEST 


DTS_W_TRANSOBJECTSTAS 
K_TABLEALREADYATDEST 


DTS_W_TRANSOBJECTSTAS 
K_VIEWALREADYATDEST 


DTS_W_TRANSOBJECTSTAS 
K_UDFALREADYATDEST 


DTS_W_TRANSOBJECTSTAS 
K_DEFAULTALREADYATDEST 


DTS_W_TRANSOBJECTSTAS 
K_UDDTALREADYATDEST 


DTS_W_TRANSOBJECTSTAS 
K_PFALREADYATDEST 


DTS_W_TRANSOBJECTSTAS 
K_PSALREADYATDEST 


DTS_W_TRANSOBJECTSTAS 
K_SCHEMAALREADYATDEST 


DESCRIPTION 


The error message "%1" 
already exists at destination 
server. 


The job "%1" already exists 
at destination server. 


Skipping the transfer of job 
"%1" since it already exists 
at destination. 


Overwriting the job "%1" at 
destination server. 


Persisted enumeration value 
of property "FaillfExists" was 
changed and rendered 

invalid. Resetting to default. 


Overwriting Login "%1" at 
destination. 


Stored procedure "%1" 
already exists at destination. 


Rule "%1" already exists at 
destination. 


Table "%1" already exists at 
destination. 


View "%1" already exists at 
destination. 


User Defined Function "%1" 
already exists at destination. 


Default "%1" already exists 
at destination. 


User Defined Data Type 
"%1" already exists at 
destination. 


Partition Function "%1" 
already exists at destination. 


Partition Scheme "%1" 
already exists at destination. 


Schema "%1" already exists 
at destination. 


HEXADECIMAL CODE 


0x8002F396 


0x8002F400 


0x8002F404 


0x8002F408 


0x8002F412 


0x8002F415 


0x8002F41A 


0x80047007 


0x80047034 


0x80047069 


0x8004706F 


0x80047076 


DECIMAL CODE 


-2147290218 


-2147290112 


-2147290108 


-2147290104 


-2147290094 


-2147290091 


-2147290086 


-2147192825 


-2147192780 


-2147192727 


-2147192721 


-2147192714 


SYMBOLIC NAME 


DTS_W_TRANSOBJECTSTAS 
K_SQLASSEMBLYALREADYA 
TDEST 


DTS_W_TRANSOBJECTSTAS 
K_AGGREGATEALREADYATD 
EST 


DTS_W_TRANSOBJECTSTAS 
K_TYPEALREADYATDEST 


DTS_W_TRANSOBJECTSTAS 
K_XMLSCHEMACOLLECTIO 
NALREADYATDEST 


DTS_W_TRANSOBJECTSTAS 
K_NOELEMENTSPECIFIEDTO 
TRANSFER 


DTS_W_TRANSOBJECTSTAS 
K_LOGINALREADYATDEST 


DTS_W_TRANSOBJECTSTAS 
K_USERALREADYATDEST 


DTS_W_NOLINEAGEVALIDA 
TION 


DTS_W_EMPTYDATAFLOW 


DTS_W_SORTEDOUTPUTHA 
SNOSORTKEYPOSITIONS 


DTS_W_SOURCEREMOVED 


DTS_W_UNUSEDOUTPUTD 
ATA 


DESCRIPTION 


SqlAssembly "%1" already 
exists at destination. 


User Defined Aggregate 
"%1" already exists at 
destination. 


User Defined Type "%1" 
already exists at destination. 


XmlSchemaCollection "%1" 
already exists at destination. 


There are no elements 
specified to transfer. 


Login "%1" already exists at 
destination. 


User "%1" already exists at 
destination. 


The lineage IDs of the input 
columns cannot be 
validated because the 
execution trees contain 
cycles. 


The DataFlow task has no 
components. Add 
components or remove the 
task. 


The IsSorted property of 
%1 is set to TRUE, but all of 
its output columns' 
SortKeyPositions are set to 
zero. 


Source "%1" (%2!d!) will not 
be read because none of its 
data ever becomes visible 

outside the Data Flow Task. 


The output column "%1" 
(%2!d!) on output "%3" 
(%A!d!) and component 
"%5" (%6!d!) is not 
subsequently used in the 
Data Flow task. >Removing 
this unused output column 
can increase Data Flow task 
performance. 


HEXADECIMAL CODE 


0x800470AE 


0x800470B0 


0x800470C8 


0x800470C9 


0x800470CA 


0x800470CB 


0x800470D8 


DECIMAL CODE 


-2147192658 


-2147192656 


-2147192632 


-2147192631 


-2147192630 


-2147192629 


-2147192616 


SYMBOLIC NAME 


DTS_W_COMPONENTREM 
OVED 


DTS_W_NOWORKTODO 


DTS_W_EXTERNALMETADAT 
ACOLUMNSOUTOFSYNC 


DTS_W_EXTERNALMETADAT 
ACOLUMNCOLLECTIONNE 
EDSADDITION 


DTS_W_EXTERNALMETADAT 
ACOLUMNCOLLECTIONNE 
EDSUPDATE 


DTS_W_EXTERNALMETADAT 
ACOLUMNCOLLECTIONNE 
EDSREMOVAL 


DTS_W_EXPREVALPOTENTIA 
LSTRINGTRUNCATION 


DESCRIPTION 


Component "%1" (%2!d!) 
has been removed from the 
Data Flow task because its 
output is not used and its 
inputs either have no side 

> effects or are not 
connected to outputs of 
other components. If the 
component is required, 
then the HasSideEffects 
property on at least one of 
its inputs should be set to 
true, >or its output should 
be connected to something. 


Rows were given to a 
thread, but that thread has 
no work to do. The layout 
has a disconnected output. 
Running the pipeline with 
the >RunInOptimizedMode 
property set to TRUE will be 
faster, and prevents this 
warning. 


The external columns for 
%1 are out of 

synchronization with the 
data source columns. %2 


The column "%1" needs to 
be added to the external 
columns. 


The external column "%1" 
needs to be updated. 


The %1 needs to be 
removed from the external 
columns. 


The result string for 
expression "%1" may be 
truncated if it exceeds the 
maximum length of %2!d! 
characters. The > expression 
could have a result value 
that exceeds the maximum 
size of a DT_WSTR. 


HEXADECIMAL CODE 


0x800470E9 


0x800470EB 


0x8004801E 


0x80049300 


0x80049301 


0x80049304 


0x8020200F 


DECIMAL CODE SYMBOLIC NAME 


-2147192599 DTS_W_COMPONENTLEAK 
PROCESSINPUT 

-2147192597 DTS_W_EXPREVALUNREFER 
ENCEDINPUTCOLUMN 

-2147188706 DTS_W_COULDNOTFINDCU 
RRENTVERSION 

-2147183872 DTS_W_BUFFERGETTEMPFIL 
ENAME 

-2147183871 DTS_W_UNUSABLETEMPOR 
ARYPATH 

-2147183868 DTS_W_DF_PERFCOUNTERS 
_DISABLED 

-2145378289 DTS_W_PARTIALROWFOUN 


DATENDOFFILE 


DESCRIPTION 


A call to the ProcessInput 
method for input %1!d! on 
%2 unexpectedly kept a 
reference to the buffer it 
was passed. The >refcount 
on that buffer was %3!d! 
before the call, and %4!d! 
after the call returned. 


The "%1" on "%2" has 
usage type READONLY, but 
is not referenced by an 
expression. Remove the 
column from the list >of 
available input columns, or 
reference it in an 
expression. 


Cannot find the "%1" value 
for component %2. The 
CurrentVersion value for 
the component cannot be 
located. This error > occurs 
if the component has not 
set its registry information 
to contain a CurrentVersion 
value in the DTSInfo section. 
This message occurs during 
component development, 
or when >the component is 
used in a package, if the 
component is not 
registered properly. 


The buffer manager could 
not get a temporary file 
name. 


The buffer manager could 
not create a temporary file 
on the path "%1". The path 
will not be considered for 
temporary storage >again. 


Warning: Could not open 
global shared memory to 
communicate with 
performance DLL; data flow 
performance counters are 
not >available. To resolve, 
run this package as an 
administrator, or on the 
system's console. 


There is a partial row at the 
end of the file. 


HEXADECIMAL CODE 


0x8020202B 


0x80202066 


0x802020F7 


0x8020400D 


0x802070CC 


0x8020820C 


0x80208305 


DECIMAL CODE 


-2145378261 


-2145378202 


-2145378057 


-2145370099 


-2145357620 


-2145353204 


-2145352955 


SYMBOLIC NAME 


DTS_W_ENDOFFILEREACH 
WHILEREADINGHEADERRO 
WS 


DTS_W_CANTRETRIEVECOD 
EPAGEFROMOLEDBPROVID 
ER 


DTS_W_TXSORTSORTISTHES 
AME 


DTS_W_NOPIPELINEDATATY 
PEMAPPINGAVAILABLE 


DTS_W_STATICTRUNCATIO 
NINEXPRESSION 


DTS_W_UNMAPPEDINPUTC 
OLUMN 


DTS_W_TXFUZZYLOOKUP_ 
DELIMITERS_DONT_MATCH 


DESCRIPTION 


The end of the data file was 
reached while reading 
header rows. Make sure the 
header row delimiter and 
the >number of header 
rows to skip are correct. 


Cannot retrieve the column 
code page info from the 
OLE DB provider. If the 
component supports the 
"%1" >property, the code 
page from that property 
will be used. Change the 
value of the property if the 
current string code page 
values are incorrect. If the 
component does not 
>support the property, the 
code page from the 
component's locale ID will 
be used. 


The data is already sorted 
as specified so the 
transform can be removed. 


The %1 references an 
external data type that 
cannot be mapped to a 
Data Flow task data type. 
The Data Flow task >data 
type DT_WSTR will be used 
instead. 


The expression "%1" will 
always result in a truncation 
of data. The expression 
contains a static truncation 
(the >truncation of a fixed 
value). 


The input column "%1" with 
ID %2!d! at index %3!d! is 
unmapped. The lineage ID 
for the column is zero. 


The specified delimiters do 
not match the delimiters 
used to build the pre- 
existing match index "%1". 
This >error occurs when the 
delimiters used to tokenize 
fields do not match. This 
can have unknown effects 
on the matching behavior 
or results. 


HEXADECIMAL CODE 


0x80208308 


0x80208310 


0x8020831C 


0x80208321 


0x8020832B 


0x8020832D 


DECIMAL CODE 


-2145352952 


-2145352944 


-2145352932 


-2145352927 


-2145352917 


-2145352915 


SYMBOLIC NAME 


DTS_W_TXFUZZYLOOKUP_ 
MAXRESULTS_IS_ZERO 


DTS_W_TXFUZZYLOOKUP_ 
NO_FUZZY_JOIN_COLUMN 
S 


DTS_W_TXFUZZYLOOKUP_T 
IMESTAMPCAVEAT 


DTS_W_MATCHINDEXALRE 
ADYEXISTS 


DTS_W_TXFUZZYLOOKUP_J 
OINLENGTHMISMATCH 


DTS_W_TXFUZZYLOOKUP_ 
CODEPAGE_MISMATCH 


DESCRIPTION 


The 
MaxOutputMatchesPerlnpu 
t property on the Fuzzy 
Lookup transformation is 
zero. No results will be 
produced. 


There were no valid input 
columns with JoinType 
column property set to 
Fuzzy. Performance on Exact 
joins may >be improved by 
using the Lookup transform 
instead of FuzzyLookup. 


The reference column "%1" 
may be a SQL timestamp 
column. When the fuzzy 
match index is built, and a 
copy of the >reference 
table is made, all reference 
table timestamps will reflect 
the current state of the 
table at the time of the 
copy. Unexpected behavior 
may occur if the 

> CopyReferenceTable is set 
to false. 


A table with the name '%1' 
given for MatchIndexName 
already exists and 
DropExistingMatchIndex is 
set to FALSE. Transform 
>execution will fail unless 
this table is dropped, a 
different name is specified, 
or DropExisitingMatchIndex 
is set to TRUE. 


The length of input column 
'%1' is not equal to the 
length of the reference 
column '%2' that it is being 
matched > against. 


The code pages of the 
DT_STR source column "%1" 
and the DT_STR dest 
column "%2" do not match. 
This may cause 
>unexpected results. 


HEXADECIMAL CODE 


0x8020832E 


0x80208350 


0x80208351 


0x80208352 


0x80208353 


DECIMAL CODE 


-2145352914 


-2145352880 


-2145352879 


-2145352878 


-2145352877 


SYMBOLIC NAME 


DTS_W_FUZZYLOOKUP_TO 
OMANYEXACTMATCHCOL 
UMNS 


DTS_W_FUZZYLOOKUP_ME 
MLIMITANDEXHAUSTIVESP 
ECIFIED 


DTS_W_FUZZYLOOKUP_EX 
ACTMATCHCOLUMNSEXCE 
EDBYTELIMIT 


DTS_W_FUZZYLOOKUP_EX 
ACTMATCHINDEXCREATIO 
NFAILED 


DTS_W_FUZZYGROUPINGI 
NTERNALPIPELINEWARNIN 
G 


DESCRIPTION 


There are more than 16 
exact match joins, so 
performance may not be 
optimal. Reduce the number 
of exact match >joins to 
improve performance. SQL 
Server has a limit of 16 
columns per index, the 
inverted index will be used 
for all lookups. 


The Exhaustive option 
requires that the entire 
reference be loaded into 
main memory. Since a 
memory >limit has been 
specified for the 
MaxMemoryUsage 
property, it is possible that 
the entire reference table 
will not fit within this bound 
and that the match 
operation will fail >at 
runtime. 


The cumulative lengths of 
the columns specified in the 
exact match joins exceeds 
the 900 byte limit >for 
index keys. Fuzzy Lookup 
creates an index on the 
exact match columns to 
increase lookup 
performance and there is a 
possibility that creation of 
this index may fail and the 
>lookup will fall back to an 
alternative, possibly slower, 
method of finding matches. 
If performance is a problem, 
try removing some exact 
match join columns or 
reduce the >maximum 
lengths of variable length 
exact match columns. 


Failed to create an index for 
exact match columns. 
Reverting to alternative 
fuzzy lookup method. 


The following Fuzzy 
Grouping internal pipeline 
warning occurred with 
warning code 0x%1!8.8X!: 
"%2". 


HEXADECIMAL CODE 


0x80208375 


0x80208376 


0x80208385 


0x80208386 


0x80208391 


0x802090E4 


DECIMAL CODE 


-2145352843 


-2145352842 


-2145352827 


-2145352826 


-2145352815 


-2145349404 


SYMBOLIC NAME 


DTS_W_XMLSRCOUTPUTCO 
LUMNLENGTHSETTODEFAU 
LT 


DTS_W_XMLSRCOUTPUTCO 
LUMNDATATY PEMAPPEDT 
OSTRING 


DTS_W_NOREDIRECTWITHA 
TTACHEDERROROUTPUTS 


DTS_W_REDIRECTWITHNOA 
TTACHEDERROROUTPUTS 


DTS_W_XMLSRCOUTPUTCO 
LUMNLENGTHSETTOMAXI 
MUM 


DTS_W_TXLOOKUP_DUPLIC 
ATE_KEYS 


DESCRIPTION 


No maximum length was 
specified for the %1 with 
external data type %2. The 
SSIS Data Flow Task data 
type "%3" >with a length of 
%A!d! will be used. 


The %1 references external 
data type %2, which cannot 
be mapped to a SSIS Data 
Flow Task data type. The 
>SSIS Data Flow Task data 
type DT_WSTR with a length 
of %3!d! will be used 
instead. 


No rows will be sent to 
error output(s). Configure 
error or truncation 
dispositions to redirect rows 
to the >error output(s), or 
delete data flow 
transformations or 
destinations that are 
attached to the error 
output(s). 


Rows sent to the error 
output(s) will be lost. Add 
new data flow 
transformations or 
destinations to receive 
>error rows, or reconfigure 
the component to stop 
redirecting rows to the 
error output(s). 


For the %1 with external 
data type %2, the XML 
schema specified a 
maxLength constraint of 
%3!d!, which >exceeds the 
maximum allowed column 
length of %4!d!. The SSIS 
Data Flow Task data type 
"%5" with a length of %6!d! 
will be used. 


The %1 encountered 
duplicate reference key 
values when caching 
reference data. This error 
occurs in Full Cache mode 
only. >Either remove the 
duplicate key values, or 
change the cache mode to 
PARTIAL or NO_CACHE. 


HEXADECIMAL CODE 


0x802092A7 


0x802092A8 


0x802092AA 


0x802092AB 


0x802092AC 


0x802092AD 


DECIMAL CODE 


-2145348953 


-2145348952 


-2145348950 


-2145348949 


-2145348948 


-2145348947 


SYMBOLIC NAME 


DTS_W_POTENTIALTRUNCA 
TIONFROMDATAINSERTION 


DTS_W_POTENTIALTRUNCA 
TIONFROMDATARETRIEVAL 


DTS_W_ADODESTBATCHNO 
TSUPPORTEDFORERRORDIS 
POSITION 


DTS_W_ADODESTNOROWS 
INSERTED 


DTS_W_ADODESTPOTENTIA 
LDATALOSS 


DTS_W_ADODESTEXTERNAL 
COLNOTMATCHSCHEMAC 
OL 


DESCRIPTION 


Truncation may occur due 
to inserting data from data 
flow column "%1" with a 
length of %2!d! to database 
>column "%3" with a length 
of %4!d!. 


Truncation may occur due 
to retrieving data from 
database column "%1" with 
a length of %2!d! to data 
flow >column "%3" with a 
length of %4!d!. 


Batch mode is not currently 
supported when error row 
disposition is used. The 
BatchSize property will >be 
set to 1. 


No rows were successfully 
inserted into the 
destination. This may be 
due to a data type 
mismatch between 
columns, or due to >the 
use of a datatype that is 
unsupported by your 
ADO.NET provider. Since the 
error disposition for this 
component is not "Fail 
component", error 
messages are not shown 
here; >set the error 
disposition to "Fail 
component" to see error 
messages here. 


Potential data loss may 
occur due to inserting data 
from input column "%1" 
with data type "%2" to 
external column "%3" >with 
data type "%4". If this is 
intended, an alternative way 
to do conversion is using a 
Data Conversion 
component before ADO 
NET destination 
component. 


The %1 has been out of 
synchronization with the 
database column. The latest 
column has %2. Use 
advanced > editor to refresh 
available destination 
columns if needed. 


HEXADECIMAL CODE 


Ox802092AE 


0x802092AF 


0x8020930C 


0x8020931B 


0xC020822C 


0x930D 


DECIMAL CODE 


-2145348946 


-2145348945 


-2145348852 


-2145348837 


-1071611348 


37645 


Informational Messages 


The symbolic names of Integration Services informational messages begin with DTS_I_. 


HEXADECIMAL CODE 


0x4001100A 


0x4001100B 


DECIMAL CODE 


1073811466 


1073811467 


SYMBOLIC NAME 


DTS_W_ADODESTEXTERNAL 
COLNOTEXIST 


DTS_W_ADODESTNEWEXTC 
OL 


DTS_W_NOMATCHOUTPUT 
GETSNOROWS 


DTS_W_ADODESTINVARIAN 
TEXCEPTION 


DTS_W_UNMAPPEDOUTPU 
TCOLUMN 


DTS_W_EXTERNALTABLECO 
LSOUTOFSYNC 


SYMBOLIC NAME 


DTS_|_STARTINGTRANSACTI 
ON 


DTS_|_COMMITTINGTRANS 
ACTION 


DESCRIPTION 


The %1 does not exist in 
the database. It may have 
been removed or renamed. 
Use Advanced Editor to 
refresh the > available 
destination columns if 
needed. 


A new column with name 
%1 has been added to the 
external database table. Use 
advanced editor to refresh 
available destination 
>columns if needed. 


No rows will be sent to the 
no match output. Configure 
the transformation to 
redirect rows with no 
matching entries to the 
>no match output, or 
delete the data flow 
transformations or 
destinations that are 
attached to the no match 
output. 


Exception received while 
enumerating ADO.Net 
providers. The invariant was 
"%1". The exception 
message is: "%2" 


The %1 has no input 
column mapped to it. 


The table "%1" has 
changed. New columns 
might have been added to 
the table. 


DESCRIPTION 


Starting distributed 
transaction for this 
container. 


Committing distributed 
transaction started by this 
container. 


HEXADECIMAL CODE 


0x4001100C 


0x40013501 


0x40013502 


0x40013503 


0x40015101 


0x40015102 


0x40015103 


0x40015104 


0x40015106 


0x40016019 


0x4001601A 


0x40016025 


0x40016026 


0x40016027 


0x40016028 


DECIMAL CODE 


1073811468 


1073820929 


1073820930 


1073820931 


1073828097 


1073828098 


1073828099 


1073828100 


1073828102 


1073831961 


1073831962 


1073831973 


1073831974 


1073831975 


1073831976 


SYMBOLIC NAME 


DTS_|_ABORTINGTRANSACT 
ION 


DTS_|_ GOTMUTEXFROMWA 
IT 


DTS_|_RELEASEACQUIREDM 
UTEX 


DTS_I_NEWMUTEXCREATED 


DTS_|_ DUMP_ON_ANY_ERR 


DTS_|_ DUMP_ON_CODES 


DTS_I_START_DUMP 


DTS_I_SSIS_INFO_DUMP 


DTS_|_FINISH_DUMP 


DTS_|_PACKAGEMIGRATED 


DTS_I_SCRIPTSMIGRATED 


DTS_|_FTPRECEIVEFILE 


DTS_|_FTPSENDFILE 


DTS_|_FTPFILEEXISTS 


DTS_|_FTPERRORLOADING 
MSG 


DESCRIPTION 


Aborting the current 
distributed transaction. 


Mutex "%1" was 
successfully acquired. 


Mutex "%1" was 
successfully released. 


Mutex "%1" was 
successfully created. 


Debug dump files will be 
generated for any error 
event. 


Debug dump files will be 
generated for the following 
event codes: "%1" 


Event code, 0x%1!8.8X!, 
triggered generation of 
debug dump files in the 
folder "%2". 


Creating SSIS information 
dump file "%1". 


Debug dump files 
successfully created. 


The package format was 
migrated from version 
%1!d! to version %2!dl. It 
must be saved to retain 
migration changes. 


The scripts in the package 
were migrated. The package 
must be saved to retain 
migration changes. 


Receiving file "%1". 


Sending file "%1". 


File "%1" already exists. 


Cannot get extra error 
information due to an 
internal error. 


HEXADECIMAL CODE 


0x40016036 


0x40016037 


0x40016038 


0x40016039 


0x40016040 


0x40016041 


0x40016042 


0x40016043 


0x40016044 


0x40016045 


0x40016046 


DECIMAL CODE 


1073831990 


1073831991 


1073831992 


1073831993 


1073832000 


1073832001 


1073832002 


1073832003 


1073832004 


1073832005 


1073832006 


SYMBOLIC NAME 


DTS_|_FTPDELETEFILE 


DTS_|_CONFIGFROMREG 


DTS_|_CONFIGFROMENVVA 
R 


DTS_|_CONFIGFROMINIFILE 


DTS_|_CONFIGFROMSQLSE 
RVER 


DTS_|_CONFIGFROMFILE 


DTS_|_CONFIGFROMPAREN 
TVARIABLE 


DTS_|_ATTEMPTINGUPGRA 
DEOFDTS 


DTS_|_ATTEMPTINGUPGRA 
DEOFANEXTOBJ 


DTS_I_SAVECHECKPOINTST 
OFILE 


DTS_|_RESTARTFROMCHEC 
KPOINTFILE 


DESCRIPTION 


The attempt to delete file 
"%1" failed. This may occur 
when the file does not exist, 
the file name was spelled 
incorrectly, or you do not 
have permissions to delete 
the file. 


The package is attempting 
to configure from a registry 
entry using the registry key 
"%1". 


The package is attempting 
to configure from the 
environment variable "%1". 


The package is attempting 
to configure from the .ini 
file "%1". 


The package is attempting 
to configure from SQL 
Server using the 
configuration string "%1". 


The package is attempting 
to configure from the XML 
file "%1". 


The package is attempting 
to configure from the 
parent variable "%1". 


Attempting an upgrade of 
SSIS from version "%1" to 
version "%2". The package 
is attempting to upgrade 
the runtime. 


Attempting to upgrade 
"%1". The package is 
attempting to upgrade an 
extensible object. 


The package will be saving 
checkpoints to file "%1" 
during execution. The 
package is configured to 
save checkpoints. 


The package restarted from 
checkpoint file "%1". The 
package was configured to 
restart from checkpoint. 


HEXADECIMAL CODE 


0x40016047 


0x40016048 


0x40016049 


0x40016051 


0x40016052 


0x40016053 


0x40016054 


0x40029161 


0x40029162 


0x400292A8 


0x4002F304 


0x4002F323 


0x4002F326 


0x4002F351 


0x4002F352 


0x4002F358 


DECIMAL CODE 


1073832007 


1073832008 


1073832009 


1073832017 


1073832018 


1073832019 


1073832020 


1073910113 


1073910114 


1073910440 


1073935108 


1073935139 


1073935142 


1073935185 


1073935186 


1073935192 


SYMBOLIC NAME 


DTS_I_CHECKPOINTSAVEDT 
OFILE 


DTS_|_CHECKPOINTFILEDEL 
ETED 


DTS_|_CHECKPOINTSAVING 
TOFILE 


DTS_|_CHOSENMAXEXECUT 
ABLES 


DTS_|_MAXEXECUTABLES 


DTS_|_PACKAGESTART 


DTS_|_PACKAGEEND 


DTS_|_FSTASK_DIRECTORYD 
ELETED 


DTS_|_FSTASK_FILEDELETED 


DTS_|_TRANSFERDBTASK_O 
VERWRITEDB 


DTS_|_SOMETHINGHAPPEN 
ED 


DTS_|_ERRMSGTASK_SKIPPI 
NGERRORMESSAGEALREAD 
YEXISTS 


DTS_|_ERRMSGTASK_TRANS 
FEREDNERRORMESSAGES 


DTS_|_STOREDPROCSTASKS 
_TRANSFEREDNSPS 


DTS_I_TRANSOBJECTSTASK_ 
TRANSFEREDNOBJECTS 


DTS_I_TRANSOBJECTSTASK_ 
NOSPSTOTRANSFER 


DESCRIPTION 


Checkpoint file "%1" was 
updated to record 
completion of this container. 


Checkpoint file "%1" was 
deleted after successful 
completion of the package. 


Checkpoint file "%1" update 
starting. 


Based on the system 
configuration, the maximum 
concurrent executables are 
set to %1!d!. 


Maximum concurrent 
executables are set to 
%1'd!. 


Beginning of package 
execution. 


End of package execution. 


Directory "%1" was deleted. 


File or directory "%1" was 
deleted. 


Overwriting the database 
"%1" on the destination 
server "%2". 


"%1". 


Skipping error message 
"%1" since it already exists 
on the destination server. 


"%1" Error Messages were 
transferred. 


The task transferred "%1" 
Stored Procedures. 


Transferred "%1" objects. 


There are no Stored 
Procedures to transfer. 


HEXADECIMAL CODE 


0x4002F362 


0x4002F366 


0x4002F370 


0x4002F374 


0x4002F378 


0x4002F382 


0x4002F386 


0x4002F390 


0x4002F394 


0x4002F398 


0x4002F402 


0x4002F406 


0x4002F410 


0x4002F418 


0x4002F41D 


Ox4002F41E 


0x40043006 


DECIMAL CODE 


1073935202 


1073935206 


1073935216 


1073935220 


1073935224 


1073935234 


1073935238 


1073935248 


1073935252 


1073935256 


1073935362 


1073935366 


1073935376 


1073935384 


1073935389 


1073935390 


1074016262 


SYMBOLIC NAME 


DTS_I_TRANSOBJECTSTASK_ 
NORULESTOTRANSFER 


DTS_I_TRANSOBJECTSTASK_ 
NOTABLESTOTRANSFER 


DTS_I_TRANSOBJECTSTASK_ 
NOVIEWSTOTRANSFER 


DTS_I|_TRANSOBJECTSTASK_ 
NOUDFSTOTRANSFER 


DTS_I_TRANSOBJECTSTASK_ 
NODEFAULTSTOTRANSFER 


DTS_I_TRANSOBJECTSTASK_ 
NOUDDTSTOTRANSFER 


DTS_I_TRANSOBJECTSTASK_ 
NOPFSTOTRANSFER 


DTS_I_TRANSOBJECTSTASK_ 
NOPSSTOTRANSFER 


DTS_I_TRANSOBJECTSTASK_ 
NOSCHEMASTOTRANSFER 


DTS_I_TRANSOBJECTSTASK_ 
NOSQLASSEMBLIESTOTRA 
NSFER 


DTS_I|_TRANSOBJECTSTASK_ 
NOAGGREGATESTOTRANSF 
ER 


DTS_I_TRANSOBJECTSTASK_ 
NOTYPESTOTRANSFER 


DTS_I_TRANSOBJECTSTASK_ 
NOXMLSCHEMACOLLECTI 
ONSTOTRANSFER 


DTS_I_TRANSOBJECTSTASK_ 
NOLOGINSTOTRANSFER 


DTS_I_TRANSOBJECTSTASK_ 
NOUSERSTOTRANSFER 


DTS_I_TRANSOBJECTSTASK_ 
TRUNCATINGTABLE 


DTS_|_EXECUTIONPHASE_P 
REPAREFOREXECUTE 


DESCRIPTION 


There are no Rules to 
transfer. 


There are no Tables to 
transfer. 


There are no Views to 
transfer. 


There are no User Defined 
Functions to transfer. 


There are no Defaults to 
transfer. 


There are no User Defined 
Data Types to transfer. 


There are no Partition 
Functions to transfer. 


There are no Partition 
Schemes to transfer. 


There are no Schemas to 
transfer. 


There are no SqlAssemblies 
to transfer. 


There are no User Defined 
Aggregates to transfer. 


There are no User Defined 
Types to transfer. 


There are no 
XmlSchemaCollections to 
transfer. 


There are no Logins to 
transfer. 


There are no Users to 
transfer. 


Truncating table "%1" 


Prepare for Execute phase is 
beginning. 


HEXADECIMAL CODE 


0x40043007 


0x40043008 


0x40043009 


0x4004300A 


0x4004300B 


0x4004300C 


0x4004800C 


0x4004800D 


0x4004800E 


0x400490F4 


DECIMAL CODE 


1074016263 


1074016264 


1074016265 


1074016266 


1074016267 


1074016268 


1074036748 


1074036749 


1074036750 


1074041076 


SYMBOLIC NAME 


DTS_|_EXECUTIONPHASE_P 
REEXECUTE 


DTS_|_EXECUTIONPHASE_P 
OSTEXECUTE 


DTS_|_EXECUTIONPHASE_C 
LEANUP 


DTS_|_EXECUTIONPHASE_V 
ALIDATE 


DTS_|_ROWS_WRITTEN 


DTS_|_EXECUTIONPHASE_E 
XECUTE 


DTS_|_CANTRELIEVEPRESSU 
RE 


DTS_|_CANTALLOCATEMEM 
ORYPRESSURE 


DTS_|_ALLOCATEDDURING 
MEMORYPRESSURE 


DTS_|_TXLOOKUP_CACHE_P 
ROGRESS 


DESCRIPTION 


Pre-Execute phase is 
beginning. 


Post Execute phase is 
beginning. 


Cleanup phase is beginning. 


Validation phase is 
beginning. 


"%1" wrote %2!Id! rows. 


Execute phase is beginning. 


The buffer manager 
detected that the system 
was low on virtual memory, 
but was unable to swap out 
any buffers. %1!d! buffers 
were considered and %2!d! 
were locked. Either not 
enough memory is available 
to the pipeline because not 
enough is installed, other 
processes are using it, or 
too many buffers are 
locked. 


The buffer manager failed a 
memory allocation call for 
%3!d! bytes, but was unable 
to swap out any buffers to 
relieve memory pressure. 
%1!d! buffers were 
considered and %2!d! were 
locked. Either not enough 
memory is available to the 
pipeline because not 
enough are installed, other 
processes were using it, or 
too many buffers are 
locked. 


The buffer manager has 
allocated %1!d! bytes, even 
though the memory 
pressure has been detected 
and repeated attempts to 
swap buffers have failed. 


%1 has cached %2!d! rows. 


HEXADECIMAL CODE 


0x400490F5 


0x4020206D 


0x402020DA 


0x40208327 


0x40208328 


0x40208387 


0x402090DA 


DECIMAL CODE 


1074041077 


1075847277 


1075847386 


1075872551 


1075872552 


1075872647 


1075876058 


SYMBOLIC NAME 


DTS_|_TXLOOKUP_CACHE_F 
INAL 


DTS_|_RAWSOURCENOCOL 
UMNS 


DTS_|_OLEDBINFORMATIO 
NALMESSAGE 


DTS_|_TXFUZZYLOOKUP_EX 
ACT_MATCH_PERF_COLLAT 
IONS_DONT_MATCH 


DTS_|_TXFUZZYLOOKUP_EX 
ACT_MATCH_PERF_INDEX_ 
MISSING 


DTS_|_DISPSNOTREVIEWED 


DTS_|_TXAGG_WORKSPACE 
_REHASH 


DESCRIPTION 


%1 has cached a total of 
%2!d! rows. 


The raw source adapter 
opened a file, but the file 
contains no columns. The 
adapter will not produce 
data. This could indicate a 
damaged file, or that there 
are zero columns and, 
therefore, no data. 


An OLE DB informational 
message is available. 


Fuzzy match performance 
can be improved if the exact 
join FuzzyComparisonFlags 
on the input column "%1" 
are set to match with the 
default SQL collation for 
reference table column 
"%2". It is also necessary 
that no fold flags are set in 
FuzzyComparisonFlagsEx. 


Fuzzy match performance 
can be improved if an index 
is created upon the 
reference table across all of 
the specified exact match 
columns. 


Error and truncation 
dispositions were not 
reviewed. Make sure this 
component is configured to 
redirect rows to error 
outputs, if you wish to 
further transform those 
rows. 


The Aggregate 
transformation has 
encountered %1!d! key 
combinations. It has to re- 
hash data because the 
number of key 
combinations is more than 
expected. The component 
can be configured to avoid 
data re-hash by adjusting 
the Keys, KeyScale, and 
AutoExtendFactor 
properties. 


HEXADECIMAL CODE 


0x402090DB 


0x402090DC 


0x402090DD 


0x402090DE 


0x402090DF 


0x402090E0 


0x402090E1 


0x402090E2 


0x402090E3 


0x402090E4 


DECIMAL CODE 


1075876059 


1075876060 


1075876061 


1075876062 


1075876063 


1075876064 


1075876065 


1075876066 


1075876067 


1075876068 


SYMBOLIC NAME 


DTS_I|_TXAGG_COUNTDISTI 
NCT_REHASH 


DTS_|_STARTPROCESSINGFI 
LE 


DTS_|_FINISHPROCESSINGF 
ILE 


DTS_|_TOTALDATAROWSPR 
OCESSEDFORFILE 


DTS_I_FINALCOMMITSTART 
ED 


DTS_|_FINALCOMMITENDE 
D 


DTS_|_BEGINHASHINGCAC 
HE 


DTS_|_SUCCEEDEDHASHIN 
GCACHE 


DTS_|_FAILEDHASHINGCAC 
HE 


DTS_|_SUCCEEDEDPREPARI 
NGCACHE 


DESCRIPTION 


The Aggregate 
transformation has 
encountered %1!d! distinct 
values while performing a 
"count distinct" aggregation 
on "%2". The 
transformation will re-hash 
data because the number of 
distinct values is more than 
expected. The component 
can be configured to avoid 
data re-hash by adjusting 
the CountDistinctKeys, 
CountDistinctKeyScale, and 
AutoExtendFactor 
properties. 


The processing of file "%1" 
has started. 


The processing of file "%1" 
has ended. 


The total number of data 
rows processed for file "%1" 
is %2!164d!. 


The final commit for the 
data insertion in "%1" has 
started. 


The final commit for the 
data insertion in "%1" has 
ended. 


%1!u! rows are added to 
the cache. The system is 
processing the rows. 


The %1 processed %2!u! 
rows in the cache. The 
processing time was %3 
seconds. The cache used 
%A'64u! bytes of memory. 


The %1 failed to process the 
rows in the cache. The 
processing time was %2 
second(s). 


The %1 succeeded in 
preparing the cache. The 
preparation time was %2 
seconds. 


HEXADECIMAL CODE 


0x40209314 


0x40209315 


0x40209316 


0x40209317 


0x4020F42C 


General and Event Messages 


DECIMAL CODE 


1075876628 


1075876629 


1075876630 


1075876631 


1075901484 


SYMBOLIC NAME 


DTS_|_TXLOOKUP_PARTIAL 
PERF 


DTS_|_TXLOOKUP_PARTIAL 
PERF2 


DTS_|_CACHEFILEWRITESTA 
RTED 


DTS_|_CACHEFILEWRITESU 
CCEEDED 


DTS_|_OLEDBDESTZEROMA 
XCOMMITSIZE 


The symbolic names of Integration Services error messages begin with DTS_MSG_. 


HEXADECIMAL CODE 


Ox1 


Ox2 


DECIMAL CODE 


SYMBOLIC NAME 


DTS_MSG_CATEGORY_SERV 
ICE_CONTROL 


DTS_MSG_CATEGORY_RUN 
NING_PACKAGE_MANAGE 
MENT 


DESCRIPTION 


The %1 has performed the 
following operations: 
processed %2!164u! rows, 
issued %3!164u! database 
commands to the reference 
database, and performed 
%A'64u! lookups using 
partial cache. 


The %1 has performed the 
following operations: 
processed %2!164u! rows, 
issued %3!164u! database 
commands to the reference 
database, performed 
%A'64u! lookups using 
partial cache and %5!164u! 
lookups using the cache for 
rows with no matching 
entries in the initial lookup. 


The %1 is writing the cache 
to file "%2". 


The %1 has written the 
cache to file "%2". 


The Maximum insert 
commit size property of the 
OLE DB destination "%1" is 
set to 0. This property 
setting can cause the 
running package to stop 
responding. For more 
information, see the F1 
Help topic for OLE DB 
Destination Editor 
(Connection Manager 
Page). 


DESCRIPTION 


Incorrect function. 


The system cannot find the 
file specified. 


HEXADECIMAL CODE 


0x100 


0x101 


0x102 


0x103 


0x104 


0x105 


0x110 


0x111 


0x112 


DECIMAL CODE 


256 


257 


258 


259 


260 


261 


272 


273 


274 


SYMBOLIC NAME 


DTS_MSG_SERVER_STARTIN 
G 


DTS_MSG_SERVER_STARTED 


DTS_MSG_SERVER_STOPPIN 
G 


DTS_MSG_SERVER_STOPPE 
D 


DTS_MSG_SERVER_START_F 
AILED 


DTS_MSG_SERVER_STOP_ER 
ROR 


DTS_MSG_SERVER_MISSING 
_CONFIG 


DTS_MSG_SERVER_BAD_CO 
NFIG 


DTS_MSG_SERVER_MISSING 
_CONFIG_REG 


DESCRIPTION 


Starting Microsoft SSIS 
Service. 


Server version %1 


Microsoft SSIS Service 
started. 


Server version %1 


The wait operation timed 
out. 


No more data is available. 


Microsoft SSIS Service failed 
to start. 


Error: %1 


Error stopping Microsoft 
SSIS Service. 


Error: %1 


Microsoft SSIS Service 
configuration file does not 
exist. 


Loading with default 
settings. 


Microsoft SSIS Service 
configuration file is 
incorrect. 


Error reading config file: %1 


Loading server with default 
settings. 


Microsoft SSIS Service: 


Registry setting specifying 
configuration file does not 
exist. 


Attempting to load default 
config file. 


HEXADECIMAL CODE 


0x150 


0x40013000 


0x40013001 


0x40013002 


0x40013003 


0x40013004 


0x40013005 


0x40103100 


DECIMAL CODE 


336 


1073819648 


1073819649 


1073819650 


1073819651 


1073819652 


1073819653 


1074802944 


SYMBOLIC NAME 


DTS_MSG_SERVER_STOPPIN 
G_PACKAGE 


DTS_MSG_PACKAGESTART 


DTS_MSG_PACKAGESUCCES 
S 


DTS_MSG_PACKAGECANCE 
L 


DTS_MSG_PACKAGEFAILUR 
E 


DTS_MSG_CANTDELAYLOA 
DDLL 


DTS_MSG_CANTDELAYLOA 
DDLLFUNCTION 


DTS_MSG_EVENTLOGENTRY 


DESCRIPTION 


Microsoft SSIS Service: 
stopping running package. 


Package instance ID: %1 
Package ID: %2 
Package name: %3 
Package description: %4 


Package started by: %5. 


Package "%1" started. 


Package "%1" finished 
successfully. 


Package "%1" has been 
cancelled. 


Package "%1" failed. 


Module %1 cannot load 
DLL %2 to call entry point 
%3 because of error %4. 
The product requires that 
DLL to run, but the DLL 
could not be found on the 
path. 


Module %1 loaded DLL %2, 
but cannot find entry point 
%3 because of error %4. 
The named DLL could not 
be found on the path, and 
the product requires that 
DLL to run. 


Event Name: %1 
Message: %9 
Operator: %2 
Source Name: %3 
Source ID: %4 
Execution ID: %5 
Start Time: %6 
End Time: %7 


Data Code: %8 


HEXADECIMAL CODE 


0x40103101 


0x40103102 


0x40103103 


DECIMAL CODE 


1074802945 


1074802946 


1074802947 


SYMBOLIC NAME 


DTS_MSG_EVENTLOGENTRY 


_PREEXECUTE 


DTS_MSG_EVENTLOGENTRY 


_POSTEXECUTE 


DTS_MSG_EVENTLOGENTRY 


_PREVALIDATE 


DESCRIPTION 


Event Name: %1 


Message: %9 


Operator: %2 


Source Name: %3 


Source ID: %4 


Execution ID: %5 


Start Time: %6 


End Time: %7 


Data Code: %8 


Event Name: %1 


Message: %9 


Operator: %2 


Source Name: %3 


Source ID: %4 


Execution ID: %5 


Start Time: %6 


End Time: %7 


Data Code: %8 


Event Name: %1 


Message: %9 


Operator: %2 


Source Name: %3 


Source ID: %4 


Execution ID: %5 


Start Time: %6 


End Time: %7 


Data Code: %8 


HEXADECIMAL CODE 


0x40103104 


0x40103105 


0x40103106 


DECIMAL CODE 


1074802948 


1074802949 


1074802950 


SYMBOLIC NAME 


DTS_MSG_EVENTLOGENTRY 


_POSTVALIDATE 


DTS_MSG_EVENTLOGENTRY 


_WARNING 


DTS_MSG_EVENTLOGENTRY 


_ERROR 


DESCRIPTION 


Event Name: %1 


Message: %9 


Operator: %2 


Source Name: %3 


Source ID: %4 


Execution ID: %5 


Start Time: %6 


End Time: %7 


Data Code: %8 


Event Name: %1 


Message: %9 


Operator: %2 


Source Name: %3 


Source ID: %4 


Execution ID: %5 


Start Time: %6 


End Time: %7 


Data Code: %8 


Event Name: %1 


Message: %9 


Operator: %2 


Source Name: %3 


Source ID: %4 


Execution ID: %5 


Start Time: %6 


End Time: %7 


Data Code: %8 


HEXADECIMAL CODE 


0x40103107 


0x40103108 


0x40103109 


DECIMAL CODE 


1074802951 


1074802952 


1074802953 


SYMBOLIC NAME 


DTS_MSG_EVENTLOGENTRY 


_TASKFAILED 


DTS_MSG_EVENTLOGENTRY 


_PROGRESS 


DTS_MSG_EVENTLOGENTRY 


_EXECSTATCHANGE 


DESCRIPTION 


Event Name: %1 


Message: %9 


Operator: %2 


Source Name: %3 


Source ID: %4 


Execution ID: %5 


Start Time: %6 


End Time: %7 


Data Code: %8 


Event Name: %1 


Message: %9 


Operator: %2 


Source Name: %3 


Source ID: %4 


Execution ID: %5 


Start Time: %6 


End Time: %7 


Data Code: %8 


Event Name: %1 


Message: %9 


Operator: %2 


Source Name: %3 


Source ID: %4 


Execution ID: %5 


Start Time: %6 


End Time: %7 


Data Code: %8 


HEXADECIMAL CODE 


0x4010310A 


0x4010310B 


0x4010310C 


DECIMAL CODE 


1074802954 


1074802955 


1074802956 


SYMBOLIC NAME 


DTS_MSG_EVENTLOGENTRY 


_VARVALCHANGE 


DTS_MSG_EVENTLOGENTRY 


_CUSTOMEVENT 


DTS_MSG_EVENTLOGENTRY 


_PACKAGESTART 


DESCRIPTION 


Event Name: %1 


Message: %9 


Operator: %2 


Source Name: %3 


Source ID: %4 


Execution ID: %5 


Start Time: %6 


End Time: %7 


Data Code: %8 


Event Name: %1 


Message: %9 


Operator: %2 


Source Name: %3 


Source ID: %4 


Execution ID: %5 


Start Time: %6 


End Time: %7 


Data Code: %8 


Event Name: %1 


Message: %9 


Operator: %2 


Source Name: %3 


Source ID: %4 


Execution ID: %5 


Start Time: %6 


End Time: %7 


Data Code: %8 


HEXADECIMAL CODE DECIMAL CODE SYMBOLIC NAME DESCRIPTION 


0x4010310D 1074802957 DTS_MSG_EVENTLOGENTRY Event Name: %1 
_PACKAGEEND 

Message: %9 
Operator: %2 
Source Name: %3 
Source ID: %4 
Execution ID: %5 
Start Time: %6 


End Time: %7 


Data Code: %8 


0x4010310E 1074802958 DTS_MSG_EVENTLOGENTRY Event Name: %1 
_INFORMATION 

Message: %9 
Operator: %2 
Source Name: %3 
Source ID: %4 
Execution ID: %5 
Start Time: %6 


End Time: %7 


Data Code: %8 


Success Messages 


The symbolic names of Integration Services success messages begin with DTS_S_. 


HEXADECIMAL CODE DECIMAL CODE SYMBOLIC NAME DESCRIPTION 
0x40003 262147 DTS_S NULLDATA The value is NULL. 
0x40005 262149 DTS_S TRUNCATED The string value was 


truncated. The buffer 
received a string that was 
too long for the column, 
and the string was 
truncated by the buffer. 


0x200001 2097153 DTS_S_EXPREVALTRUNCATI A truncation occurred 
ONOCCURRED during evaluation of the 
expression. The truncation 
occurred during evaluation, 
which may include any 
point in an intermediate 
step. 


Data Flow Component Error Messages 


The symbolic names of Integration Services error messages begin with DTSBC_E_, where "BC" refers to the 


native base class from which most Microsoft data flow components are derived. 


HEXADECIMAL CODE 


0xC8000002 


0xC8000003 


0xC8000005 


0xC8000006 


0xC8000007 


0xC8000008 


0xC8000009 


OxC800000A 


0xC800000B 


OxC800000C 


0xC800000D 


DECIMAL CODE 


-939524094 


-939524093 


-939524091 


-939524090 


-939524089 


-939524088 


-939524087 


-939524086 


-939524085 


-939524084 


-939524083 


SYMBOLIC NAME 


DTSBC_E_INCORRECTEXACT 
NUMBEROFTOTALOUTPUTS 


DTSBC_E_FAILEDTOGETOUT 
PUTBYINDEX 


DTSBC_E_INCORRECTEXACT 
NUMBEROFERROROUTPUT 
S 


DTSBC_E_INVALIDVALIDATI 
ONSTATUSVALUE 


DTSBC_E_INPUTHASNOOU 
TPUT 


DTSBC_E_INPUTHASNOERR 
OROUTPUT 


DTSBC_E_INVALIDHTPIVAL 
UE 


DTSBC_E_FAILEDTOGETCOLI 
NFO 


DTSBC_E_FAILEDTOSETCOLI 
NFO 


DTSBC_E_INVALIDPROPERT 
Y 


DTSBC_E_PROPERTYNOTFO 
UND 


DESCRIPTION 


The total number of 
outputs and error outputs, 
%1'lu!, is incorrect. There 
must be exactly %2!lul. 


Cannot retrieve output with 
index %1!lul. 


The number of error 
outputs, %1!lu!, is incorrect. 
There must be exactly 
%2!lu!. 


Incorrect validation status 
value, "%1!lu! ". It must be 
one of the values found in 
the DTSValidationStatus 
enumeration. 


The input "%1!lu!" has no 
synchronous output. 


The input "%1!lu!" has no 
synchronous error output. 


The HowToProcess!Input 
value, %1!lul, is not valid. It 
must be one of the values 
from the 
HowtToProcessInput 
enumeration. 


Failed to get information for 
row "%1!Id!", column 
"%2!Id!" from the buffer. The 
error code returned was 
0x%3!8.8X!. 


Failed to set information for 
row "%1!Id!", column 
"%2!Id!" into the buffer. The 
error code returned was 
0x%3!8.8X!. 


The property "%1" is not 
valid. 


The property "%1" was not 
found. 


HEXADECIMAL CODE 


0xC8000010 


0xC8000011 


0xC8000012 


0xC8000013 


0xC8000014 


0xC8000015 


0xC8000016 


0xC8000017 


0xC8000018 


DECIMAL CODE 


-939524080 


-939524079 


-939524078 


-939524077 


-939524076 


-939524075 


-939524074 


-939524073 


-939524072 


SYMBOLIC NAME 


DTSBC_E_READONLYPROPE 
RTY 


DTSBC_E_CANTINSERTOUTP 
UTCOLUMN 


DTSBC_E_OUTPUTCOLUMN 
SMETADATAMISMATCH 


DTSBC_E_OUTPUTCOLUMN 
SMISSING 


DTSBC_E_TOOMANYOUTP 
UTCOLUMNS 


DTSBC_E_OUTPUTCOLUMN 
SMETADATAMISMATCHUN 
MAP 


DTSBC_E_UNMAPINPUTCO 
LUMNS 


DTSBC_E_MULTIPLEINCOLS 
TOOUTCOL 


DTSBC_E_CANTINSERTEXTE 
RNALMETADATACOLUMN 


DESCRIPTION 


Error assigning a value to 
the read-only property 
"O61", 


The %1 does not allow the 
insertion of output 
columns. 


The output columns’ 
metadata does not match 
the associated input 
columns' metadata. The 
output columns’ metadata 
will be updated. 


There are input columns 
that do not have associated 
output columns. The output 
columns will be added. 


There are output columns 
that do not have associated 
input columns. The output 
columns will be removed. 


The output columns’ 
metadata does not match 
the associated input 
columns' metadata. The 
input columns will be 
unmapped. 


There are input columns 
that do not have associated 
output columns. The input 
columns will be unmapped. 


There is an input column 
associated with an output 
column, and that output 
column is already 
associated with another 
input column on the same 
input. 


The %1 does not allow the 
insertion of external 
metadata columns. 
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SQL Server Integration Services has an architecture that separates data movement and transformation from 
package control flow and management. There are two distinct engines that define this architecture and that can 
be automated and extended when programming Integration Services. The run-time engine implements the 
control flow and package management infrastructure that lets developers control the flow of execution and set 
options for logging, event handlers, and variables. The data flow engine is a specialized, high performance 
engine that is exclusively dedicated to extracting, transforming, and loading data. When programming 
Integration Services, you will be programming against these two engines. 


The following image depicts the architecture of Integration Services. 


Object Model 


Custom Applications | SSIS Designer | 









Integration 


Command Line Utilities | SSIS Wizards Services 





















-dtsx File 


Database 





Log Enumerators ] 
Providers 

a Connection 
Managers 

Data a 

Event 
Sources Handlers | 
Data Flow Task 


%G 






Data Flow Task 
Object Model 


Integration Services Data Flow 


Source Source 
Transformation 





Data Flow | Transformation | 
Components 
Custom Destination 
Data Flow 
Components 


Integration Services Run-time Engine 


The Integration Services run-time engine controls the management and execution of packages, by 
implementing the infrastructure that enables execution order, logging, variables, and event handling. 
Programming the Integration Services run-time engine lets developers automate the creation, configuration, 
and execution of packages and create custom tasks and other extensions. 


For more information, see Extending the Package with the Script Task, Developing a Custom Task, and Building 
Packages Programmatically. 


Integration Services Data Flow Engine 


The data flow engine manages the data flow task, which is a specialized, high performance task dedicated to 

moving and transforming data from disparate sources. Unlike other tasks, the data flow task contains additional 
objects called data flow components, which can be sources, transformations, or destinations. These components 
are the core moving parts of the task. They define the movement and transformation of data. Programming the 
data flow engine lets developers automate the creation and configuration of the components in a data flow task, 


and create custom components. 


For more information, see Extending the Data Flow with the Script Component, Developing a Custom Data Flow 
Component, and Building Packages Programmatically. 


Supported Languages 


Integration Services fully supports the Microsoft NET Framework. This lets developers program Integration 
Services in their choice of INET-compliant languages. Although both the run-time engine and the data flow 
engine are written in native code, they are both available through a fully managed object model. 


You can program Integration Services packages, custom tasks, and components in Microsoft Visual Studio or in 
another code or text editor. Visual Studio offers the developer many tools and features to simplify and accelerate 
the iterative cycles of coding, debugging, and testing. Visual Studio also makes deployment easier. However, you 
do not need Visual Studio to compile and build Integration Services code projects. The .NET Framework SDK 
includes the Visual Basic and Visual C# compilers and related tools. 


IMPORTANT 

By default, the .NET Framework is installed with SQL Server, but the .NET Framework SDK is not. Unless the SDK is 
installed on the computer and the SDK documentation is included in the Books Online collection, links to SDK content in 
this section will not work. After you have installed the .NET Framework SDK, you can add the SDK documentation to the 
Books Online collection and table of contents by following the instructions in Add or Remove Product Documentation for 
SQL Server. 











The Integration Services Script task and Script component use Microsoft Visual Studio Tools for Applications 
(VSTA) as an embedded scripting environment. VSTA supports Microsoft Visual Basic and Microsoft Visual C#. 





NOTE 


The Integration Services application programming interfaces are incompatible with COM-based scripting languages such 
as VBScript. 











Locating Assemblies 


In SQL Server 2019 (15.x), the Integration Services assemblies were upgraded to .NET 4.0. There is a separate 
global assembly cache for .NET 4, located in <drive>\Windows\Microsoft.NET\assembly. You can find all of the 
Integration Services assemblies under this path, usually in the GAC_MSIL folder. 


As in previous versions of SQL Server, the core Integration Services extensibility .dll files are also located at 
<drive>:\Program Files\Microsoft SQL Server\100\SDK\Assemblies. 


Commonly Used Assemblies 


The following table lists the assemblies that are frequently used when programming Integration Services using 
the .NET Framework. 


ASSEMBLY 


Microsoft.SqlServer ManagecDTS.dll 


Microsoft.SqlServerRuntimeWrapperdll 


Microsoft.SqlServerPipelineHost.dll 


Microsoft.SqlServerPipelineWrapperdll 


DESCRIPTION 


Contains the managed run-time engine. 


Contains the primary interop assembly (PIA), or wrapper, for 
the native run-time engine. 


Contains the managed data flow engine. 


Contains the primary interop assembly (PIA), or wrapper, for 
the native data flow engine. 
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To understand the difference between a synchronous and an asynchronous transformation in Integration 
Services, it is easiest to start with an understanding of a synchronous transformation. If a synchronous 
transformation does not meet your needs, your design might require an asynchronous transformation. 


Synchronous Transformations 


A synchronous transformation processes incoming rows and passes them on in the data flow one row ata time. 
Output is synchronous with input, meaning that it occurs at the same time. Therefore, to process a given row, 
the transformation does not need information about other rows in the data set. In the actual implementation, 
rows are grouped into buffers as they pass from one component to the next, but these buffers are transparent to 
the user, and you can assume that each row is processed separately. 


An example of a synchronous transformation is the Data Conversion transformation. For each incoming row, it 
converts the value in the specified column and sends the row on its way. Each discrete conversion operation is 
independent of all the other rows in the data set. 


In Integration Services scripting and programming, you specify a synchronous transformation by looking up the 
ID of a component's input and assigning it to the SynchronousInputID property of the component's outputs. 
This tells the data flow engine to process each row from the input and send each row automatically to the 
specified outputs. If you want every row to go to every output, you do not have to write any additional code to 
output the data. If you use the ExclusionGroup property to specify that rows should only go to one or another 
of a group of outputs, as in the Conditional Split transformation, you must call the DirectRow method to select 
the appropriate destination for each row. When you have an error output, you must call DirectErrorRow to 
send rows with problems to the error output instead of the default output. 


Asynchronous Transformations 


You might decide that your design requires an asynchronous transformation when it is not possible to process 
each row independently of all other rows. In other words, you cannot pass each row along in the data flow as it 
is processed, but instead must output data asynchronously, or at a different time, than the input. For example, 
the following scenarios require an asynchronous transformation: 


e@ The component has to acquire multiple buffers of data before it can perform its processing. An example is 
the Sort transformation, where the component has to process the complete set of rows in a single 
operation. 


e The component has to combine rows from multiple inputs. An example is the Merge transformation, 
where the component has to examine multiple rows from each input and then merge them in sorted 
order. 


e There is no one-to-one correspondence between input rows and output rows. An example is the 
Aggregate transformation, where the component has to add a row to the output to hold the computed 
aggregate values. 


In Integration Services scripting and programming, you specify an asynchronous transformation by assigning a 


value of 0 to the SynchronousInputID property of the component's outputs. . This tells the data flow engine 
not to send each row automatically to the outputs. Then you must write code to send each row explicitly to the 
appropriate output by adding it to the new output buffer that is created for the output of an asynchronous 


transformation. 





NOTE 


Since a source component must also explicitly add each row that it reads from the data source to its output buffers, a 


source resembles a transformation with asynchronous outputs. 











It would also be possible to create an asynchronous transformation that emulates a synchronous transformation 
by explicitly copying each input row to the output. By using this approach, you could rename columns or 
convert data types or formats. However this approach degrades performance. You can achieve the same results 
with better performance by using built-in Integration Services components, such as Copy Column or Data 


Conversion. 


See Also 


Creating a Synchronous Transformation with the Script Component 

Creating an Asynchronous Transformation with the Script Component 
Developing a Custom Transformation Component with Synchronous Outputs 
Developing a Custom Transformation Component with Asynchronous Outputs 
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In Integration Services, the AcquireConnection method of the associated connection manager class is the 
method that you call most often when you are working with connection managers in managed code. When you 
write managed code, you have to call the AcquireConnection method to use the functionality of a connection 
manager. You have to call this method regardless of whether you are writing managed code in a Script task, 
Script component, custom object, or custom application. 


To call the AcquireConnection method successfully, you have to know the answers to the following questions: 
e Which connection managers return a managed object from the AcquireConnection method? 


Many connection managers return unmanaged COM objects (System.__ComObject) and these objects 
cannot easily be used from managed code. The list of these connection managers includes the frequently 
used OLE DB connection manager. 


e For those connection managers that return a managed object, what objects do their 
AcquireConnection methods return? 


To cast the return value to the appropriate type, you have to know what type of object the 
AcquireConnection method returns. For example, the AcquireConnection method for the ADO.NET 
connection manager returns an open SqlConnection object when you use the SqlClient provider. 
However, the AcquireConnection method for the File connection manager just returns a string. 


This topic answers these questions for the connection managers that are included with Integration Services. 


Connection Managers That Do Not Return a Managed Object 


The following table lists the connection managers that return a native COM object (System.__ComObject) from 
the AcquireConnection method. These unmanaged objects cannot easily be used from managed code. 


CONNECTION MANAGER TYPE CONNECTION MANAGER NAME 

ADO ADO Connection Manager 
MSOLAP90 Analysis Services Connection Manager 
EXCEL Excel Connection Manager 

FTP FTP Connection Manager 

HTTP HTTP Connection Manager 

ODBC ODBC Connection Manager 

OLEDB OLE DB Connection Manager 


Typically, you can use an ADO.NET connection manager from managed code to connect to an ADO, Excel, ODBC, 
or OLE DB data source. 


Return Values from the AcquireConnection Method 


The following table lists the connection managers that return a managed object from the AcquireConnection 
method. These managed objects can easily be used from managed code. 


CONNECTION MANAGER 
TYPE 


ADO.NET 


FILE 


FLATFILE 


MSMQ 


MULTIFILE 


MULTIFLATFILE 


SMOServer 


SMTP 


WMI 


SQLMOBILE 


See Also 


CONNECTION MANAGER 
NAME 


ADO.NET Connection 
Manager 


File Connection Manager 


Flat File Connection 
Manager 


MSMQ Connection 
Manager 


Multiple Files Connection 
Manager 





Multiple Flat Files 
Connection Manager 


SMO Connection Manager 


SMTP Connection Manager 


WMI Connection Manager 


SQL Server Compact 
Connection Manager 


Connecting to Data Sources in the Script Task 


Connecting to Data Sources in the Script Component 


Connecting to Data Sources in a Custom Task 


TYPE OF RETURN VALUE 


System.Data.SqlClient.S 
qiConnection 


System.String 


System.String 


System.Messaging.Mess 
ageQueue 


System.String 


System.String 


Microsoft.SqlServer.Man 
agement.Smo.Server 


System.String 


System.Management.Ma 
nagementScope 


System.Data.SqlServerC 
e.SqlCeConnection 


ADDITIONAL 
INFORMATION 


Path to the file. 


Path to the file. 


Path to one of the files. 


Path to one of the files. 


For example: 


SmtpServer=<server 
name> ;UseWindowsAuthentication=True; Enables 
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If you find that the built-in components Integration Services do not meet your requirements, you can extend the 
power of Integration Services by coding your own extensions. You have two discrete options for extending your 
packages: you can write code within the powerful wrappers provided by the Script task and the Script 
component, or you can create custom Integration Services extensions from scratch by deriving from the base 
classes provided by the Integration Services object model. 


This section explores the simpler of the two options - extending packages with scripting. 


The Script task and the Script component let you extend both the control flow and the data flow of an 
Integration Services package with very little coding. Both objects use the Microsoft Visual Studio Tools for 
Applications (VSTA) development environment and the Microsoft Visual Basic or Microsoft Visual C# 
programming languages, and benefit from all the functionality offered by the Microsoft .NET Framework class 
library, as well as custom assemblies. The Script task and the Script component let the developer create custom 
functionality without having to write all the infrastructure code that is typically required when developing a 
custom task or custom data flow component. 


In This Section 


Comparing the Script Task and the Script Component 
Discusses the similarities and differences between the Script task and the Script component. 


Comparing Scripting Solutions and Custom Objects 
Discusses the criteria to use in choosing between a scripting solution and the development of a custom object. 


Referencing Other Assemblies in Scripting Solutions 
Discusses the steps required to reference and use external assemblies and namespaces in a scripting project. 


Extending the Package with the Script Task 
Discusses how to create custom tasks by using the Script task. A task is typically called one time per package 
execution, or one time for each data source opened by a package. 


Extending the Data Flow with the Script Component 
Discusses how to create custom data flow sources, transformations, and destinations by using the Script 
component. A data flow component is typically called one time for each row of data that is processed. 


Reference 


Integration Services Error and Message Reference 


Lists the predefined Integration Services error codes with their symbolic names and descriptions. 


Related Sections 


Extending Packages with Custom Objects 
Discusses how to create program custom tasks, data flow components, and other package objects for use in 
multiple packages. 


Building Packages Programmatically 
Describes how to create, configure, run, load, save, and manage Integration Services packages 


programmatically. 


See Also 


SQL Server Integration Services 


Comparing the Script Task and the Script 


Component 
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The Script task, available in the Control Flow window of the Integration Services designer, and the Script 
component, available in the Data Flow window, have very different purposes in an Integration Services package. 
The task is a general-purpose control flow tool, whereas the component serves as a source, transformation, or 
destination in the data flow. Despite their different purposes, however, the Script task and the Script component 
have some similarities in the coding tools that they use and the objects in the package that they make available 
to the developer. Understanding their similarities and differences may help you to use both the task and the 
component more effectively. 


Similarities between the Script Task and the Script Component 


The Script task and the Script component share the following common features. 
FEATURE DESCRIPTION 


Two design-time modes In both the task and the component, you begin by 
specifying properties in the editor, and then switch to the 
development environment to write code. 


Microsoft Visual Studio Tools for Applications (VSTA) Both the task and the component use the same VSTA IDE, 
and support code written in either Microsoft Visual Basic or 
Microsoft Visual C#. 


Precompiled scripts Beginning in SQL Server 2008 Integration Services (SSIS), all 
scripts are precompiled. In earlier versions, you could specify 
whether scripts were precompiled. 


The script is precompiled into binary code, permitting faster 
execution, but at the cost of increased package size. 


Debugging Both the task and the component support breakpoints and 
stepping through code while debugging in the design 
environment. For more information, see Coding and 
Debugging the Script Task and Coding and Debugging the 
Script Component. 


Differences between the Script Task and the Script Component 


The Script task and the Script component have the following noteworthy differences. 


FEATURE SCRIPT TASK SCRIPT COMPONENT 


FEATURE 


Control flow / Data flow 


Purpose 


Execution 


Editor 


Interaction with the package 


Using variables 


SCRIPT TASK 


The Script task is configured on the 
Control Flow tab of the designer and 
runs outside the data flow of the 
package. 


A Script task can accomplish almost 
any general-purpose task. 


A Script task runs custom code at 
some point in the package workflow. 
Unless you put it in a loop container or 
an event handler, it only runs once. 


The Script Task Editor has three 
pages: General, Script, and 
Expressions. Only the 
ReadOnlyVariables and 
ReadWriteVariables, and 
ScriptLanguage properties directly 
affect the code that you can write. 


In the code written for a Script task, 
you use the Dts property to access 
other features of the package. The Dts 
property is a member of the 
ScriptMain class. 


The Script task uses the Variables 
property of the Dts object to access 
variables that are available through the 
task’s ReadOnlyVariables and 
ReadWriteVariables properties. For 
example: 


[Visual Basic] 


Dim myVar as String 


myVar = 


Dts.Variables("MyStringVariable").Val 


[C#] 


string myVar; 


myVar = 


Dts.Variables["MyStringVariable"].Val 


SCRIPT COMPONENT 


The Script component is configured on 
the Data Flow page of the designer 
and represents a source, 
transformation, or destination in the 
Data Flow task. 


You must specify whether you want to 
create a source, transformation, or 
destination with the Script component. 


A Script component also runs once, 
but typically it runs its main processing 
routine once for each row of data in 
the data flow. 


The Script Transformation Editor 
has up to four pages: Input 
Columns, Inputs and Outputs, 
Script, and Connection Managers. 
The metadata and properties that you 
configure on each of these pages 
determines the members of the base 
classes that are autogenerated for 
your use in coding. 


In Script component code, you use 
typed accessor properties to access 
certain package features such as 

variables and connection managers. 


The PreExecute method can access 
only read-only variables. The 
PostExecute method can access both 
read-only and read/write variables. 


For more information about these 
methods, see Coding and Debugging 
the Script Component. 


The Script component uses typed 
accessor properties of the 
autogenerated based class, created 
from the component's 
ReadOnlyVariables and 
ReadWriteVariables properties. For 
example: 


[Visual Basic] 
Dim myVar as String 


myVar = 
Me.Variables.MyStringVariable 


[C#] 
string myVar; 


myVar = 
this.Variables.MyStringVariable; 


FEATURE 


Using connections 


Raising events 


Logging 


SCRIPT TASK 


The Script task uses the Connections 
property of the Dts object to access 
connection managers defined in the 
package. For example: 


[Visual Basic] 


Dim myFlatFileConnection As 
String 


myFlatFileConnection = 


SCRIPT COMPONENT 


The Script component uses typed 
accessor properties of the 
autogenerated base class, created from 
the list of connection managers 
entered by the user on the Connection 
Managers page of the editor. For 
example: 


[Visual Basic] 


DirectCast(Dts.Connections("Test Flat ~*~ 


Connection") .AcquireConnection(Dts.Tri 


_ String) 


[C#] 


string myFlatFileConnection; 


myFlatFileConnection = (Dts.Connectio 


Flat File 


Connection"].AcquireConnection(Dts.Tri 


as: String): 


The Script task uses the Events 
property of the Dts object to raise 
events. For example: 


[Visual Basic] 


Dts.Events.FireError(@, "Event 
Snippet", _ ex.Message & 
ControlChars.CrLf & 
ex.StackTrace, _"", @) 


[C#] 


Dts.Events.FireError(@, "Event 
Snippet", ex.Message + "\r" + 
ex.StackTrace, "", 0) 


The Script task uses the Log method of 
the Dts object to log information to 
enabled log providers. For example: 


[Visual Basic] 


Dim bt(®) As Byte Dts.Log("Test 
KOg  EVeniey e105. 2D) 


[C#] 
byte[] bt = new byte[@]; 


Dts.Log("Test Log Event", @, 
bt); 


Dim connMgr As 
IDTSConnectionManager100 


connMgr = 
Me.Connections .MyADONETConnection 


[C#] 


IDTSConnectionManager100 
connMgr; 


connMgr = 


this.Connections.MyADONETConnection; 


The Script component raises errors, 
warnings, and informational messages 
by using the methods of the 
IDTSComponentMetaData100 
interface returned by the 
ComponentMetaData property. For 
example: 


[Visual Basic] 


Dim myMetadata as 
IDTSComponentMetaData1ee 
myMetaData = 
Me.ComponentMetaData 
myMetaData.FireError(...) 


The Script component uses the Log 
method of the autogenerated base 
class to log information to enabled log 
providers. For example: 

[Visual Basic] 

Dim bt(@) As Byte 

Me.Log("Test Log Event", _ 

@, =— 

bt) 


[C#] 


byte[] bt = new byte[@]; 
this.Log("Test Log Event", @, 
bE) i 


FEATURE SCRIPT TASK 


Returning results The Script task uses both the 
TaskResult property and the optional 
ExecutionValue property of the Dts 
object to notify the runtime of its 
results. 


See Also 


Extending the Package with the Script Task 
Extending the Data Flow with the Script Component 


SCRIPT COMPONENT 


The Script component runs as a part of 
the Data Flow task and does not 
report results using either of these 
properties. 
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An Integration Services Script task or Script component can implement much of the same functionality that is 
possible in a custom managed task or data flow component. Here are some considerations to help you choose 
the appropriate type of task for your needs: 


e If the configuration or functionality is specific to an individual package, you should use the Script task or 
the Script component instead of a developing a custom object. 


e If the functionality is generic, and might be used in the future for other packages and by other developers, 
you should create a custom object instead of using a scripting solution. You can use a custom object in 
any package, whereas a script can be used only in the package for which it was created. 


e If the code will be reused within the same package, you should consider creating a custom object. 
Copying code from one Script task or component to another leads to reduced maintainability by making 
it more difficult to maintain and update multiple copies of the code. 


e Ifthe implementation will change over time, consider using a custom object. Custom objects can be 
developed and deployed separately from the parent package, whereas an update made to a scripting 
solution requires the redeployment of the whole package. 


See Also 


Extending Packages with Custom Objects 


Referencing Other Assemblies in Scripting Solutions 
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The Microsoft .NET Framework class library provides the script developer with a powerful set of tools for 
implementing custom functionality in Integration Services packages. The Script task and the Script component 
can also use custom managed assemblies. 


NOTE 


To enable your packages to use the objects and methods from a Web service, use the Add Web Reference command 
available in MicrosoftVisual Studio Tools for Applications (VSTA). In earlier versions of Integration Services, you had to 
generate a proxy class to use a Web service. 





Using a Managed Assembly 
For Integration Services to find a managed assembly at design time, you must do the following steps: 


1. Store the managed assembly in any folder on your computer. 





NOTE 


In earlier versions of Integration Services, you could only add a reference to a managed assembly that was stored 
in the %windir%\Microsoft.NET\Framework\vx.x.xxxxx folder or the %ProgramFiles%\Microsoft SQL 
Server\100\SDK\Assemblies folder. 








2. Add a reference to the managed assembly. 


To add the reference, in VSTA, in the Add Reference dialog box, on the Browse tab, locate and add the 
managed assembly. 


For Integration Services to find the managed assembly at run time, you must do the following steps: 
1. Sign the managed assembly with a strong name. 
2. Install the assembly in the global assembly cache on the computer on which the package is run. 


For more information, see Building, Deploying, and Debugging Custom Objects. 


Using the Microsoft .NET Framework Class Library 


The Script task and the Script component can take advantage of all the other objects and functionality exposed 
by the .NET Framework class library. For example, by using the .NET Framework, you can retrieve information 
about your environment and interact with the computer that is running the package. 


This list describes several of the more frequently used .NET Framework classes: 
e System.Data Contains the ADO.NET architecture. 
e System.IO Provides an interface to the file system and streams. 


e System.Windows.Forms Provides form creation. 





e System.Text.RegularExpressions Provides classes for working with regular expressions. 


e System.Environment Returns information about the local computer, the current user, and computer and 


user settings. 
e System.Net Provides network communications. 
e System.DirectoryServices Exposes Active Directory. 
e System.Drawing Provides extensive image manipulation libraries. 
e System.Threading Enables multithreaded programming. 


For more information about the NET Framework, see the MSDN Library. 


See Also 
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This procedure describes how to set breakpoints in the scripts that are used in the Script task and Script 
component. 


After you set breakpoints in the script, the Set Breakpoints - <object name> dialog box lists the breakpoints, 
along with the built-in breakpoints. 





IMPORTANT 

Under certain circumstances, breakpoints in the Script task and Script component are ignored. For more information, see 
the Debugging the Script Task section in Coding and Debugging the Script Task and the Debugging the Script 
Component section in Coding and Debugging the Script Component. 








To set a breakpoint in script 


1. In SQL Server Data Tools (SSDT), open the Integration Services project that contains the package you 
want. 


2. Double-click the package that contains the script in which you want to set breakpoints. 

3. To open the Script task, click the Control Flow tab, and then double-click the Script task. 

4. To open the Script component, click the Data Flow tab, and then double-click the Script component. 
5. Click Script and then click Edit Script. 


6. In Microsoft Visual Studio Tools for Applications (VSTA), locate the line of script on which you want to set 
a breakpoint, right-click that line, point to Breakpoint, and then click Insert Breakpoint. 


The breakpoint icon appears on the line of code. 
7. On the File menu, click Exit. 
8. Click OK. 


9. To save the package, click Save Selected Items on the File menu. 


Extending the Package with the Script Task 
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The Script task extends the run-time capabilities of Microsoft Integration Services packages with custom code 
written in Microsoft Visual Basic or Microsoft Visual C# that is compiled and executed at package run time. The 
Script task simplifies the development of a custom run-time task when the tasks included with Integration 
Services do not fully satisfy your requirements. The Script task writes all the required infrastructure code for 
you, letting you focus exclusively on the code that is required for your custom processing. 


A Script task interacts with the containing package through the global Dts object, an instance of the 
ScriptObjectModel class that is exposed in the scripting environment. You can write code in a Script task that 
modifies the values stored in Integration Services variables; later, the package can use those updated values to 
determine the path of its workflow. The Script task can also use the Visual Basic namespace and the .NET 


Framework class library, as well as custom assemblies, to implement custom functionality. 


The Script task and the infrastructure code that it generates for you simplify significantly the process of 
developing a custom task. However, to understand how the Script task works, you may find it useful to read the 
section Developing a Custom Task to understand the steps that are involved in developing a custom task. 


If you are creating a task that you plan to reuse in multiple packages, you should consider developing a custom 
task instead of using the Script task. For more information, see Comparing Scripting Solutions and Custom 
Objects. 


In This Section 
The following topics provide more information about the Script task. 


Configuring the Script Task in the Script Task Editor 
Explains how the properties that you configure in the Script Task Editor affect the capabilities and the 
performance of the code in the Script task. 


Coding and Debugging the Script Task 
Explains how to use Microsoft Visual Studio Tools for Applications (VSTA) to develop the scripts that are 
contained in the Script task. 


Using Variables in the Script Task 
Explains how to use variables through the Variables property. 


Connecting to Data Sources in the Script Task 
Explains how to use connections through the Connections property. 


Raising Events in the Script Task 
Explains how to raise events through the Events property. 


Logging in the Script Task 
Explains how to log information through the Log method. 


Returning Results from the Script Task 
Explains how to return results through the property TaskResult and the ExecutionValue property. 


Script Task Examples 
Provides simple examples that demonstrate several possible uses for a Script task. 


See Also 


Script Task 
Comparing the Script Task and the Script Component 


Configuring the Script Task in the Script Task Editor 
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Before you write custom code in the Script task, you configure its principal properties in the three pages of the 
Script Task Editor. You can configure additional task properties that are not unique to the Script task by using 
the Properties window. 


NOTE 


Unlike earlier versions where you could indicate whether scripts were precompiled, all scripts are precompiled beginning in 
SQL Server 2008 Integration Services (SSIS). 











General Page of the Script Task Editor 


On the General page of the Script Task Editor, you assign a unique name and a description for the Script task. 


Script Page of the Script Task Editor 
The Script page of the Script Task Editor displays the custom properties of the Script task. 


ScriptLanguage Property 

Microsoft Visual Studio Tools for Applications (VSTA) supports the Microsoft Visual Basic or Microsoft Visual C# 
programming languages. After you create a script in the Script task, you cannot change value of the 
ScriptLanguage property. 


To set the default script language for Script tasks and Script components, use the ScriptLanguage property on 
the General page of the Options dialog box. For more information, see General Page. 


EntryPoint Property 

The EntryPoint property specifies the method on the ScriptMain class in the VSTA project that the Integration 
Services runtime calls as the entry point into the Script task code. The ScriptMain class is the default class 
generated by the script templates. 


If you change the name of the method in the VSTA project, you must change the value of the EntryPoint 
property. 


ReadOnlyVariables and ReadWriteVariables Properties 


You can enter comma-delimited lists of existing variables as the values of these properties to make the variables 
available for read-only or read/write access within the Script task code. Variables of both types are accessed in 
code through the Variables property of the Dts object. For more information, see Using Variables in the Script 
Task. 





NOTE 


Variable names are case-sensitive. 





To select the variables, click the ellipsis (...) button next to the property field. For more information, see Select 


Variables Page. 


Edit Script Button 


The Edit Script button launches the VSTA development environment in which you write your custom script. For 
more information, see Coding and Debugging the Script Task. 


Expressions Page of the Script Task Editor 


On the Expressions page of the Script Task Editor, you can use expressions to provide values for the 
properties of the Script task listed above and for many other task properties. For more information, see 
Integration Services (SSIS) Expressions. 


See Also 


Coding and Debugging the Script Task 


Coding and Debugging the Script Task 
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After configuring the Script task in the Script Task Editor, you write your custom code in the Script task 
development environment. 


Script Task Development Environment 


The Script task uses Microsoft Visual Studio Tools for Applications (VSTA) as the development environment for 
the script itself. 


Script code is written in Microsoft Visual Basic or Microsoft Visual C#. You specify the script language by setting 
the ScriptLanguage property in the Script Task Editor. If you prefer to use another programming language, 
you can develop a custom assembly in your language of choice and call its functionality from the code in the 
Script task. 


The script that you create in the Script task is stored in the package definition. There is no separate script file. 
Therefore, the use of the Script task does not affect package deployment. 


NOTE 


When you design the package and debug the script, the script code is temporarily written to a project file. Because storing 
sensitive information in a file is a potential security risk, we recommend that you do not include sensitive information such 
as passwords in the script code. 











By default, Option Strict is disabled in the IDE. 


Script Task Project Structure 


When you create or modify the script that is contained in a Script task, VSTA opens an empty new project or 
reopens the existing project. The creation of this VSTA project does not affect the deployment of the package, 
because the project is saved inside the package file; the Script task does not create additional files. 


Project Items and Classes in the Script Task Project 


By default, the Script task project displayed in the VSTA Project Explorer window contains a single item, 
ScriptMain. The ScriptMain item, in turn, contains a single class, also named ScriptMain. The code elements 
in the class vary depending on the programming language that you selected for the Script task: 


e When the Script task is configured for the Visual Basic 2010 programming language, the ScriptMain 
class has a public subroutine, Main. The ScriptMain.Main subroutine is the method that the runtime 
calls when you run your Script task. 


By default, the only code in the Main subroutine of a new script is the line 
Dts.TaskResult = ScriptResults.Success . This line informs the runtime that the task was successful in its 


operation. The Dts.TaskResult property is discussed in Returning Results from the Script Task. 


e@ When the Script task is configured for the Visual C# programming language, the ScriptMain class has a 
public method, Main. The method is called when the Script task runs. 


By default, the Main method includes the line pts.TaskResult = (int)ScriptResults.Success . This line 


informs the runtime that the task was successful in its operation. 


The ScriptMain item can contain classes other than the ScriptMain class. Classes are available only to the 
Script task in which they reside. 


By default, the ScriptMain project item contains the following autogenerated code. The code template also 
provides an overview of the Script task, and additional information on how to retrieve and manipulate SSIS 


objects, such as variables, events, and connections. 


Microsoft SQL Server Integration Services Script Task 


Write scripts using Microsoft Visual Basic 2008. 


The ScriptMain is the entry point class of the script. 


Imports System 

Imports System.Data 

Imports System.Math 

Imports Microsoft.SqlServer.Dts.Runtime.VSTAProxy 


<System.AddIn.AddIn("ScriptMain", Version:="1.0", Publisher:="", Description:="")> _ 
Partial Class ScriptMain 


Private Sub ScriptMain_Startup(ByVal sender As Object, ByVal e As System.EventArgs) Handles Me.Startup 
End Sub 


Private Sub ScriptMain_Shutdown(ByVal sender As Object, ByVal e As System.EventArgs) Handles Me.Shutdown 
Try 
" Unlock variables from the read-only and read-write variable collection properties 
If (Dts.Variables.Count <> @) Then 
Dts.Variables.Unlock() 
End If 
Catch ex As Exception 
End Try 


End Sub 


Enum ScriptResults 

Success = DTSExecResult.Success 
Failure = DTSExecResult.Failure 
End Enum 


The execution engine calls this method when the task executes. 
To access the object model, use the Dts property. Connections, variables, events, 


and logging features are available as members of the Dts property as shown in the following examples. 


To reference a variable, call Dts.Variables("MyCaseSensitiveVariableName").Value 
To post a log entry, call Dts.Log("This is my log text", 999, Nothing) 
" To fire an event, call Dts.Events.FireInformation(99, "test", "hit the help message", "", @, True) 


To use the connections collection use something like the following: 

" ConnectionManager cm = Dts.Connections.Add("OLEDB" ) 

" cm.ConnectionString = "Data Source=localhost;Initial Catalog=AdventureWorks ; Provider=SQLNCL1I10; Integrated 
Security=SSPI;Auto Translate=False;" 

" Before returning from this method, set the value of Dts.TaskResult to indicate success or failure. 


To open Help, press F1. 


Public Sub Main() 


" Add your code here 


Dts.TaskResult = ScriptResults.Success 
End Sub 


End Class 


Ves 
Microsoft SQL Server Integration Services Script Task 
Write scripts using Microsoft Visual C# 2008. 
The ScriptMain is the entry point class of the script. 
a) 


using System; 

using System.Data; 

using Microsoft.SqlServer.Dts.Runtime.VSTAProxy; 
using System.Windows. Forms; 


namespace ST_1bcfdbad36d94f8ba9f23a10375abe53.csproj 


it 
System.AddIn.AddIn("ScriptMain", Version = "1.0", Publisher = "", Description = "" 
y: p Pp 
public partial class ScriptMain 
it 
private void ScriptMain_Startup(object sender, EventArgs e) 
{ 
} 
private void ScriptMain_Shutdown(object sender, EventArgs e) 
{ 
try 
if 
// Unlock variables from the read-only and read-write variable collection properties 
if (Dts.Variables.Count != @) 
{ 
Dts.Variables.Unlock(); 
i 
} 
catch 
it 
} 
} 


#region VSTA generated code 
private void InternalStartup() 


{ 
this.Startup += new System.EventHandler(ScriptMain_Startup) ; 
this.Shutdown += new System.EventHandler(ScriptMain_Shutdown) ; 
} 
enum ScriptResults 
{ 
Success = DTSExecResult.Success, 
Failure = DTSExecResult.Failure 
33 
#endregion 
if} 


The execution engine calls this method when the task executes. 
To access the object model, use the Dts property. Connections, variables, events, 
and logging features are available as members of the Dts property as shown in the following examples. 


To reference a variable, call Dts.Variables["MyCaseSensitiveVariableName"].Value; 
To post a log entry, call Dts.Log("This is my log text", 999, null); 
To fire an event, call Dts.Events.FireInformation(99, "test", "hit the help message", 


ay Oa PUue));s 


To use the connections collection use something like the following: 

ConnectionManager cm = Dts.Connections.Add("OLEDB") ; 

cm.ConnectionString = "Data Source=localhost;Initial Catalog=AdventureWorks ; Provider=SQLNCLI1®; Integrated 
Security=SSPI;Auto Translate=False;"; 


Before returning from this method, set the value of Dts.TaskResult to indicate success or failure. 


To open Help, press F1. 
sf 


public void Main() 


{ 
// TODO: Add your code here 
Dts.TaskResult = (int)ScriptResults.Success; 


Additional Project Items in the Script Task Project 


The Script task project can include items other than the default ScriptMain item. You can add classes, modules, 
and code files to the project. You can also use folders to organize groups of items. All the items that you add are 
persisted inside the package. 


References in the Script Task Project 


You can add references to managed assemblies by right-clicking the Script task project in Project Explorer, and 
then clicking Add Reference. For more information, see Referencing Other Assemblies in Scripting Solutions. 


NOTE 


You can view project references in the VSTA IDE in Class View or in Project Explorer. You open either of these windows 


from the View menu. You can add a new reference from the Project menu, from Project Explorer, or from Class View. 





Interacting with the Package in the Script Task 


The Script task uses the global Dts object, which is an instance of the ScriptObjectModel class, and its members 
to interact with the containing package and with the Integration Services runtime. 


The following table lists the principal public members of the ScriptObjectModel class, which is exposed to Script 
task code through the global Dts object. The topics in this section discuss the use of these members in more 
detail. 


MEMBER PURPOSE 

Connections Provides access to connection managers defined in the 
package. 

Events Provides an events interface to let the Script task raise 


errors, warnings, and informational messages. 


ExecutionValue Provides a simple way to return a single object to the 
runtime (in addition to the TaskResult) that can also be 
used for workflow branching. 


Log Logs information such as task progress and results to 
enabled log providers. 


TaskResult Reports the success or failure of the task. 


Transaction Provides the transaction, if any, within which the task's 
container is running. 


Variables Provides access to the variables listed in the 
ReadOnlyVariables and ReadWriteVariables task 
properties for use within the script. 


The ScriptObjectModel class also contains some public members that you will probably not use. 
MEMBER DESCRIPTION 


VariableDispenser The Variables property provides more convenient access to 
variables. Although you can use the VariableDispenser, you 
must explicitly call methods to lock and unlock variables for 
reading and writing. The Script task handles locking 
semantics for you when you use the Variables property. 


Debugging the Script Task 


To debug the code in your Script task, set at least one breakpoint in the code, and then close the VSTA IDE to run 
the package in SQL Server Data Tools (SSDT). When package execution enters the Script task, the VSTA IDE 
reopens and displays your code in read-only mode. After execution reaches your breakpoint, you can examine 
variable values and step through the remaining code. 


WARNING 
You cannot debug the Script task when you run the package in 64-bit mode. 








NOTE 


You must execute the package to debug into your Script task. If you execute only the individual task, breakpoints in the 


Script task code are ignored. 








NOTE 


You cannot debug a Script task when you run the Script task as part of a child package that is run from an Execute 
Package task. Breakpoints that you set in the Script task in the child package are disregarded in these circumstances. You 


can debug the child package normally by running it separately. 


NOTE 


When you debug a package that contains multiple Script tasks, the debugger debugs one Script task. The system can 
debug another Script task if the debugger completes, as in the case of a Foreach Loop or For Loop container. 





External Resources 


e Blog entry, VSTA setup and configuration troubles for SSIS 2008 and R2 installations, on blogs.msdn.com. 


See Also 


Referencing Other Assemblies in Scripting Solutions 
Configuring the Script Task in the Script Task Editor 





Using Variables in the Script Task 
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Variables make it possible for the Script task to exchange data with other objects in the package. For more 
information, see Integration Services (SSIS) Variables. 


The Script task uses the Variables property of the Dts object to read from and write to Variable objects in the 
package. 





NOTE 


The Value property of the Variable class is of type Object. Because the Script task has Option Strict enabled, you must 
cast the Value property to the appropriate type before you can use it. 





You add existing variables to the ReadOnlyVariables and ReadWriteVariables lists in the Script Task Editor to 
make them available to the custom script. Keep in mind that variable names are case-sensitive. Within the script, 
you access variables of both types through the Variables property of the Dts object. Use the Value property to 
read from and write to individual variables. The Script task transparently manages locking as the script reads 
and modifies the values of variables. 


You can use the Contains method of the Variables collection returned by the Variables property to check for the 
existence of a variable before using it in your code. 


You can also use the VariableDispenser property (Dts.VariableDispenser) to work with variables in the Script 
task. When using the VariableDispenser, you must handle both the locking semantics and the casting of data 
types for variable values in your own code. You may need to use the VariableDispenser property instead of the 
Variables property if you want to work with a variable that is not available at design time but is created 
programmatically at run time. 


Using the Script Task within a Foreach Loop Container 


When a Script task runs repeatedly within a Foreach Loop container, the script usually needs to work with the 
contents of the current item in the enumerator. For example, when using a Foreach File enumerator, the script 
needs to know the current file name; when using a Foreach ADO enumerator, the script needs to know the 
contents of the columns in the current row of data. 


Variables make this communication between the Foreach Loop container and the Script task possible. On the 
Variable Mappings page of the Foreach Loop Editor, assign variables to each item of data that is returned 
by a single enumerated item. For example, a Foreach File enumerator returns only a file name at Index 0 and 
therefore requires only one variable mapping, whereas an enumerator that returns several columns of data in 
each row requires you to map a different variable to each column that you want to use in the Script task. 


After you have mapped enumerated items to variables, then you must add the mapped variables to the 
ReadOnlyVariables property on the Script page of the Script Task Editor to make them available to your 
script. For an example of a Script task within a Foreach Loop container that processes the image files in a folder, 
see Working with Images with the Script Task. 


Variables Example 





The following example demonstrates how to access and use variables in a Script task to determine the path of 
package workflow. The sample assumes that you have created integer variables named customercount and 
MaxRecordcount and added them to the ReadOnlyVariables collection in the Script Task Editor. The 
CustomerCcount variable contains the number of customer records to be imported. If its value is greater than the 

value of MaxRecordcount , the Script task reports failure. When a failure occurs because the MaxRecordCount 


threshold has been exceeded, the error path of the workflow can implement any required clean-up. 


To successfully compile the sample, you need to add a reference to the Microsoft.SqlServerScriptTask assembly. 


Public Sub Main() 


Dim customerCount As Integer 
Dim maxRecordCount As Integer 


If Dts.Variables.Contains("CustomerCount") = True AndAlso _ 
Dts.Variables.Contains("MaxRecordCount") = True Then 


customerCount = _ 
CType(Dts.Variables("CustomerCount").Value, Integer) 

maxRecordCount = _ 
CType(Dts.Variables("MaxRecordCount").Value, Integer) 


End If 


If customerCount > maxRecordCount Then 
Dts.TaskResult = ScriptResults.Failure 
Else 
Dts.TaskResult = ScriptResults.Success 
End If 


End Sub 


using System; 
using System.Data; 
using Microsoft.SqlServer.Dts.Runtime; 


public class ScriptMain 


{ 
public void Main() 
{ 
int customerCount; 
int maxRecordCount; 
if (Dts.Variables.Contains("CustomerCount" )==true&&Dts.Variables.Contains("MaxRecordCount" )==true) 
{ 
customerCount = (int) Dts.Variables["CustomerCount"].Value; 
maxRecordCount = (int) Dts.Variables["MaxRecordCount"].Value; 
} 
if (customerCount>maxRecordCount) 
{ 
Dts.TaskResult = (int)ScriptResults.Failure; 
} 
else 
{ 
Dts.TaskResult = (int)ScriptResults.Success; 
} 
} 
} 


See Also 


Integration Services (SSIS) Variables 
Use Variables in Packages 
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Connection managers provide access to data sources that have been configured in the package. For more 
information, see Integration Services (SSIS) Connections. 


The Script task can access these connection managers through the Connections property of the Dts object. Each 
connection manager in the Connections collection stores information about how to connect to the underlying 
data source. 


When you call the AcquireConnection method of a connection manager, the connection manager connects to 
the data source, if it is not already connected, and returns the appropriate connection or connection information 
for you to use in your Script task code. 


NOTE 


You must know the type of connection returned by the connection manager before calling AcquireConnection. Because 
the Script task has Option Strict enabled, you must cast the connection, which is returned as type Object, to the 
appropriate connection type before you can use it. 











You can use the Contains method of the Connections collection returned by the Connections property to look 
for an existing connection before using the connection in your code. 





IMPORTANT 


You cannot call the AcquireConnection method of connection managers that return unmanaged objects, such as the OLE 
DB connection manager and the Excel connection manager, in the managed code of a Script task. However, you can read 
the ConnectionString property of these connection managers, and connect to the data source directly in your code by 
using the connection string with an OledbConnection from the System.Data.OleDb namespace. 


If you must call the AcquireConnection method of a connection manager that returns an unmanaged object, use an 
ADO.NET connection manager. When you configure the ADO.NET connection manager to use an OLE DB provider, it 
connects by using the .NET Framework Data Provider for OLE DB. In this case, the AcquireConnection method returns a 
System.Data.OleDb.OleDbConnection instead of an unmanaged object. To configure an ADO.NET connection 
manager for use with an Excel data source, select the Microsoft OLE DB Provider for Jet, specify an Excel file, and enter 

Excel 8.0 (for Excel 97 and later) as the value of Extended Properties on the All page of the Connection Manager 
dialog box. 











Connections Example 


The following example demonstrates how to access connection managers from within the Script task. The 
sample assumes that you have created and configured an ADO.NET connection manager named Test ADO.NET 
Connection and a Flat File connection manager named Test Flat File Connection. Note that the ADO.NET 
connection manager returns a SqlConnection object that you can use immediately to connect to the data 
source. The Flat File connection manager, on the other hand, returns only a string that contains the path and file 
name. You must use methods from the System.IO namespace to open and work with the flat file. 


Public Sub Main() 


Dim myADONETConnection As SqliClient.SqlConnection = 
DirectCast(Dts.Connections("Test ADO.NET Connection") .AcquireConnection(Dts.Transaction) , 
SqlClient.SqiConnection) 
MsgBox (myADONETConnection.ConnectionString, 
MsgBoxStyle.Information, "ADO.NET Connection") 


Dim myFlatFileConnection As String = 
DirectCast(Dts.Connections("Test Flat File Connection") .AcquireConnection(Dts.Transaction), 
String) 
MsgBox(myFlatFileConnection, MsgBoxStyle.Information, "Flat File Connection") 


Dts.TaskResult = ScriptResults.Success 


End Sub 


public void Main() 


{ 
SqlConnection myADONETConnection = 
Dts.Connections["Test ADO.NET Connection" ].AcquireConnection(Dts. Transaction) 
as SqlConnection; 
MessageBox. Show(myADONETConnection.ConnectionString, "ADO.NET Connection") ; 
string myFlatFileConnection = 
Dts.Connections["Test Flat File Connection"].AcquireConnection(Dts. Transaction) 
as string; 
MessageBox.Show(myFlatFileConnection, "Flat File Connection") ; 
Dts.TaskResult = (int)ScriptResults.Success; 
} 


See Also 


Integration Services (SSIS) Connections 
Create Connection Managers 
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Events provide a way to report errors, warnings, and other information, such as task progress or status, to the 
containing package. The package provides event handlers for managing event notifications. The Script task can 
raise events by calling methods on the Events property of the Dts object. For more information about how 
Integration Services packages handle events, see Integration Services (SSIS) Event Handlers. 


Events can be logged to any log provider that is enabled in the package. Log providers store information about 
events in a data store. The Script task can also use the Log method to log information to a log provider without 
raising an event. For more information about how to use the Log method, see Logging in the Script Task. 


To raise an event, the Script task calls one of the methods exposed by the Events property. The following table 
lists the methods exposed by the Events property. 


EVENT DESCRIPTION 

FireCustomEvent Raises a user-defined custom event in the package. 
FireError Informs the package of an error condition. 
Firelnformation Provides information to the user. 

FireProgress Informs the package of the progress of the task. 
FireQueryCancel Returns a value that indicates whether the package needs 


the task to shut down prematurely. 


FireWarning Informs the package that the task is in a state that warrants 
user notification, but is not an error condition. 


Events Example 


The following example demonstrates how to raise events from within the Script task. The example uses a native 
Windows API function to determine whether an Internet connection is available. If no connection is available, it 
raises an error. If a potentially volatile modem connection is in use, the example raises a warning. Otherwise, it 
returns an informational message that an Internet connection has been detected. 


Private Declare Function InternetGetConnectedState Lib "wininet” _ 
(ByRef dwFlags As Long, ByVal dwReserved As Long) As Long 


Private Enum ConnectedStates 


LAN = &H2 
Modem = &H1 
Proxy = &H4 


Offline = &H20 

Configured = &H40 

RasInstalled = &H10 
End Enum 


Public Sub Main() 
Dim dwFlags As Long 
Dim connectedState As Long 
Dim fireAgain as Boolean 


connectedState = InternetGetConnectedState(dwFlags, @) 


If connectedState <> @ Then 


If (dwFlags And ConnectedStates.Modem) = ConnectedStates.Modem Then 


Dts.Events.FireWarning(®, "Script Task Example", _ 


"Volatile Internet connection detected.", String.Empty, @) 


Else 
Dts.Events.FireInformation(@, "Script Task Example", _ 


"Internet connection detected.", String.Empty, ®, fireAgain) 


End If 
Else 

" If not connected to the Internet, raise an error. 
Dts.Events.FireError(®, "Script Task Example", _ 

"Internet connection not available.", String.Empty, 9) 


End Lf 


Dts.TaskResult = ScriptResults.Success 


End Sub 


using System; 

using System.Data; 

using Microsoft.SqlServer.Dts.Runtime; 
using System.Windows. Forms; 

using System.Runtime. InteropServices; 


public class ScriptMain 


{ 


[D1llImport("wininet") ] 
private extern static long InternetGetConnectedState(ref long dwFlags, long dwReserved) ; 


private enum ConnectedStates 
{ 
LAN = Ox2), 
Modem = @x1, 
Proxy = 0x4, 
Offline = @x2@, 
Configured = @x4@, 
RasInstalled = 0x10 


}3 


public void Main() 

{ 
// 
long dwFlags = 0; 
long connectedState; 
bool fireAgain = true; 
int state; 


connectedState = InternetGetConnectedState(ref dwFlags, 9); 
state = (int)ConnectedStates.Modem; 
if (connectedState != @) 
{ 
if ((dwFlags & state) == state) 
{ 


Dts.Events.FireWarning(®, "Script Task Example", "Volatile Internet connection 
detected.", String.Empty, @); 
} 


else 


{ 


Dts.Events.FireInformation(®, "Script Task Example", "Internet connection detected.", 
String.Empty, @, ref fireAgain); 
i; 
} 


else 


a 


// If not connected to the Internet, raise an error. 
Dts.Events.FireError(@, "Script Task Example", “Internet connection not available.", 
String.Empty, @); 
} 


Dts.TaskResult = (int)ScriptResults.Success; 


See Also 


Integration Services (SSIS) Event Handlers 
Add an Event Handler to a Package 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


The use of logging in Integration Services packages lets you record detailed information about execution 
progress, results, and problems by recording predefined events or user-defined messages for later analysis. The 
Script task can use the Log method of the Dts object to log user-defined data. If logging is enabled, and the 
ScriptTaskLogEntry event is selected for logging on the Details tab of the Configure SSIS Logs dialog box, 
a single call to the Log method stores the event information in all the log providers configured for the task. 


NOTE 


Although you can perform logging directly from your Script task, you may want to consider implementing events rather 
than logging. When using events, not only can you enable the logging of event messages, but you can also respond to 
the event with default or user-defined event handlers. 








For more information about logging, see Integration Services (SSIS) Logging. 


Logging Example 


The following example demonstrates logging from the Script task by logging a value that represents the 
number of rows processed. 


Public Sub Main() 


Dim rowsProcessed As Integer = 100 
Dim emptyBytes(@) As Byte 


Try 

Dts.Log("Rows processed: " & rowsProcessed.ToString, _ 
Q, _ 
emptyBytes) 

Dts.TaskResult = ScriptResults.Success 

Catch ex As Exception 

"An error occurred. 

Dts.Events.FireError(@, "Script Task Example", _ 
ex.Message & ControlChars.CrLf & ex.StackTrace, _ 
String.Empty, 0) 

Dts.TaskResult = ScriptResults.Failure 

End Try 


End Sub 


using System; 
using System.Data; 
using Microsoft.SqlServer.Dts.Runtime; 


public class ScriptMain 


{ 


public void Main() 


{ 
// 
int rowsProcessed = 1003 
new byte[Q]; 


byte[] emptyBytes 


try 

{ 
Dts.Log("Rows processed: " + rowsProcessed.ToString(), @, emptyBytes) ; 
Dts.TaskResult = (int)ScriptResults.Success; 

t 

catch (Exception ex) 

{ 


//An error occurred. 

Dts.Events.FireError(®@, "Script Task Example", ex.Message + "\r" + ex.StackTrace, 
String.Empty, 0); 

Dts.TaskResult = (int)ScriptResults.Failure; 


See Also 


Integration Services (SSIS) Logging 


Returning Results from the Script Task 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


The Script task uses the TaskResult and the optional ExecutionValue properties to return status information to 
the Integration Services runtime that can be used to determine the path of the workflow after the Script task has 
finished. 


TaskResult 
The TaskResult property reports whether the task succeeded or failed. For example: 


Dts.TaskResult = ScriptResults.Success 


ExecutionValue 


The ExecutionValue property optionally returns a user-defined object that quantifies or provides more 
information about the success or failure of the Script task. For example, the FTP task uses the ExecutionValue 
property to return the number of files transferred. The Execute SQL task returns the number of rows affected by 
the task. The ExecutionValue can also be used to determine the path of the workflow. For example: 


Dim rowsAffected as Integer 


rowsAffected = 1000 


Dts.ExecutionValue = rowsAffected 


Script Task Examples 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


The Script task is a multi-purpose tool that you can use in a package to fill almost any requirement that is not 
met by the tasks included with Integration Services. This topic lists Script task code samples that demonstrate 
some of the available functionality. 


NOTE 


If you want to create tasks that you can more easily reuse across multiple packages, consider using the code in these 
Script task samples as the starting point for custom tasks. For more information, see Developing a Custom Task. 











In This Section 


Example Topics 


This section contains code examples that demonstrate various uses of the .NET Framework classes that you can 
incorporate into an Integration Services Script task: 


Detecting an Empty Flat File with the Script Task 
Checks a flat file to determine whether it contains rows of data, and saves the result to a variable for use in 
control flow branching. 


Gathering a List for the ForEach Loop with the Script Task 
Gathers a list of files that meet user-specified criteria, and populates a variable for later use by the Foreach from 
Variable Enumerator. 


Querying the Active Directory with the Script Task 
Retrieves user information from Active Directory based on the value of an Integration Services variable, by 
using classes in the System.DirectoryServices namespace. 


Monitoring Performance Counters with the Script Task 
Creates a custom performance counter that can be used to track the execution progress of an Integration 
Services package, by using classes in the System.Diagnostics namespace. 


Working with Images with the Script Task 
Compresses images into the JPEG format and creates thumbnail images from them, by using classes in the 
System.Drawing namespace. 


Finding Installed Printers with the Script Task 
Locates installed printers that support a specific paper size, by using classes in the System.Drawing.Printing 
namespace. 


Sending an HTML Mail Message with the Script Task 
Sends a mail message in HTML format instead of plain text format. 


Working with Excel Files with the Script Task 
Lists the worksheets in an Excel file and checks for the existence of a specific worksheet. 


Sending to a Remote Private Message Queue with the Script Task 
Sends a message to a remote private message queue. 


Other Examples 


The following topics also contain code examples for use with the Script task: 


Using Variables in the Script Task 
Asks the user for confirmation of whether the package should continue to run, based on the value of a package 
variable that may exceed the limit specified in another variable. 


Connecting to Data Sources in the Script Task 


Retrieves a connection or connection information from connection managers defined in the package. 


Raising Events in the Script Task 
Raises an error, a warning, or an informational message based on the status of the Internet connection on the 


server. 


Logging in the Script Task 
Logs the number of items processed by the task to enabled log providers. 


Detecting an Empty Flat File with the Script Task 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


The Flat File source does not determine whether a flat file contains rows of data before attempting to process it. 
You may want to improve the efficiency of a package, especially of a package that iterates over numerous flat 
files, by skipping files that do not contain any rows of data. The Script task can look for an empty flat file before 
the package begins to process the data flow. 





NOTE 


If you want to create a task that you can more easily reuse across multiple packages, consider using the code in this Script 
task sample as the starting point for a custom task. For more information, see Developing a Custom Task. 





Description 


The following example uses methods from the System.IO namespace to test the flat file specified in a Flat File 
connection manager to determine whether the file is empty, or whether it contains only expected non-data rows 
such as column headers or an empty line. The script checks the size of the file first; if the size is zero bytes, the 
file is empty. If the file size is greater than zero, the script reads lines from the file until there are no more lines, 
or until the number of lines exceeds the expected number of non-data rows. If the number of lines in the file is 
less than or equal to the expected number of non-data rows, then the file is considered empty. The result is 
returned as a Boolean value in a user variable, the value of which can be used for branching in the package's 
control flow. The Firelnformation method also displays the result in the Output window of the Microsoft 
Visual Studio Tools for Applications (VSTA). 


To configure this Script Task example 


1. Create and configure a flat file connection manager named EmptyFlatFileTest. 


2. Create an integer variable named FFNonDataRows and set its value to the number of non-data rows 


expected in the flat file. 
3. Create a Boolean variable named FFIsEmpty . 
4. Add the FFNonDataRows variable to the Script task's ReadOnlyVariables property. 
5. Add the FFIsempty variable to the Script task's ReadWriteVariables property. 
6. In your code, import the System.IO namespace. 


If you are iterating over files with a Foreach File enumerator, instead of using a single Flat File connection 
manager, you will need to modify the sample code below to obtain the file name and path from the variable in 
which the enumerated value is stored instead of from the connection manager. 


Code 





Public Sub Main() 


Dim nonDataRows As Integer = _ 
DirectCast(Dts.Variables("FFNonDataRows").Value, Integer) 
Dim ffConnection As String = _ 


DirectCast(Dts.Connections("EmptyFlatFileTest").AcquireConnection(Nothing), _ 


String) 
Dim flatFileInfo As New FileInfo(ffConnection) 
' If file size is @ bytes, flat file does not contain data. 
Dim fileSize As Long = flatFileInfo.Length 
If fileSize > @ Then 
Dim lineCount As Integer = @ 
Dim line As String 
Dim fsFlatFile As New StreamReader(ffConnection) 
Do Until fsFlatFile.EndOfStream 
line = fsFlatFile.ReadLine 
lineCount += 1 
" If line count > expected number of non-data rows, 
"flat file contains data (default value). 
If lineCount > nonDataRows Then 
Exit Do 
End If 


If line count <= expected number of non-data rows, 
"flat file does not contain data. 
If lineCount <= nonDataRows Then 
Dts.Variables("FFIsEmpty").Value = True 
End If 
Loop 
Else 
Dts.Variables("FFIsEmpty").Value = True 
End If 


Dim fireAgain As Boolean = False 

Dts.Events.FireInformation(@, "Script Task", _ 
String.Format("{0}: {1}", ffConnection, _ 
Dts.Variables("FFIsEmpty").Value.ToString), _ 
String.Empty, @, fireAgain) 


Dts.TaskResult = ScriptResults.Success 


End Sub 


public void Main() 
{ 


int nonDataRows = (int) (Dts.Variables["FFNonDataRows"].Value) ; 

string ffConnection = (string) (Dts.Connections["EmptyFlatFileTest"].AcquireConnection(null) 
String); 

FileInfo flatFileInfo = new FileInfo(ffConnection) ; 

// If file size is @ bytes, flat file does not contain data. 

long fileSize = flatFileInfo.Length; 

if (fileSize > @) 


{ 
int lineCount = @;3 
string line; 
StreamReader fsFlatFile = new StreamReader(ffConnection) ; 
while (!(fsFlatFile.EndOfStream) ) 
{ 
Console.WriteLine (fsFlatFile.ReadLine()); 
lineCount += 1; 
// If line count > expected number of non-data rows, 
// flat file contains data (default value). 
if (lineCount > nonDataRows) 
if 
break; 
t 
// If line count <= expected number of non-data rows, 
// flat file does not contain data. 
if (lineCount <= nonDataRows) 
{ 
Dts.Variables["FFIsEmpty"].Value = true; 
t 
} 
} 
else 
{ 
Dts.Variables["FFIsEmpty"].Value = true; 
t 


bool fireAgain = false; 
Dts.Events.FireInformation(®, "Script Task", String.Format("{@}: {1}", ffConnection, 
Dts.Variables["FFIsEmpty"].Value), String.Empty, @, ref fireAgain) ; 


Dts.TaskResult = (int)ScriptResults.Success; 


See Also 


Script Task Examples 


Finding Installed Printers with the Script Task 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


The data that is transformed by Integration Services packages often has a printed report as its final destination. 
The System.Drawing.Printing namespace in the Microsoft .NET Framework provides classes for working with 
printers. 


NOTE 


If you want to create a task that you can more easily reuse across multiple packages, consider using the code in this Script 
task sample as the starting point for a custom task. For more information, see Developing a Custom Task. 











Description 


The following example locates printers installed on the server that support legal size paper (as used in the 
United States). The code to check supported paper sizes is encapsulated in a private function. To enable you to 
track the progress of the script as it checks the settings for each printer, the script uses the Log method to raise 
an informational message for printers with legal size paper, and to raise a warning for printers without legal size 
paper. These messages appear in the Output window of the Microsoft Visual Studio Tools for Applications 
(VSTA) IDE when you run the package in the designer. 


To configure this Script Task example 


1. Create the variable named PrinterList with type Object. 
2. On the Script page of the Script Task Editor, add this variable to the ReadWriteVariables property. 
3. In the script project, add a reference to the System.Drawing namespace. 


4. In your code, use Imports statements to import the System.Collections and the 
System.Drawing.Printing namespaces. 


Code 


Public Sub Main() 


Dim printerName As String 
Dim currentPrinter As New PrinterSettings 
Dim size As PaperSize 


Dim printerList As New ArrayList 
For Each printerName In PrinterSettings.InstalledPrinters 
currentPrinter.PrinterName = printerName 
If PrinterHasLegalPaper(currentPrinter) Then 
printerList.Add(printerName) 
Dts.Events.FireInformation(@, "Example", _ 
"Printer " & printerName & " has legal paper.", _ 
String.Empty, 9, False) 
Else 
Dts.Events.FireWarning(®, "Example", _ 


"Printer " & printerName & " DOES NOT have legal paper.", _ 


String.Empty, @) 
End If 
Next 
Dts.Variables("PrinterList").Value = printerList 
Dts.TaskResult = ScriptResults.Success 


End Sub 


Private Function PrinterHasLegalPaper( _ 
ByVal thisPrinter As PrinterSettings) As Boolean 


Dim size As PaperSize 
Dim hasLegal As Boolean = False 


For Each size In thisPrinter.PaperSizes 
If size.Kind = PaperKind.Legal Then 
True 


hasLegal 
End If 
Next 


Return hasLegal 


End Function 


public void Main() 
{ 


PrinterSettings currentPrinter = new PrinterSettings(); 
PaperSize size; 
Boolean Flag = false; 


ArrayList printerList = new ArrayList(); 
foreach (string printerName in PrinterSettings.InstalledPrinters) 
{ 
currentPrinter.PrinterName = printerName; 
if (PrinterHasLegalPaper(currentPrinter) ) 
{ 
printerList.Add(printerName) ; 


Dts.Events.FireInformation(®, "Example", "Printer " + printerName + " has legal paper.", 
String.Empty, @, ref Flag); 
} 
else 
{ 
Dts.Events.FireWarning(®, "Example", "Printer " + printerName + " DOES NOT have legal 
paper.", String.Empty, @); 


y 


Dts.Variables["PrinterList"].Value = printerList; 


Dts.TaskResult = (int)ScriptResults.Success; 


} 
private bool PrinterHasLegalPaper(PrinterSettings thisPrinter) 
{ 
bool hasLegal = false; 
foreach (PaperSize size in thisPrinter.PaperSizes) 
{ 
if (size.Kind == PaperKind.Legal) 
{ 
hasLegal = true; 
} 
} 
return hasLegal; 
i 


See Also 


Script Task Examples 


Gathering a List for the ForEach Loop with the 


Script Task 
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Applies to: Q sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


The Foreach from Variable Enumerator enumerates over the items in a list that is passed to it in a variable and 
performs the same tasks on each item. You can use custom code in a Script task to populate a list for this 
purpose. For more information about the enumerator, see Foreach Loop Container. 





NOTE 


If you want to create a task that you can more easily reuse across multiple packages, consider using the code in this Script 
task sample as the starting point for a custom task. For more information, see Developing a Custom Task. 





Description 


The following example uses methods from the System.IO namespace to gather a list of Excel workbooks on the 
computer that are either newer or older than a number of days specified by the user in a variable. It searches 
directories on Drive C recursively for files that have the .xls extension and examines the date on which each file 
was last modified to determine whether the file belongs in the list. It adds qualifying files to an ArrayList and 
saves the ArrayList to a variable for later use in a Foreach Loop container. The Foreach Loop container is 
configured to use the Foreach from Variable enumerator. 








NOTE 


The variable that you use with the Foreach from Variable Enumerator must be of type Object. The object that you place 
in the variable must implement one of the following interfaces: System.Collections.|Enumerable, 
System.Runtime.InteropServices.ComTypes.|EnumVARIANT, System.ComponentModel IListSource, or 
Microsoft.SqlServer.Dts.Runtime.Wrapper.ForEachEnumeratorHost. An Array or ArrayList is commonly used. 
The ArrayList requires a reference and an Imports statement for the System.Collections namespace. 





You can experiment with this task by using different positive and negative values for the FileAge package 
variable. For example, you can enter 5 to search for files created in the last five days, or enter -3 to search for 
files that were created more than three days ago. This task may take a minute or two on a drive with many 
folders to search. 


To configure this Script Task example 

1. Create a package variable named FileAge of type integer and enter a positive or negative integer value. 
When the value is positive, the code searches for files newer than the specified number of days; when 
negative, for files older than the specified number of days. 


2. Create a package variable named FileList of type Object to receive the list of files gathered by the 
Script task for later use by the Foreach from Variable Enumerator. 


3. Add the FileAge variable to the Script task's ReadOnlyVariables property, and add the FileList 
variable to the ReadWriteVariables property. 


4. In your code, import the System.Collections and the System.IO namespaces. 





Code 


Imports System 

Imports System.Data 

Imports System.Math 

Imports Microsoft.SqlServer.Dts.Runtime 
Imports System.Collections 

Imports System.IO 


Public Class ScriptMain 


Private Const FILE_AGE As Integer =50 
Private Const FILE_ROOT As String = "C:\" 
Private Const FILE_FILTER As String = "*.xls" 


Private isCheckForNewer As Boolean = True 
Dim fileAgeLimit As Integer 
Private listForEnumerator As ArrayList 


Public Sub Main() 


fileAgeLimit = DirectCast(Dts.Variables("FileAge").Value, Integer) 
" If value provided is positive, we want files NEWER THAN n days. 
"If negative, we want files OLDER THAN n days. 
If fileAgeLimit < @ Then 

isCheckForNewer = False 
End If 


Extract number of days as positive integer. 
fileAgeLimit = Math.Abs(fileAgeLimit) 


listForEnumerator = New ArrayList 
GetFilesInFolder(FILE_ROOT) 


" Return the list of files to the variable 
"for later use by the Foreach from Variable enumerator. 

System.Windows.Forms .MessageBox.Show("Matching files: " & listForEnumerator.Count.ToString, "Results", 
Windows. Forms.MessageBoxButtons.OK, Windows.Forms.MessageBoxIcon. Information) 


Dts.Variables("FileList").Value = listForEnumerator 
Dts.TaskResult = ScriptResults.Success 

End Sub 

Private Sub GetFilesInFolder(ByVal folderPath As String) 


Dim localFiles() As String 
Dim localFile As String 

Dim fileChangeDate As Date 
Dim fileAge As TimeSpan 

Dim fileAgeInDays As Integer 
Dim childFolder As String 


Try 

localFiles = Directory.GetFiles(folderPath, FILE_FILTER) 

For Each localFile In localFiles 
fileChangeDate = File.GetLastWriteTime(localFile) 
fileAge = DateTime.Now.Subtract(fileChangeDate) 
fileAgeInDays = fileAge.Days 
CheckAgeOfFile(localFile, fileAgeInDays) 

Next 


If Directory.GetDirectories(folderPath).Length > @ Then 
For Each childFolder In Directory.GetDirectories(folderPath) 
GetFilesInFolder(childFolder) 
Next 


End If 


Catch 


Ignore exceptions on special folders such as System Volume Information. 
End Try 


End Sub 
Private Sub CheckAgeOfFile(ByVal localFile As String, ByVal fileAgeInDays As Integer) 


If isCheckForNewer Then 
If fileAgeInDays <= fileAgeLimit Then 
listForEnumerator.Add(localFile) 
End If 
Else 
If fileAgeInDays > fileAgeLimit Then 
listForEnumerator.Add(localFile) 
End If 
End If 


End Sub 


End Class 


using System; 

using System.Data; 

using System.Math; 

using Microsoft.SqlServer.Dts.Runtime; 
using System.Collections; 

using System.I0; 


public partial class ScriptMain : Microsoft.SqlServer.Dts.Tasks.ScriptTask.VSTARTScriptObjectModelBase 
{ 


private const int FILE_AGE = -5@; 


private const string FILE_ROOT = "C:\\"; 
private const string FILE_FILTER = "*.xls"; 


private bool isCheckForNewer = true; 
int fileAgeLimit; 
private ArrayList listForEnumerator; 


public void Main() 


fileAgeLimit = (int)(Dts.Variables["FileAge"].Value) ; 


// If value provided is positive, we want files NEWER THAN n days. 
// If negative, we want files OLDER THAN n days. 
if (fileAgeLimit<@) 
{ 
isCheckForNewer = false; 
} 
// Extract number of days as positive integer. 
fileAgeLimit = Math.Abs(fileAgeLimit) ; 


listForEnumerator = new ArrayList(); 
GetFilesInFolder(FILE_ROOT); 


// Return the list of files to the variable 

// for later use by the Foreach from Variable enumerator. 

System.Windows.Forms .MessageBox.Show("Matching files: "+ listForEnumerator.Count, "Results", 
MessageBoxButtons.OK, MessageBoxIcon. Information) ; 

Dts.Variables["FileList"].Value = listForEnumerator; 


Dts.TaskResult = (int)ScriptResults.Success; 


t 
private void GetFilesInFolder(string folderPath) 
{ 
string[] localFiles; 
DateTime fileChangeDate; 
TimeSpan fileAge; 
int fileAgeInDays; 
try 
{ 
localFiles = Directory.GetFiles(folderPath, FILE_FILTER); 
foreach (string localFile in localFiles) 
{ 
fileChangeDate = File.GetLastWriteTime(localFile) ; 
fileAge = DateTime.Now.Subtract(fileChangeDate) ; 
fileAgeInDays = fileAge.Days; 
CheckAgeOfFile(localFile, fileAgeInDays) ; 
} 
if (Directory.GetDirectories(folderPath).Length > @) 
{ 
foreach (string childFolder in Directory.GetDirectories(folderPath) ) 
{ 
GetFilesInFolder(childFolder) ; 
} 
} 
} 
catch 
{ 
// Ignore exceptions on special folders, such as System Volume Information. 
t 
} 
private void CheckAgeOfFile(string localFile, int fileAgeInDays) 
{ 
if (isCheckForNewer) 
{ 
if (fileAgeInDays <= fileAgeLimit) 
{ 
listForEnumerator.Add(localFile) ; 
} 
} 
else 
{ 
if (fileAgeInDays > fileAgeLimit) 
{ 
listForEnumerator.Add(localFile); 
t 
t 
t 
i 
See Also 


Foreach Loop Container 
Configure a Foreach Loop Container 


Monitoring Performance Counters with the Script 


Task 
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Applies to: Q sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Administrators may need to monitor the performance of Integration Services packages that perform complex 
transformations on large amounts of data. The System.Diagnostics namespace of the Microsoft .NET 
Framework provides classes for using existing performance counters and for creating your own performance 
counters. 


Performance counters store application performance information that you can use to analyze the performance 
of software over time. Performance counters can be monitored locally or remotely by using the Performance 
Monitor tool. You can store the values of performance counters in variables for later control flow branching in 
the package. 


As an alternative to using performance counters, you can raise the FireProgress event through the Events 
property of the Dts object. The FireProgress event returns both incremental progress and percentage complete 
information to the Integration Services runtime. 


NOTE 


If you want to create a task that you can more easily reuse across multiple packages, consider using the code in this Script 
task sample as the starting point for a custom task. For more information, see Developing a Custom Task. 





Description 


The following example creates a custom performance counter and increments the counter. First, the example 
determines whether the performance counter already exists. If the performance counter has not been created, 
the script calls the Create method of the PerformanceCounterCategory object to create it. After the 
performance counter has been created, the script increments the counter. Finally, the example follows the best 
practice of calling the Close method on the performance counter when it is no longer needed. 


NOTE 


Creating a new performance counter category and performance counter requires administrative rights. Also, the new 


category and counter persist on the computer after creation. 





To configure this Script Task example 


e Use an Imports statement in your code to import the System.Diagnostics namespace. 


Example Code 


Public Sub Main() 


Dim 


Try 


myCounter As PerformanceCounter 


"Create the performance counter if it does not already exist. 
ENO Gee 
PerformanceCounterCategory.Exists("TaskExample") Then 
PerformanceCounterCategory.Create("TaskExample", _ 
"Task Performance Counter Example", "Iterations", _ 
"Number of times this task has been called.") 
End If 


"Initialize the performance counter. 
myCounter = New PerformanceCounter("TaskExample", _ 
"Iterations", String.Empty, False) 


"Increment the performance counter. 
myCounter. Increment () 


myCounter.Close() 
Dts.TaskResult = ScriptResults.Success 


Catch ex As Exception 


End 


End Sub 


Dts.Events.FireError(@, _ 
"Task Performance Counter Example", _ 
ex.Message & ControlChars.CrLf & ex.StackTrace, _ 
String.Empty, 0) 

Dts.TaskResult = ScriptResults.Failure 

Try 


public class ScriptMain 


{ 


public void Main() 
{ 


PerformanceCounter myCounter; 


try 

{ 
//Create the performance counter if it does not already exist. 
if (!PerformanceCounterCategory.Exists("TaskExample") ) 


{ 


PerformanceCounterCategory.Create("TaskExample", "Task Performance Counter Example", 
"Iterations", "Number of times this task has been called."); 


} 


//Initialize the performance counter. 
myCounter = new PerformanceCounter("TaskExample", "Iterations", String.Empty, false); 


//Increment the performance counter. 
myCounter.Increment() ; 


myCounter.Close(); 
Dts.TaskResult = (int)ScriptResults.Success; 


} 


catch (Exception ex) 


{ 


Dts.Events.FireError(@, "Task Performance Counter Example", ex.Message + "\r" + 
ex.StackTrace, String.Empty, @); 
Dts.TaskResult = (int)ScriptResults.Failure; 


Dts.TaskResult = (int)ScriptResults.Success; 


Querying the Active Directory with the Script Task 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Enterprise data processing applications, such as Integration Services packages, often need to process data 
differently based on the rank, job title, or other characteristics of employees stored in Active Directory. Active 
Directory is a Microsoft Windows directory service that provides a centralized store of metadata, not only about 
users, but also about other organizational assets such as computers and printers. The 
System.DirectoryServices namespace in the Microsoft .NET Framework provides classes for working with 
Active Directory, to help you direct data processing workflow based on the information that it stores. 


NOTE 


If you want to create a task that you can more easily reuse across multiple packages, consider using the code in this Script 


task sample as the starting point for a custom task. For more information, see Developing a Custom Task. 





Description 


The following example retrieves an employee's name, title, and phone number from Active Directory based on 
the value of the email variable, which contains the e-mail address of the employee. Precedence constraints in 
the package can use the retrieved information to determine, for example, whether to send a low-priority e-mail 
message or a high-priority page, based on the job title of the employee. 


To configure this Script Task example 
1. Create the three string variables email , name , and title . Enter a valid corporate email address as the 
value of the email variable. 


2. On the Script page of the Script Task Editor, add the email variable to the ReadOnlyVariables 
property. 


3. Add the name and title variables to the ReadWriteVariables property. 
4. In the script project, add a reference to the System.DirectoryServices namespace. 


5. . In your code, use anImports statement to import the DirectoryServices namespace. 





NOTE 


To run this script successfully, your company must be using Active Directory on its network and storing the employee 
information that this example uses. 











Code 


Public Sub Main() 


Dim directory As DirectoryServices.DirectorySearcher 
Dim result As DirectoryServices.SearchResult 
Dim email As String 


email = Dts.Variables("email") .Value.ToString 


Try 
directory = New _ 
DirectoryServices.DirectorySearcher("(mail=" & email & ")") 
result = directory.FindOne 
Dts.Variables("name").Value = _ 
result.Properties("displayname").ToString 
Dts.Variables("title").Value = _ 
result.Properties("title").ToString 
Dts.TaskResult = ScriptResults.Success 
Catch ex As Exception 
Dts.Events.FireError(@, _ 
"Script Task Example", _ 
ex.Message & ControlChars.CrLf & ex.StackTrace, _ 
String.Empty, @) 
Dts.TaskResult = ScriptResults.Failure 
End Try 


End Sub 


public void Main() 


{ 

// 

DirectorySearcher directory; 

SearchResult result; 

string email; 

email = (string)Dts.Variables["email"].Value; 

try 

{ 
directory = new DirectorySearcher("(mail=" + email + ")"); 
result = directory.FindOne(); 
Dts.Variables["name"].Value = result.Properties["displayname"].ToString(); 
Dts.Variables["title"].Value = result.Properties["title"].ToString(); 
Dts.TaskResult = (int)ScriptResults.Success; 

} 

catch (Exception ex) 

{ 
Dts.Events.FireError(®@, "Script Task Example", ex.Message + "\n" + ex.StackTrace, String.Empty, @); 
Dts.TaskResult = (int)ScriptResults.Failure; 

} 

} 
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External Resources 


e Technical article, Processing Active Directory Information in SSIS, on social.technet.microsoft.com 


Sending an HTML Mail Message with the Script 


Task 
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Applies to: Q sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


The Integration Services SendMail task only supports mail messages in plain text format. However you can 
easily send HTML mail messages by using the Script task and the mail capabilities of the .NET Framework. 


NOTE 


If you want to create a task that you can more easily reuse across multiple packages, consider using the code in this Script 
task sample as the starting point for a custom task. For more information, see Developing a Custom Task. 











Description 


The following example uses the System.Net.Mail namespace to configure and send an HTML mail message. 
The script obtains the To, From, Subject, and body of the e-mail from package variables, uses them to create a 
new MailMessage, and sets its IsBodyHtml property to True. Then it obtains the SMTP server name from 
another package variable, initializes an instance of System.Net.Mail.SmtpClient, and calls its Send method to 
send the HTML message. The sample encapsulates the message sending functionality in a subroutine that could 
be reused in other scripts. 


To configure this Script Task example without an SMTP Connection Manager 
1. Create string variables named HtmlEmailTo , HtmlemailFrom , and Htmlemailsubject and assign 


appropriate values to them for a valid test message. 


2. Create a string variable named HtmlEmailBody and assign a string of HTML markup to it. For example: 
<html><body><h1>Testing</h1><p>This is a <b>test</b> message.</p></body></htm1> 


3. Create a string variable named HtmlEmailserver and assign the name of an available SMTP server that 
accepts anonymous outgoing messages. 


4. Assign all five of these variables to the ReadOnlyVariables property of a new Script task. 
5. Import the System.Net and System.Net.Mail namespaces into your code. 


The sample code in this topic obtains the SMTP server name from a package variable. However, you could also 
take advantage of an SMTP connection manager to encapsulate the connection information, and extract the 
server name from the connection manager in your code. The AcquireConnection method of the SMTP 


connection manager returns a string in the following format: 
SmtpServer=smtphost ; UseWindowsAuthentication=False;EnableSsl=False; 


You can use the String.Split method to separate this argument list into an array of individual strings at each 
semicolon (;) or equal sign (=), and then extract the second argument (subscript 1) from the array as the server 
name. 


To configure this Script Task example with an SMTP Connection Manager 


1. Modify the Script task configured earlier by removing the HtmlemailServer variable from the list of 


ReadOnlyVariables. 


2. Replace the line of code that obtains the server name: 


Dim smtpServer As String = _ 
Dts.Variables("HtmlEmailServer") .Value.ToString 


with the following lines: 


Dim smtpConnectionString As String = _ 

DirectCast(Dts.Connections("SMTP Connection Manager") .AcquireConnection(Dts.Transaction), String) 
Dim smtpServer As String = _ 

smtpConnectionString.Split(New Char() {"="c, ";"c})(1) 


Code 


Public Sub Main() 


Dim htmlMessageFrom As String = _ 
Dts.Variables("HtmlEmailFrom") .Value.ToString 

Dim htmlMessageTo As String = _ 
Dts.Variables("HtmlEmailTo") .Value.ToString 

Dim htmlMessageSubject As String = _ 
Dts.Variables("HtmlEmailSubject") .Value. ToString 

Dim htmlMessageBody As String = _ 
Dts.Variables("HtmlEmailBody").Value.ToString 

Dim smtpServer As String = _ 
Dts.Variables("HtmlEmailServer") .Value.ToString 


SendMailMessage( _ 
htmlMessageFrom, htmlMessageTo, _ 
htmlMessageSubject, htmlMessageBody, _ 
True, smtpServer) 


Dts.TaskResult = ScriptResults.Success 
End Sub 


Private Sub SendMailMessage( _ 
ByVal From As String, ByVal SendTo As String, 
ByVal Subject As String, ByVal Body As String, _ 
ByVal IsBodyHtml As Boolean, ByVal Server As String) 


Dim htmlMessage As MailMessage 
Dim mySmtpClient As SmtpClient 


htmlMessage = New MailMessage( _ 
From, SendTo, Subject, Body) 
htmlMessage.IsBodyHtml = IsBodyHtml 


mySmtpClient = New SmtpClient(Server) 
mySmtpClient.Credentials = CredentialCache.DefaultNetworkCredentials 


mySmtpClient.Send(htmlMessage) 


End Sub 


public void 


{ 


smtpServer) ; 


Main() 


string htmlMessageFrom = Dts.Variables["HtmlEmailFrom"].Value.ToString() ; 
string htmlMessageTo = Dts.Variables["HtmlEmailTo"].Value.ToString() ; 

string htmlMessageSubject = Dts.Variables["HtmlEmailSubject"].Value.ToString(); 
string htmlMessageBody = Dts.Variables["HtmlEmailBody"].Value.ToString() ; 
string smtpServer = Dts.Variables["HtmlEmailServer"].Value.ToString(); 


SendMailMessage(htmlMessageFrom, htmlMessageTo, htmlMessageSubject, htmlMessageBody, true, 


Dts.TaskResult = (int)ScriptResults.Success; 


private void SendMailMessage(string From, string SendTo, string Subject, string Body, bool 


IsBodyHtml, 
{ 


See Also 


Send Mail Task 


string Server) 


MailMessage htmlMessage; 
SmtpClient mySmtpClient; 


htmlMessage = new MailMessage(From, SendTo, Subject, Body); 
htmlMessage.IsBodyHtml = IsBodyHtml; 


mySmtpClient = new SmtpClient(Server) ; 
mySmtpClient.Credentials = CredentialCache.DefaultNetworkCredentials; 
mySmtpClient.Send(htmlMessage) ; 


Sending to a Remote Private Message Queue with 


the Script Task 


11/23/2021 + 2 minutes to read * Edit Online 





Applies to: Q sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Message Queuing (also known as MSMQ) makes it easy for developers to communicate with application 
programs quickly and reliably by sending and receiving messages. A message queue may be located on the 
local computer or a remote computer, and may be public or private. In Integration Services, the MSMQ 
connection manager and Message Queue task do not support sending to a private queue on a remote computer. 
However, by using the Script task, it is easy to send a message to a remote private queue. 


NOTE 


If you want to create a task that you can more easily reuse across multiple packages, consider using the code in this Script 


task sample as the starting point for a custom task. For more information, see Developing a Custom Task. 





Description 


The following example uses an existing MSMQ connection manager, together with objects and methods from 
the System.Messaging namespace, to send the text contained in a package variable to a remote private message 
queue. The call to the 

M:Microsoft.SqlServer.Dts.:ManagedConnections. MSMQConn.AcquireConnection(System.Object) method of the 
MSMQ connection manager returns a MessageQueue object whose Send method accomplishes this task. 


To configure this Script Task example 
1. Create an MSMQ connection manager with the default name. Set the path of a valid remote private 
queue, in the following format: 


FORMATNAME : DIRECT=0S : <computername>\private$\<queuename> 


2. Create an Integration Services variable named MessageText of type String to pass the message text into 
the script. Enter a default message as the value of the variable. 


3. Add a Script Task to the design surface and edit it. On the Script tab of the Script Task Editor, add the 
MessageText variable to the ReadOnlyVariables property to make the variable available inside the 
script. 


4. Click Edit Script to open the Microsoft Visual Studio Tools for Applications (VSTA) script editor. 
5. Add a reference in the script project to the System.Messaging namespace. 


6. Replace the contents of the script window with the code in the following section. 


Code 


Imports System 
Imports Microsoft.SqlServer.Dts.Runtime 
Imports System.Messaging 


Public Class ScriptMain 
Public Sub Main() 


Dim remotePrivateQueue As MessageQueue 
Dim messageText As String 


remotePrivateQueue = _ 
DirectCast(Dts.Connections("Message Queue Connection 
Manager") .AcquireConnection(Dts.Transaction), _ 
MessageQueue) 
messageText = DirectCast(Dts.Variables("MessageText").Value, String) 
remotePrivateQueue.Send(messageText ) 


Dts.TaskResult = ScriptResults.Success 
End Sub 


End Class 


using System; 
using Microsoft.SqlServer.Dts.Runtime; 
using System.Messaging; 


public class ScriptMain 


{ 


public void Main() 
ib 


MessageQueue remotePrivateQueue = new MessageQueue() ; 
string messageText; 


remotePrivateQueue = (MessageQueue) (Dts.Connections[ "Message Queue Connection 
Manager" ].AcquireConnection(Dts.Transaction) as MessageQueue) ; 
messageText = (string) (Dts.Variables["MessageText"].Value) ; 


remotePrivateQueue.Send(messageText) ; 


Dts.TaskResult = (int)ScriptResults.Success; 


See Also 


Message Queue Task 


Working with Excel Files with the Script Task 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Integration Services provides the Excel connection manager, Excel source, and Excel destination for working with 
data stored in spreadsheets in the Microsoft Excel file format. The techniques described in this topic use the 
Script task to obtain information about available Excel databases (workbook files) and tables (worksheets and 
named ranges). 





IMPORTANT 


For detailed info about connecting to Excel files, and about limitations and known issues for loading data from or to Excel 


files, see Load data from or to Excel with SQL Server Integration Services (SSIS). 


TIP 


If you want to create a task that you can reuse across multiple packages, consider using the code in this Script task 


sample as the starting point for a custom task. For more information, see Developing a Custom Task. 





Configuring a Package to Test the Samples 


You can configure a single package to test all the samples in this topic. The samples use many of the same 
package variables and the same .NET Framework classes. 


To configure a package for use with the examples in this topic 


1. Create a new Integration Services project in SQL Server Data Tools (SSDT) and open the default package 
for editing. 


2. Variables. Open the Variables window and define the following variables: 
@ excelFile , of type String. Enter the complete path and filename to an existing Excel workbook. 


@ ExcelTable , of type String. Enter the name of an existing worksheet or named range in the 
workbook named in the value of the ExcelFile variable. This value is case-sensitive. 


@ excelFileExists , of type Boolean. 


ExcelTableExists , of type Boolean. 


@ excelFolder , of type String. Enter the complete path of a folder that contains at least one Excel 
workbook. 


e@ excelFiles , of type Object. 
@ excelTables , of type Object. 


3. Imports statements. Most of the code samples require you to import one or both of the following .NET 
Framework namespaces at the top of your script file: 


e System.IO, for file system operations. 


e System.Data.OleDb, to open Excel files as data sources. 





. References. The code samples that read schema information from Excel files require an additional 


reference in the script project to the System.Xml namespace. 


. Set the default scripting language for the Script component by using the Scripting language option on 


the General page of the Options dialog box. For more information, see General Page. 


Example 1 Description: Check Whether an Excel File Exists 


This example determines whether the Excel workbook file specified in the ExcelFile variable exists, and then 


sets the Boolean value of the ExcelFileExists variable to the result. You can use this Boolean value for 


branching in the workflow of the package. 


To configure this Script Task example 


1. 


2. 


5: 


6. 


Add a new Script task to the package and change its name to ExcelFileExists. 


In the Script Task Editor, on the Script tab, click ReadOnlyVariables and enter the property value 
using one of the following methods: 


e Type ExcelFile. 
-Or- 


e Click the ellipsis (...) button next to the property field, and in the Select variables dialog box, 
select the ExcelFile variable. 


. Click ReadWriteVariables and enter the property value using one of the following methods: 


e Type ExcelFileExists. 
-Or- 


e Click the ellipsis (...) button next to the property field, and in the Select variables dialog box, 
select the ExcelFileExists variable. 


. Click Edit Script to open the script editor. 


Add an Imports statement for the System.IO namespace at the top of the script file. 


Add the following code. 


Example 1 Code 


Public Class ScriptMain 
Public Sub Main() 
Dim fileToTest As String 


fileToTest = Dts.Variables("ExcelFile").Value.ToString 
If File.Exists(fileToTest) Then 
Dts.Variables("ExcelFileExists").Value = True 
Else 
Dts.Variables("ExcelFileExists").Value = False 
End If 


Dts.TaskResult = ScriptResults.Success 
End Sub 
End Class 


public class ScriptMain 


{ 
public void Main() 


{ 
string fileToTest; 


fileToTest = Dts.Variables["ExcelFile"].Value.ToString(); 
if (File.Exists(fileToTest) ) 
{ 


Dts.Variables["ExcelFileExists"].Value = true; 


} 


else 


if 


Dts.Variables["ExcelFileExists"].Value = false; 


} 


Dts.TaskResult = (int)ScriptResults.Success; 


Example 2 Description: Check Whether an Excel Table Exists 


This example determines whether the Excel worksheet or named range specified in the ExcelTable variable 


exists in the Excel workbook file specified in the ExcelFile variable, and then sets the Boolean value of the 


ExcelTableExists variable to the result. You can use this Boolean value for branching in the workflow of the 


package. 


To configure this Script Task example 


Vs 


2. 


ds 


Add a new Script task to the package and change its name to ExcelTableExists. 


In the Script Task Editor, on the Script tab, click ReadOnlyVariables and enter the property value 
using one of the following methods: 


e Type ExcelTable and ExcelFile separated by commas. 
-Or- 


e Click the ellipsis (...) button next to the property field, and in the Select variables dialog box, 
select the ExcelTable and ExcelFile variables. 


. Click ReadWriteVariables and enter the property value using one of the following methods: 


e Type ExcelTableExists. 
-Or- 


@ Click the ellipsis (...) button next to the property field, and in the Select variables dialog box, 
select the ExcelTableExists variable. 


. Click Edit Script to open the script editor. 
. Add a reference to the System.Xml assembly in the script project. 


. Add Imports statements for the System.IO and System.Data.OleDb namespaces at the top of the 


script file. 


Add the following code. 


Example 2 Code 


Public Class ScriptMain 
Public Sub Main() 
Dim fileToTest As String 
Dim tableToTest As String 
Dim connectionString As String 
Dim excelConnection As OleDbConnection 
Dim excelTables As DataTable 
Dim excelTable As DataRow 
Dim currentTable As String 


fileToTest = Dts.Variables("ExcelFile").Value.ToString 
tableToTest = Dts.Variables("ExcelTable").Value.ToString 


Dts.Variables("ExcelTableExists").Value = False 
If File.Exists(fileToTest) Then 
connectionString = "Provider=Microsoft.ACE.OLEDB.12.0;" & _ 
"Data Source=" & fileToTest & _ 
";Extended Properties=Excel 12.0" 
excelConnection = New OleDbConnection(connectionString) 
excelConnection.Open() 
excelTables = excelConnection.GetSchema( "Tables" ) 
For Each excelTable In excelTables.Rows 
currentTable = excelTable.Item("TABLE_NAME").ToString 
If currentTable = tableToTest Then 
Dts.Variables("ExcelTableExists").Value = True 
End If 
Next 
End If 


Dts.TaskResult = ScriptResults.Success 
End Sub 
End Class 


public class ScriptMain 


if 
public void Main() 
{ 
string fileToTest; 
string tableToTest; 
string connectionString; 
OleDbConnection excelConnection; 
DataTable excelTables; 
string currentTable; 
fileToTest = Dts.Variables["ExcelFile"].Value.ToString(); 
tableToTest = Dts.Variables["ExcelTable"].Value.ToString(); 
Dts.Variables["ExcelTableExists"].Value = false; 
if (File.Exists(fileToTest) ) 
{ 
connectionString = "Provider=Microsoft.ACE.OLEDB.12.0;" + 
"Data Source=" + fileToTest + ";Extended Properties=Excel 12.0"; 
excelConnection = new OleDbConnection(connectionString) ; 
excelConnection.Open() ; 
excelTables = excelConnection.GetSchema("Tables") ; 
foreach (DataRow excelTable in excelTables.Rows) 
{ 
currentTable = excelTable["TABLE_NAME"].ToString() ; 
if (currentTable == tableToTest) 
{ 
Dts.Variables["ExcelTableExists"].Value = true; 
} 
oi 
} 
Dts.TaskResult = (int)ScriptResults.Success; 
} 
i 


Example 3 Description: Get a List of Excel Files in a Folder 


This example fills an array with the list of Excel files found in the folder specified in the value of the ExcelFolder 
variable, and then copies the array into the ExcelFiles variable. You can use the Foreach from Variable 


enumerator to iterate over the files in the array. 


To configure this Script Task example 


1. Add a new Script task to the package and change its name to GetExcelFiles. 


2. Open the Script Task Editor, on the Script tab, click ReadOnlyVariables and enter the property value 
using one of the following methods: 


e Type ExcelFolder 
-Or- 


e Click the ellipsis (...) button next to the property field, and in the Select variables dialog box, 
select the ExcelFolder variable. 


3. Click ReadWriteVariables and enter the property value using one of the following methods: 
e Type ExcelFiles. 
-Or- 


e Click the ellipsis (...) button next to the property field, and in the Select variables dialog box, 


select the ExcelFiles variable. 
4. Click Edit Script to open the script editor. 
5. Add an Imports statement for the System.IO namespace at the top of the script file. 
6. Add the following code. 


Example 3 Code 


Public Class ScriptMain 
Public Sub Main() 
Const FILE_PATTERN As String = "*.xlsx" 


Dim excelFolder As String 
Dim excelFiles As String() 


excelFolder = Dts.Variables("ExcelFolder") .Value.ToString 
excelFiles = Directory.GetFiles(excelFolder, FILE_PATTERN) 


Dts.Variables("ExcelFiles").Value = excelFiles 
Dts.TaskResult = ScriptResults.Success 


End Sub 
End Class 


public class ScriptMain 


{ 
public void Main() 
{ 
const string FILE_PATTERN = "*.xlsx"; 
string excelFolder; 
string[] excelFiles; 
excelFolder = Dts.Variables["ExcelFolder"].Value.ToString(); 
excelFiles = Directory.GetFiles(excelFolder, FILE_PATTERN); 
Dts.Variables["ExcelFiles"].Value = excelFiles; 
Dts.TaskResult = (int)ScriptResults.Success; 
t 
t 


Alternate Solution 


Instead of using a Script task to gather a list of Excel files into an array, you can also use the ForEach File 
enumerator to iterate over all the Excel files in a folder. For more information, see Loop through Excel Files and 
Tables by Using a Foreach Loop Container. 


Example 4 Description: Get a List of Tables in an Excel File 


This example fills an array with the list of worksheets and named ranges found in the Excel workbook file 
specified by the value of the eExcelFile variable, and then copies the array into the ExcelTables variable. You 


can use the Foreach from Variable Enumerator to iterate over the tables in the array. 


NOTE 


The list of tables in an Excel workbook includes both worksheets (which have the $ suffix) and named ranges. If you have 


to filter the list for only worksheets or only named ranges, you may have to add additional code for this purpose. 





To configure this Script Task example 


1. Add a new Script task to the package and change its name to GetExcelTables. 


2. Open the Script Task Editor, on the Script tab, click ReadOnlyVariables and enter the property value 
using one of the following methods: 


e Type ExcelFile. 
-Or- 


e Click the ellipsis (...) button next to the property field, and in the Select variables dialog box, 
select the ExcelFile variable. 


3. Click ReadWriteVariables and enter the property value using one of the following methods: 
e Type ExcelTables. 
-Or- 


e Click the ellipsis (...) button next to the property field, and in the Select variables dialog box, 
select the ExcelTablesvariable. 


4. Click Edit Script to open the script editor. 

5. Add a reference to the System.Xml namespace in the script project. 

6. Add an|Imports statement for the System.Data.OleDb namespace at the top of the script file. 
7. Add the following code. 


Example 4 Code 


Public Class ScriptMain 
Public Sub Main() 
Dim excelFile As String 
Dim connectionString As String 
Dim excelConnection As OleDbConnection 
Dim tablesInFile As DataTable 
Dim tableCount As Integer = @ 
Dim tableInFile As DataRow 
Dim currentTable As String 
Dim tableIndex As Integer = 0 


Dim excelTables As String() 


excelFile = Dts.Variables("ExcelFile").Value.ToString 
connectionString = "Provider=Microsoft.ACE.OLEDB.12.0;" & _ 
"Data Source=" & excelFile & _ 
";Extended Properties=Excel 12.0" 
excelConnection = New OleDbConnection(connectionString) 
excelConnection.Open() 
tablesInFile = excelConnection.GetSchema("Tables") 
tableCount = tablesInFile.Rows.Count 
ReDim excelTables(tableCount - 1) 
For Each tableInFile In tablesInFile.Rows 
currentTable = tableInFile.Item("TABLE_NAME").ToString 
excelTables(tableIndex) = currentTable 
tableIndex += 1 
Next 


Dts.Variables("ExcelTables").Value = excelTables 
Dts.TaskResult = ScriptResults.Success 


End Sub 
End Class 


public class ScriptMain 


{ 
public void Main() 
{ 

string excelFile; 

string connectionString; 

OleDbConnection excelConnection; 

DataTable tablesInFile; 

int tableCount = @; 

string currentTable; 

int tableIndex = @; 

string[] excelTables = new string[5]; 

excelFile = Dts.Variables["ExcelFile"].Value.ToString(); 

connectionString = "Provider=Microsoft.ACE.OLEDB.12.0;" + 
"Data Source=" + excelFile + ";Extended Properties=Excel 12.0"; 

excelConnection = new OleDbConnection(connectionString) ; 

excelConnection.Open() ; 

tablesInFile = excelConnection.GetSchema("Tables") ; 

tableCount = tablesInFile.Rows.Count; 

foreach (DataRow tableInFile in tablesInFile.Rows) 

{ 
currentTable = tableInFile["TABLE_NAME"].ToString(); 
excelTables[tableIndex] = currentTable; 
tableIndex += 1; 

} 

Dts.Variables["ExcelTables"].Value = excelTables; 

Dts.TaskResult = (int)ScriptResults.Success; 

} 
} 


Alternate Solution 


Instead of using a Script task to gather a list of Excel tables into an array, you can also use the ForEach ADO.NET 
Schema Rowset Enumerator to iterate over all the tables (that is, worksheets and named ranges) in an Excel 
workbook file. For more information, see Loop through Excel Files and Tables by Using a Foreach Loop 


Container. 


Displaying the Results of the Samples 


If you have configured each of the examples in this topic in the same package, you can connect all the Script 
tasks to an additional Script task that displays the output of all the examples. 


To configure a Script task to display the output of the examples in this topic 


1. Add a new Script task to the package and change its name to DisplayResults. 


2. Connect each of the four example Script tasks to one another, so that each task runs after the preceding 
task completes successfully, and connect the fourth example task to the DisplayResults task. 


3. Open the DisplayResults task in the Script Task Editor. 


4. On the Script tab, click ReadOnlyVariables and use one of the following methods to add all seven 
variables listed in Configuring a Package to Test the Samples: 


e Type the name of each variable separated by commas. 
-Or- 


e Click the ellipsis (...) button next to the property field, and in the Select variables dialog box, 


selecting the variables. 
5. Click Edit Script to open the script editor. 


6. Add Imports statements for the Microsoft.VisualBasic and System.Windows.Forms namespaces at 


the top of the script file. 
7. Add the following code. 
8. Run the package and examine the results displayed in a message box. 


Code to Display the Results 


Public Class ScriptMain 
Public Sub Main() 
Const EOL As String = ControlChars.CrLlf 


Dim results As String 

Dim filesInFolder As String() 
Dim fileInFolder As String 
Dim tablesInFile As String() 
Dim tableInFile As String 


results = _ 
"Final values of variables:" & EOL & _ 
"ExcelFile: " & Dts.Variables("ExcelFile").Value.ToString & EOL & _ 
"ExcelFileExists: " & Dts.Variables("ExcelFileExists").Value.ToString & EOL & _ 
"ExcelTable: " & Dts.Variables("ExcelTable").Value.ToString & EOL & _ 
"ExcelTableExists: " & Dts.Variables("ExcelTableExists").Value.ToString & EOL & _ 
"ExcelFolder: " & Dts.Variables("ExcelFolder").Value.ToString & EOL & _ 
EOL 


results &= "Excel files in folder: " & EOL 
filesInFolder = DirectCast(Dts.Variables("ExcelFiles").Value, String()) 
For Each fileInFolder In filesInFolder 
results & " " & fileInFolder & EOL 
Next 
results &= EOL 


results &= "Excel tables in file: " & EOL 
tablesInFile = DirectCast(Dts.Variables("ExcelTables").Value, String()) 
For Each tableInFile In tablesInFile 
results & " " & tableInFile & EOL 
Next 


MessageBox.Show(results, "Results", MessageBoxButtons.OK, MessageBoxIcon. Information) 
Dts.TaskResult = ScriptResults.Success 


End Sub 
End Class 


public class ScriptMain 
{ 
public void Main() 


{ 
const string EOL = "\r"; 


string results; 
string[] filesInFolder; 
//string fileInFolder; 
string[] tablesInFile; 
//string tableInFile; 


results = "Final values of variables:" + EOL + "ExcelFile: " + 
Dts.Variables["ExcelFile"].Value.ToString() + EOL + "ExcelFileExists: " + 
Dts.Variables["ExcelFileExists"].Value.ToString() + EOL + "ExcelTable: " + 
Dts.Variables["ExcelTable"].Value.ToString() + EOL + "ExcelTableExists: " + 
Dts.Variables["ExcelTableExists"].Value.ToString() + EOL + "ExcelFolder: " + 
Dts.Variables["ExcelFolder"].Value.ToString() + EOL + EOL; 


results += "Excel files in folder: " + EOL; 
filesInFolder = (string[])(Dts.Variables["ExcelFiles"].Value) ; 
foreach (string fileInFolder in filesInFolder) 


if 


results += " " + fileInFolder + EOL; 


} 


results += EOL; 
results += "Excel tables in file: " + EOL; 


tablesInFile = (string[])(Dts.Variables["ExcelTables"].Value) ; 
foreach (string tableInFile in tablesInFile) 


Hi 


results += " " + tableInFile + EOL; 


MessageBox.Show(results, "Results", MessageBoxButtons.OK, MessageBoxIcon. Information) ; 


Dts.TaskResult = (int)ScriptResults.Success; 


See Also 


Load data from or to Excel with SQL Server Integration Services (SSIS) 
Loop through Excel Files and Tables by Using a Foreach Loop Container 


Working with Images with the Script Task 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


A database of products or users frequently includes images in addition to text and numeric data. The 
System.Drawing namespace in the Microsoft .NET Framework provides classes for manipulating images. 


Example 1: Convert Images to JPEG Format 


Example 2: Create and Save Thumbnail Images 





NOTE 


If you want to create a task that you can more easily reuse across multiple packages, consider using the code in this Script 
task sample as the starting point for a custom task. For more information, see Developing a Custom Task. 





Example 1 Description: Convert Images to JPEG Format 


The following example opens an image file specified by a variable and saves it as a compressed JPEG file by 
using an encoder. The code to retrieve encoder information is encapsulated in a private function. 


To configure this Script Task example for use with a single image file 


1. Create a string variable named currentImageFile and set its value to the path and file name of an existing 
image file. 


2. On the Script page of the Script Task Editor, add the currentImageFile variable to the 
ReadOnlyVariables property. 


3. In the script project, set a reference to the System.Drawing namespace. 


4. In your code, use Imports statements to import the System.Drawing and System.IO namespaces. 


To configure this Script Task example for use with multiple image files 


1. Place the Script task within a Foreach Loop container. 


2. On the Collection page of the Foreach Loop Editor, select the Foreach File Enumerator as the 
enumerator, and specify the path and file mask of the source files, such as "*.bmp." 


3. On the Variable Mappings page, map the currentImageFile variable to Index 0. This variable passes the 
current file name to the Script task on each iteration of the enumerator. 








NOTE 


These steps are in addition to the steps listed in the procedure for use with a single image file. 








Example 1 Code 


Public Sub Main() 


"Create and initialize variables. 
Dim currentFile As String 

Dim newFile As String 

Dim bmp As Bitmap 


Dim eps As New Imaging.EncoderParameters(1) 

Dim ici As Imaging. ImageCodecInfo 

Dim supportedExtensions() As String = _ 
{ee BMD iets GLE sad PGay a) PEGE) mreEX Lees le PNGoe. 
DeRURR es mele S: wtGOl.. CONE} 


Try 
"Store the variable in a string for local manipulation. 
currentFile = Dts.Variables("CurrentImageFile").Value.ToString 
"Check the extension of the file against a list of 
"files that the Bitmap class supports. 
If Array.IndexOf(supportedExtensions, _ 
Path.GetExtension(currentFile).ToUpper) > -1 Then 


"Load the file. 
bmp = New Bitmap(currentFile) 


"Calculate the new name for the compressed image. 

"Note: This will overwrite existing JPEGs. 

newFile = Path.Combine( _ 
Path.GetDirectoryName(currentFile), _ 
String.Concat(Path.GetFileNameWithoutExtension(currentFile), _ 


".jpg")) 


"Specify the compression ratio (@=worst quality, 10@=best quality). 
eps.Param(®) = New Imaging.EncoderParameter( _ 
Imaging.Encoder.Quality, 75) 


"Retrieve the ImageCodecInfo associated with the jpeg format. 
ici = GetEncoderInfo( "image/jpeg" ) 


"Save the file, compressing it into the jpeg encoding. 
bmp.Save(newFile, ici, eps) 

Else 
"The file is not supported by the Bitmap class. 
Dts.Events.FireWarning(®, "Image Resampling Sample", _ 

"File " & currentFile & " is not a supported format.", _ 
EO) 
End If 
Dts.TaskResult = ScriptResults.Success 
Catch ex As Exception 

"An error occurred. 

Dts.Events.FireError(@, "Image Resampling Sample", _ 
ex.Message & ControlChars.CrLf & ex.StackTrace, _ 
String.Empty, 0) 

Dts.TaskResult = ScriptResults.Failure 

End Try 


End Sub 


Private Function GetEncoderInfo(ByVal mimeType As String) As Imaging. ImageCodecInfo 


"The available image codecs are returned as an array, 
"which requires code to iterate until the specified codec is found. 


Dim count As Integer 
Dim encoders() As Imaging. ImageCodecInfo 


encoders = Imaging. ImageCodecInfo.GetImageEncoders() 


For count = @ To encoders.Length 
If encoders(count).MimeType = mimeType Then 
Return encoders(count) 
End If 
Next 


"This point is only reached if a codec is not found. 
Err.Raise(513, "Image Resampling Sample", String.Format( _ 
"The {@} codec is not available. Unable to compress file.", _ 


mimeType) ) 
Return Nothing 


End Function 


Example 2 Description: Create and Save Thumbnail Images 


The following example opens an image file specified by a variable, creates a thumbnail of the image while 


maintaining a constant aspect ratio, and saves the thumbnail with a modified file name. The code that calculates 


the height and width of the thumbnail while maintaining a constant aspect ratio is encapsulated in a private 


subroutine. 


To configure this Script Task example for use with a single image file 


il 


4. 


5: 


Create a string variable named currentImageFile and set its value to the path and file name of an existing 


image file. 


. Also create the MaxThumbSize integer variable and assign a value in pixels, such as 100. 


. On the Script page of the Script Task Editor, add both variables to the ReadOnlyVariables property. 


In the script project, set a reference to the System.Drawing namespace. 


In your code, use Imports statements to import the System.Drawing and System.IO namespaces. 


To configure this Script Task example for use with multiple image files 


We 


Place the Script task within a Foreach Loop container. 


On the Collection page of the Foreach Loop Editor, select the Foreach File Enumerator as the 
Enumerator, and specify the path and file mask of the source files, such as "*,jpg." 


On the Variable Mappings page, map the CurrentImageFile variable to Index 0. This variable passes the 


current file name to the Script task on each iteration of the enumerator. 





NOTE 


These steps are in addition to the steps listed in the procedure for use with a single image file. 





Example 2 Code 


Public Sub Main() 


Dim currentImageFile As String 
Dim currentImage As Image 

Dim maxThumbSize As Integer 
Dim thumbnailImage As Image 
Dim thumbnailFile As String 
Dim thumbnailHeight As Integer 
Dim thumbnailWidth As Integer 


currentImageFile = Dts.Variables("CurrentImageFile") .Value.ToString 

thumbnailFile = Path.Combine( _ 
Path.GetDirectoryName(currentImageFile), _ 
String.Concat(Path.GetFileNameWithoutExtension(currentImageFile), _ 


_thumbnail. jpg") ) 


Try 


" 


currentImage = Image.FromFile(currentImageFile) 
maxThumbSize = CType(Dts.Variables("MaxThumbSize").Value, Integer) 
CalculateThumbnailSize( _ 

maxThumbSize, currentImage, thumbnailWidth, thumbnailHeight) 


thumbnailImage = currentImage.GetThumbnailImage( _ 
thumbnailWidth, thumbnailHeight, Nothing, Nothing) 

thumbnaillImage.Save(thumbnailFile) 
Dts.TaskResult = ScriptResults.Success 

Catch ex As Exception 
Dts.Events.FireError(®@, "Script Task Example", _ 
ex.Message & ControlChars.CrLf & ex.StackTrace, _ 
String.Empty, 0) 
Dts.TaskResult = ScriptResults.Failure 

End Try 


End Sub 


Private Sub CalculateThumbnailSize( _ 
ByVal maxSize As Integer, ByVal sourceImage As Image, _ 
ByRef thumbWidth As Integer, ByRef thumbHeight As Integer) 


If sourceImage.Width > sourceImage.Height Then 

thumbWidth = maxSize 

thumbHeight = CInt((maxSize / sourceImage.Width) * sourceImage.Height) 
Else 

thumbHeight = maxSize 

thumbWidth = CInt((maxSize / sourceImage.Height) * sourceImage.Width) 
End If 


End Sub 


bool ThumbnailCallback() 


{ 

return false; 
} 
public void Main() 
{ 


string currentImageFile; 
Image currentImage; 

int maxThumbSize; 

Image thumbnaillImage; 
string thumbnailFile; 
int thumbnailHeight = @; 
int thumbnailWidth = @; 


currentImageFile = Dts.Variables["CurrentImageFile"].Value.ToString(); 
thumbnailFile = Path.Combine(Path.GetDirectoryName(currentImageFile), 
String.Concat(Path.GetFileNameWithoutExtension(currentImageFile), "_thumbnail.jpg")); 


try 
{ 


currentImage = Image.FromFile(currentImageFile) ; 


maxThumbSize = (int)Dts.Variables["MaxThumbSize"].Value; 
CalculateThumbnailSize(maxThumbSize, currentImage, ref thumbnailWidth, ref thumbnailHeight) ; 


Image.GetThumbnailImageAbort myCallback = new 
Image .GetThumbnailImageAbort (ThumbnailCallback) ; 


thumbnailImage = currentImage.GetThumbnailImage(thumbnailWidth, thumbnailHeight, 
ThumbnailCallback, IntPtr.Zero) ; 
thumbnailImage.Save(thumbnailFile) ; 
Dts.TaskResult = (int)ScriptResults.Success; 
} 
catch (Exception ex) 
{ 
Dts.Events.FireError(®, "Script Task Example", ex.Message + "\r" + ex.StackTrace, 
String.Empty, @); 
Dts.TaskResult = (int)ScriptResults.Failure; 


private void CalculateThumbnailSize(int maxSize, Image sourceImage, ref int thumbWidth, ref int 
thumbHeight ) 


{ 
if (sourceImage.Width > sourceImage.Height) 
{ 
thumbWidth = maxSize; 
thumbHeight = (int)(sourceImage.Height * maxSize / sourceImage.Width) ; 
} 
else 
{ 
thumbHeight = maxSize; 
thumbWidth = (int)(sourceImage.Width * maxSize / sourceImage.Height) ; 
t 
t 


ll ee | 
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The Script component extends the data flow capabilities of Microsoft Integration Services packages with custom 
code written in Microsoft Visual Basic or Microsoft Visual C# that is compiled and executed at package run time. 
The Script component simplifies the development of a custom data flow source, transformation, or destination 
when the sources, transformations, and destinations included with Integration Services do not fully satisfy your 
requirements. After you configure the component with the expected inputs and outputs, it writes all the required 
infrastructure code for you, letting you focus exclusively on the code that is required for your custom 
processing. 


A Script component interacts with the containing package and with the data flow through the autogenerated 
classes in the ComponentWrapper and BufferWrapper project items, which are instances of the 
ScriptComponent and the ScriptBuffer classes respectively. These classes make connections, variables, and other 
package items available as typed objects, and manage inputs and outputs. The Script component can also use 
the Visual Basic namespace and the .NET Framework class library, as well as custom assemblies, to implement 
custom functionality. 


The Script component and the infrastructure code that it generates for you simplify significantly the process of 
developing a custom data flow component. However, to understand how the Script component works, you may 
find it useful to read the section Developing a Custom Data Flow Component to understand the steps that are 
involved in developing a custom data flow component. 


If you are creating a source, transformation, or destination that you plan to reuse in multiple packages, you 
should consider developing a custom component instead of using the Script component. For more information, 
see Developing a Custom Data Flow Component. 


In This Section 
The following topics provide more information about the Script component. 


Configuring the Script Component in the Script Component Editor 
Properties that you configure in the Script Transformation Editor affect the capabilities and the performance 
of Script component code. 


Coding and Debugging the Script Component 
You use the Microsoft Visual Studio Tools for Applications (VSTA) development environment to develop the 
scripts contained in the Script component. 


Understanding the Script Component Object Model 
A new Script component project contains three project items with several classes and autogenerated properties 
and methods. 


Using Variables in the Script Component 
The ComponentWrapper project item contains strongly-typed accessor properties for package variables. 


Connecting to Data Sources in the Script Component 
The ComponentWrapper project item also contains strongly-typed accessor properties for connections 
defined in the package. 


Raising Events in the Script Component 


You can raise events to provide notification of problems and errors. 


Logging in the Script Component 
You can log information to log providers enabled on the package. 


Developing Specific Types of Script Components 
These simple examples explain and demonstrate how to use the Script component to develop data flow sources, 
transformations, and destinations. 


Additional Script Component Examples 
These simple examples explain and demonstrate a few possible uses for the Script component. 


See Also 


Script Component 
Comparing the Script Task and the Script Component 


Configuring the Script Component in the Script 
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Before you write custom code in the Script component, you must select the type of data flow component that 
you want to create-source, transformation, or destination-and then configure the component's metadata and 
properties in the Script Transformation Editor. 


Selecting the Type of Component to Create 


When you add a Script component to the Data Flow pane of SSIS Designer, the Select Script Component 
Type dialog box appears. You preconfigure the component as a source, transformation, or destination. After you 
make this initial selection, you can continue to configure the component in the Script Transformation Editor. 


To set the default script language for the Script component, use the Scripting language option on the General 
page of the Options dialog box. For more information, see General Page. 


Understanding the Two Design-Time Modes 
In SSIS Designer, the Script component has two modes: metadata design mode and code design mode. 


When you open the Script Transformation Editor, the component enters metadata design mode. In this 
mode, you can select input columns, and add or configure outputs and output columns, but you cannot write 
code. After you have configured the component's metadata, you can switch to code design mode to write the 
script. 


When you switch to code design mode by clicking Edit Script, the Script component locks metadata to prevent 
additional changes, and then automatically generates base code from the metadata of the inputs and outputs. 
After the autogenerated code is complete, you will be able to enter your custom code. Your code uses the auto- 
generated base classes to process input rows, to access buffers and columns in the buffers, and to retrieve 
connection managers and variables from the package, all as strongly-typed objects. 


After entering your custom code in code design mode, you can switch back to metadata design mode. This does 
not delete any code that you have entered; however, subsequent changes to the metadata cause the base class 
to be regenerated. Afterward, your component may fail validation because objects referenced by your custom 
code may no longer exist or may have been modified. In this case, you must fix your code manually so that it can 
be compiled successfully against the regenerated base class. 


Configuring the Component in Metadata Design Mode 


In metadata design mode, you can select input columns, and add and configure outputs and output columns, 
but you cannot write code. After you have configured the component's metadata, switch to code design mode to 
write the script. 


The properties that you must configure in the custom editor depend on the usage of the Script component. The 
Script component can be configured as a source, a transformation, or a destination. Depending on how the 
component is used, it supports either an input or outputs or both. The custom code that you will write processes 
the input and output rows and columns. 


Inputs Columns Page of the Script Transformation Editor 


The Input Columns page of the Script Transformation Editor is displayed for transformations and 
destinations, but not for sources. On this page, you select the available input columns that you want to make 


available to your custom script, and specify read-only or read/write access to them. 


In the code project that will be generated based on this metadata, the BufferWrapper project item contains a 
class for each input, and this class contains typed accessor properties for each input column selected. For 
example, if you select an integer CustomerID column and a string CustomerName column from an input 
named CustomerI!nput, the BufferWrapper project item will contain a CustomerInput class that derives from 
ScriptBuffer, and the CustomerInput class will expose an integer property named CustomerID and a string 
property named CustomerName. This convention makes it possible to write code with type-checking like the 
following: 


Dim currentCustomerID as Integer = CustomerInput.CustomerID 
Dim currentCustomerName as String = CustomerInput.CustomerName 


For more information about how to configure input columns for a specific type of data flow component, see the 
appropriate example under Developing Specific Types of Script Components. 


Inputs and Outputs Page of the Script Transformation Editor 


The Input and Outputs page of the Script Transformation Editor is displayed for sources, transformations, 
and destinations. On this page, you add, remove, and configure inputs, outputs, and output columns that you 
want to use in your custom script, within the following limitations: 


e When used as a source, the Script component has no input and supports multiple outputs. 
e When used as a transformation, the Script component supports one input and multiple outputs. 
e@ When used as a destination, the Script component supports one input and has no outputs. 


In the code project that will be generated based on this metadata, the BufferWrapper project item contains a 
class for each input and output. For example, if you create an output named CustomerOutput, the 
BufferWrapper project item will contain a CustomerOutput class that derives from ScriptBuffer, and the 
CustomerOutput class will contain typed accessor properties for each output column created. 


You can configure output columns only on the Input and Outputs page. You can select input columns for 
transformations and destinations on the Input Columns page. The typed accessor properties created for you in 
the BufferWrapper project item will be write-only for output columns. The accessor properties for input columns 
will be read-only or read/write depending on the usage type that you have selected for each column on the 
Input Columns page. 


For more information about configuring inputs and outputs for a specific type of data flow component see the 
appropriate example under Developing Specific Types of Script Components. 





NOTE 

Although you cannot directly configure an output as an error output in the Script component for automatic handling of 
error rows, you can reproduce the functionality of an error output by creating an additional output and using script to 
direct rows to this output when appropriate. For more information, see Simulating an Error Output for the Script 


Component. 





ExclusionGroup and SynchronousInputID Properties of Outputs 

The ExclusionGroup property has a non-zero value only in transformations with synchronous outputs, where 
your code performs filtering or branching and directs each row to one of the outputs that share the same non- 
zero ExclusionGroup value. For example, the transformation can direct rows either to the default output or to 





an error output. When you create additional outputs for this scenario, make sure to set the value of the 
Synchronous!InputID property to the integer that matches the ID of the component's input. 


The Synchronous!InputID property has a non-zero value only in transformations with synchronous outputs. If 
the value of this property is zero, it means that the output is asynchronous. For a synchronous output, where 
rows are passed through to the selected output or outputs without adding any new rows, this property should 
contain the ID of the component's input. 





NOTE 
When the Script Transformation Editor creates the first output, the editor sets the SynchronousInputID property 


of the output to the ID of the component's input. However, when the editor creates subsequent outputs, the editor sets 


the SynchronousInputID properties of those outputs to zero. 


If you are creating a component with synchronous outputs, each output must have its SynchronousInputID property 
set to the ID of the component's input. Therefore, each output that the editor creates after the first output must have its 


Synchronous!nputID value changed from zero to the ID of the component's input. 


If you are creating a component with asynchronous outputs, each output must have its SynchronousInputID property 
set to zero. Therefore, the first output must have its SynchronousInputID value changed from the ID of the 


component's input to zero. 











For an example of directing rows to one of two synchronous outputs in the Script component, see Creating a 
Synchronous Transformation with the Script Component. 


Object Names in Generated Script 


The Script component parses the names of inputs and outputs, and parse the names of columns in the inputs 
and outputs, and based on these names generates classes and properties in the BufferWrapper project item. If 
the found names include characters that do not belong to the Unicode categories UppercaseLetter, 
LowercaseLetter, TitlecaseLetter, ModifierLetter, OtherLetter, or DecimalDigitLetter, the invalid 
characters are dropped in the generated names. For example, spaces are dropped, therefore two input columns 
that have the names FirstName and [First Name] are both interpreted as having the column name 
FirstName, with unpredictable results. To avoid this situation, the names of inputs and outputs and of input and 
output columns used by the Script component should contain only characters in the Unicode categories listed in 
this section. 


Script Page of the Script Transformation Editor 


On the Script page of the Script Task Editor, you assign a unique name and a description for the Script task. 
You can also assign values for the following properties. 


NOTE 


In SQL Server 2008 Integration Services (SSIS) and later versions, all scripts are precompiled. In previous versions, you 


specified whether scripts were precompiled by setting a Precompile property for the task. 





ValidateExternalMetadata Property 

The Boolean value of the ValidateExternalMetadata property specifies whether the component should 
perform validation against external data sources at design time, or whether it should postpone validation until 
run time. By default, the value of this property is True; that is, the external metadata is validated both at design 
time and at run time. You may want to set the value of this property to False when an external data source is not 
available at design time: for example, when the package downloads the source or creates the destination only at 
run time. 


ReadOnlyVariables and ReadWriteVariables Properties 


You can enter comma-delimited lists of existing variables as the values of these properties to make the variables 


available for read-only or read/write access within the Script component code. Variables are accessed in code 
through the ReadOnlyVariables and ReadWriteVariables properties of the autogenerated base class. For more 


information, see Using Variables in the Script Component. 





NOTE 


Variable names are case-sensitive. 





ScriptLanguage 
You can select either Microsoft Visual Basic or Microsoft Visual C# as the programming language for the Script 


component. 


Edit Script Button 
The Edit Script button opens the Microsoft Visual Studio Tools for Applications (VSTA) IDE in which you write 
your custom script. For more information, see Coding and Debugging the Script Component. 


Connection Managers Page of the Script Transformation Editor 
On the Connection Managers page of the Script Transformation Editor, you add and remove connection 
managers that you want to use in your custom script. Normally you need to reference connection managers 


when you create a source or destination component. 


In the code project that will be generated based on this metadata, the ComponentWrapper project item 
contains a Connections collection class that has a typed accessor property for each selected connection 
manager. Each typed accessor property has the same name as the connection manager itself and returns a 
reference to the connection manager as an instance of IDTSConnectionManager100. For example, if you have 
added a connection manager named myaDoNeTConnection on the Connection Managers page of the editor, 


you can obtain a reference to the connection manager in your script by using the following code: 


Dim myADONETConnectionManager As IDTSConnectionManager100 = _ 
Me. Connections .MyADONETConnection 


For more information, see Connecting to Data Sources in the Script Component. 


See Also 


Coding and Debugging the Script Component 


Coding and Debugging the Script Component 
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In SSIS Designer, the Script component has two modes: metadata design mode and code design mode. When 
you open the Script Transformation Editor, the component enters metadata design mode, in which you 
configure metadata and set component properties. After you have set the properties of the Script component 
and configured the input and outputs in metadata design mode, you can switch to code design mode to write 
your custom script. For more information about metadata design mode and code design mode, see Configuring 
the Script Component in the Script Component Editor. 


Writing the Script in Code Design Mode 


Script Component Development Environment 


To write your script, click Edit Script on the Script page of the Script Transformation Editor to open the 
Microsoft Visual Studio Tools for Applications (VSTA) IDE. The VSTA IDE includes all the standard features of the 
Visual Studio NET environment, such as the color-coded Visual Studio editor, Intellisense, and Object Browser. 


Script code is written in Microsoft Visual Basic or Microsoft Visual C#. You specify the script language by setting 
the ScriptLanguage property in the Script Transformation Editor. If you prefer to use another 
programming language, you can develop a custom assembly in your language of choice and call its functionality 
from the code in the Script component. 


The script that you create in the Script component is stored in the package definition. There is no separate script 
file. Therefore, the use of the Script component does not affect package deployment. 





NOTE 


While you design the package, the script code is temporarily written to a project file. Because storing sensitive information 
in a file is a potential security risk, we recommended that you do not include sensitive information such as passwords in 
the script code. 





By default, Option Strict is disabled in the IDE. 


Script Component Project Structure 

The power of the Script component is that it can generate infrastructure code that reduces the amount of code 
that you must write. This feature relies on the fact that inputs and outputs and their columns and properties are 
fixed and known in advance. Therefore, any subsequent changes that you make to the component's metadata 
may invalidate the code that you have written. This causes compilation errors during execution of the package. 


Project Items and Classes in the Script Component Project 

When you switch to code design mode, the VSTA IDE opens and displays the ScriptMain project item. The 
ScriptMain project item contains the editable ScriptMain class, which serves as the entry point for the script 
and which is where you write your code. The code elements in the class vary depending on the programming 
language that you selected for the Script task. 


The script project contains two additional auto-generated read-only project items: 
e The ComponentWrapper project item contains three classes: 


o The UserComponent class, which inherits from ScriptComponent and contains the methods and 





properties that you will use to process data and to interact with the package. The ScriptMain class 
inherits from the UserComponent class. 


o AConnections collection class that contains references to the connections selected on the 
Connection Manager page of the Script Transformation Editor. 


o AVariables collection class that contains references to the variables entered in the 
ReadOnlyVariable and ReadWriteVariables properties on the Script page of the Script 
Transformation Editor. 


e The BufferWrapper project item contains a class that inherits from ScriptBuffer for each input and 
output configured on the Inputs and Outputs page of the Script Transformation Editor. Each of 
these classes contains typed accessor properties that correspond to the configured input and output 
columns, and the data flow buffers that contain the columns. 


For information about how to use these objects, methods, and properties, see Understanding the Script 
Component Object Model. For information about how to use the methods and properties of these classes ina 
particular type of Script component, see the section Additional Script Component Examples. The example topics 


also contain complete code samples. 


When you configure the Script component as a transformation, the ScriptMain project item contains the 
following autogenerated code. The code template also provides an overview of the Script component, and 
additional information on how to retrieve and manipulate SSIS objects, such as variables, events, and 


connections. 


Microsoft SQL Server Integration Services Script Component 
Write scripts using Microsoft Visual Basic 2008. 
ScriptMain is the entry point class of the script. 


Imports System 

Imports System.Data 

Imports System.Math 

Imports Microsoft.SqlServer.Dts.Pipeline.Wrapper 
Imports Microsoft.SqlServer.Dts.Runtime.Wrapper 


<Microsoft.SqlServer.Dts.Pipeline.SSISScriptComponentEntryPointAttribute> _ 

<CLSCompliant(False)> _ 

Public Class ScriptMain 
Inherits UserComponent 


Public Overrides Sub PreExecute() 
MyBase. PreExecute() 


Add your code here for preprocessing or remove if not needed 


End Sub 


Public Overrides Sub PostExecute() 
MyBase. PostExecute() 


Add your code here for postprocessing or remove if not needed 
You can set read/write variables here, for example: 
" Me.Variables.MyIntVar = 100 


End Sub 


Public Overrides Sub Input@_ProcessInputRow(ByVal Row As Input@Buffer) 


" Add your code here 


End Sub 


End Class 


/* Microsoft SQL Server Integration Services user script component 
* Write scripts using Microsoft Visual C# 2008. 
* ScriptMain is the entry point class of the script.*/ 


using System; 

using System.Data; 

using Microsoft.SqlServer.Dts.Pipeline.Wrapper; 
using Microsoft.SqlServer.Dts.Runtime.Wrapper; 


[Microsoft.SqlServer.Dts.Pipeline.SSISScriptComponentEntryPointAttribute ] 
public class ScriptMain : UserComponent 


{ 
public override void PreExecute() 
{ 
base.PreExecute(); 
if} 
Add your code here for preprocessing or remove if not needed 
suf 
t 
public override void PostExecute() 
{ 
base.PostExecute(); 
fx 
Add your code here for postprocessing or remove if not needed 
You can set read/write variables here, for example: 
Variables.MyIntVar = 100 
yf 
t 
public override void Input@_ProcessInputRow(Input@Buffer Row) 
{ 
if} 
Add your code here 
ay 
t 
t 


Additional Project Items in the Script Component Project 
The Script component project can include items other than the default ScriptMain item. You can add classes, 
modules, code files, and folders to the project, and you can use folders to organize groups of items. 


All the items that you add are persisted inside the package. 


References in the Script Component Project 
You can add references to managed assemblies by right-clicking the Script task project in Project Explorer, and 
then clicking Add Reference. For more information, see Referencing Other Assemblies in Scripting Solutions. 


NOTE 


You can view project references in the VSTA IDE in Class View or in Project Explorer. You open either of these windows 


from the View menu. You can add a new reference from the Project menu, from Project Explorer, or from Class View. 











Interacting with the Package in the Script Component 


The custom script that you write in the Script component can access and use variables and connection managers 
from the containing package through strongly-typed accessors in the auto-generated base classes. However, 
you must configure both variables and connection managers before entering code-design mode if you want to 


make them available to your script. You can also raise events and perform logging from your Script component 


code. 


The autogenerated project items in the Script component project provide the following objects, methods, and 
properties for interacting with the package. 


PACKAGE FEATURE ACCESS METHOD 


Variables Use the named and typed accessor properties in the 
Variables collection class in the ComponentWrapper 
project item, exposed through the Variables property of 
the ScriptMain class. 


The PreExecute method can access only read-only 
variables. The PostExecute method can access both read- 
only and read/write variables. 


Connections Use the named and typed accessor properties in the 
Connections collection class in the ComponentWrapper 
project item, exposed through the Connections property 
of the ScriptMain class. 


Events Raise events by using the ComponentMetaData property of 
the ScriptMain class and the Fire<X> methods of the 
IDTSComponentMetaData100 interface. 


Logging Perform logging by using the Log method of the 
ScriptMain class. 


Debugging the Script Component 


To debug the code in your Script component, set at least one breakpoint in the code, and then close the VSTA IDE 
to run the package in SQL Server Data Tools (SSDT). When package execution enters the Script component, the 
VSTA IDE reopens and displays your code in read-only mode. After execution reaches your breakpoint, you can 
examine variable values and step through the remaining code. 





NOTE 
You cannot debug a Script component when you run the Script component as part of a child package that is run from an 
Execute Package task. Breakpoints that you set in the Script component in the child package are disregarded in these 


circumstances. You can debug the child package normally by running it separately. 


NOTE 
When you debug a package that contains multiple Script components, the debugger debugs one Script component. The 
system can debug another Script component if the debugger completes, as in the case of a Foreach Loop or For Loop 


container. 





You can also monitor the execution of the Script component by using the following methods: 


e Interrupt execution and display a modal message by using the MessageBox.Show method in the 
System.Windows.Forms namespace. (Remove this code after you complete the debugging process.) 


e Raise events for informational messages, warnings, and errors. The Firelnformation, FireWarning, and 
FireError methods display the event description in the Visual Studio Output window. However, the 
FireProgress method, the Console.Write method, and Console.WriteLine method do not display any 
information in the Output window. Messages from the FireProgress event appear on the Progress tab 





of SSIS Designer. For more information, see Raising Events in the Script Component. 


e Log events or user-defined messages to enabled logging providers. For more information, see Logging in 
the Script Component. 


If you just want to examine the output of a Script component configured as a source or as a transformation, 
without saving the data to a destination, you can stop the data flow with a Row Count Transformation and attach 
a data viewer to the output of the Script component. For information about data viewers, see Debugging Data 


Flow. 


In This Section 


For more information about coding the Script component, see the following topics in this section. 


Understanding the Script Component Object Model 
Explains how to use the objects, methods, and properties available in the Script component. 


Referencing Other Assemblies in Scripting Solutions 
Explains how to reference objects from the .NET Framework class library in the Script component. 


Simulating an Error Output for the Script Component 
Explains how to simulate an error output for rows that raise errors during processing by the Script component. 


External Resources 


e Blog entry, VSTA setup and configuration troubles for SSIS 2008 and R2 installations, on blogs.msdn.com. 


See Also 


Configuring the Script Component in the Script Component Editor 
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As discussed in Coding and Debugging the Script Component, the Script component project contains three 
project items: 


1. The ScriptMain item, which contains the ScriptMain class in which you write your code. The 
ScriptMain class inherits from the UserComponent class. 


2. The ComponentWrapper item, which contains the UserComponent class, an instance of 
ScriptComponent that contains the methods and properties that you will use to process data and to 
interact with the package. The ComponentWrapper item also contains Connections and Variables 
collection classes. 


3. The BufferWrapper item, which contains classes that inherits from ScriptBuffer for each input and 
output, and typed properties for each column. 


As you write your code in the ScriptMain item, you will use the objects, methods, and properties discussed in 
this topic. Each component will not use all the methods listed here; however, when used, they are used in the 
sequence shown. 


The ScriptComponent base class does not contain any implementation code for the methods discussed in this 
topic. Therefore it is unnecessary, but harmless, to add a call to the base class implementation to your own 
implementation of the method. 


For information about how to use the methods and properties of these classes in a particular type of Script 
component, see the section Additional Script Component Examples. The example topics also contain complete 
code samples. 


AcquireConnections Method 


Sources and destinations generally must connect to an external data source. Override the AcquireConnections 
method of the ScriptComponent base class to retrieve the connection or the connection information from the 
appropriate connection manager. 


The following example returns a System.Data.SqIClient.SqlConnection from an ADO.NET connection 


Manager. 


Dim connMgr As IDTSConnectionManager10@ 
Dim sqlConn As SqlConnection 


Public Overrides Sub AcquireConnections(ByVal Transaction As Object) 


connMgr = Me.Connections .MyADONETConnection 
sqlconn = CType(connMgr.AcquireConnection(Nothing), SqlConnection) 


End Sub 


The following example returns a complete path and file name from a Flat File Connection Manager, and then 
opens the file by using a System.lO.StreamReader. 


Private textReader As StreamReader 
Public Overrides Sub AcquireConnections(ByVal Transaction As Object) 


Dim connMgr As IDTSConnectionManager10@ = _ 
Me.Connections .MyFlatFileSrcConnectionManager 
Dim exportedAddressFile As String = _ 
CType(connMgr ..AcquireConnection(Nothing), String) 
textReader = New StreamReader(exportedAddressFile) 


End Sub 


PreExecute Method 


Override the PreExecute method of the ScriptComponent base class whenever you have processing that you 
must perform one time only before you start processing rows of data. For example, in a destination, you may 
want to configure the parameterized command that the destination will use to insert each row of data into the 


data source. 


Dim sqlConn As SqlConnection 
Dim sqlCmd As SqlCommand 
Dim sqlParam As SqlParameter 


Public Overrides Sub PreExecute() 


sqlcmd = New SqlCommand("INSERT INTO Person.Address2(AddressID, City) " & _ 
"VALUES(@addressid, @city)", sqlConn) 

sqlParam = New SqlParameter("@addressid", SqlDbType. Int) 

sqlcCmd.Parameters.Add(sqlParam) 

sqlParam = New SqlParameter("@city", SqlDbType.NVarChar, 30) 

sqlcmd.Parameters.Add(sqlParam) 


End Sub 


SqlConnection sqlConn; 
SqlCommand sqlCmd; 
SqlParameter sqlParam; 


public override void PreExecute() 


{ 


sqlcmd = new SqlCommand("INSERT INTO Person.Address2(AddressID, City) " + "VALUES(@addressid, @city)", 
sqlConn) ; 

sqlParam = new SqlParameter("@addressid", SqlDbType. Int) ; 

sqlcmd.Parameters.Add(sqlParam) ; 

sqlParam = new SqlParameter("@city", SqlDbType.NVarChar, 30); 

sqlcmd.Parameters.Add(sqlParam) ; 


Processing Inputs and Outputs 


Processing Inputs 


Script components that are configured as transformations or destinations have one input. 


What the BufferWrapper Project Item Provides 
For each input that you have configured, the BufferWrapper project item contains a class that derives from 
ScriptBuffer and has the same name as the input. Each input buffer class contains the following properties, 


functions, and methods: 


e Named, typed accessor properties for each selected input column. These properties are read-only or 
read/write depending on the Usage Type specified for the column on the Input Columns page of the 
Script Transformation Editor. 


e A<column>_IsNull property for each selected input column. This property is also read-only or 
read/write depending on the Usage Type specified for the column. 


e A DirectRowTo<outputbuffer> method for each configured output. You will use these methods when 
filtering rows to one of several outputs in the same ExclusionGroup. 


e ANextRow function to get the next input row, and an EndOfRowset function to determine whether the 
last buffer of data has been processed. You typically do not need these functions when you use the input 
processing methods implemented in the UserComponent base class. The next section provides more 
information about the UserComponent base class. 


What the ComponentWrapper Project Item Provides 

The ComponentWrapper project item contains a class named UserComponent that derives from 
ScriptComponent. The ScriptMain class in which you write your custom code derives in turn from 
UserComponent. The UserComponent class contains the following methods: 


e An overridden implementation of the ProcessInput method. This is the method that the data flow 
engine calls next at run time after the PreExecute method, and it may be called multiple times. 
ProcessInput hands off processing to the <inputbuffer>_ProcessInput method. Then the 
ProcessInput method checks for the end of the input buffer and, if the end of the buffer has been 
reached, calls the overridable FinishOutputs method and the private MarkOutputsAsFinished 
method. The MarkOutputsAsFinished method then calls SetEndOfRowset on the last output buffer. 


e An overridable implementation of the <inputbuffer>_ProcessInput method. This default 
implementation simply loops through each input row and calls <inputbuffer>_ProcessInputRow. 


e An overridable implementation of the <inputbuffer>_ProcessInputRow method. The default 
implementation is empty. This is the method that you will normally override to write your custom data 
processing code. 


What Your Custom Code Should Do 
You can use the following methods to process input in the ScriptMain class: 


e Override <inputbuffer>_ProcessInputRow to process the data in each input row as it passes through. 


e Override <inputbuffer>_ProcessInput only if you have to do something additional while looping 
through input rows. (For example, you have to test for EndOfRowset to take some other action after all 
rows have been processed.) Call <inputbuffer>_ProcessInputRow to perform the row processing. 


e Override FinishOutputs if you have to do something to the outputs before they are closed. 


The ProcessInput method ensures that these methods are called at the appropriate times. 


Processing Outputs 

Script components configured as sources or transformations have one or more outputs. 

What the BufferWrapper Project Item Provides 

For each output that you have configured, the BufferWrapper project item contains a class that derives from 


ScriptBuffer and has the same name as the output. Each input buffer class contains the following properties and 
methods: 


e Named, typed, write-only accessor properties for each output column. 


e Awrite-only <column>_IsNull property for each selected output column that you can use to set the 
column value to null. 


e An AddRow method to add an empty new row to the output buffer. 


e ASetEndOfRowset method to let the data flow engine know that no more buffers of data are expected. 
There is also an EndOfRowset function to determine whether the current buffer is the last buffer of data. 
You generally do not need these functions when you use the input processing methods implemented in 
the UserComponent base class. 


What the ComponentWrapper Project Item Provides 

The ComponentWrapper project item contains a class named UserComponent that derives from 
ScriptComponent. The ScriptMain class in which you write your custom code derives in turn from 
UserComponent. The UserComponent class contains the following methods: 


e An overridden implementation of the PrimeOutput method. The data flow engine calls this method 
before ProcessInput at run time, and it is only called one time. PrimeOutput hands off processing to 
the CreateNewOutputRows method. Then, if the component is a source (that is, the component has no 
inputs), PrimeOutput calls the overridable FinishOutputs method and the private 
MarkOutputsAsFinished method. The MarkOutputsAsFinished method calls SetEndOfRowset on 
the last output buffer. 


e An overridable implementation of the CreateNewOutputRows method. The default implementation is 
empty. This is the method that you will normally override to write your custom data processing code. 


What Your Custom Code Should Do 
You can use the following methods to process outputs in the ScriptMain class: 


e Override CreateNewOutputRows only when you can add and populate output rows before processing 
input rows. For example, you can use CreateNewOutputRows in a source, but in a transformation with 
asynchronous outputs, you should call AddRow during or after the processing of input data. 


e@ Override FinishOutputs if you have to do something to the outputs before they are closed. 


The PrimeOutput method ensures that these methods are called at the appropriate times. 


PostExecute Method 


Override the PostExecute method of the ScriptComponent base class whenever you have processing that you 
must perform one time only after you have processed the rows of data. For example, in a source, you may want 
to close the System.Data.SqlClient.SqlDataReader that you have used to load data into the data flow. 





IMPORTANT 

The collection of ReadWriteVariables is available only in the PostExecute method. Therefore you cannot directly 
increment the value of a package variable as you process each row of data. Instead, increment the value of a local variable, 
and set the value of the package variable to the value of the local variable in the PostExecute method after all data has 


been processed. 











ReleaseConnections Method 


Sources and destinations typically must connect to an external data source. Override the ReleaseConnections 
method of the ScriptComponent base class to close and release the connection that you have opened previously 


in the AcquireConnections method. 


Dim connMgr As IDTSConnectionManager100 


Public Overrides Sub ReleaseConnections() 


connMgr.ReleaseConnection(sqlConn) 


End Sub 


IDTSConnectionManager1@@ connMgr; 


public override void ReleaseConnections() 


{ 
connMgr.ReleaseConnection(sqlConn) ; 
t 
See Also 


Configuring the Script Component in the Script Component Editor 
Coding and Debugging the Script Component 
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Variables store values that a package and its containers, tasks, and event handlers can use at run time. For more 
information, see Integration Services (SSIS) Variables. 


You can make existing variables available for read-only or read/write access by your custom script by entering 
comma-delimited lists of variables in the ReadOnlyVariables and ReadWriteVariables fields on the Script 
page of the Script Transformation Editor. Keep in mind that variable names are case-sensitive. Use the Value 
property to read from and write to individual variables. The Script component handles any required locking 
behind the scenes as your script manipulates the variables at run time. 





IMPORTANT 


The collection of ReadWriteVariables is only available in the PostExecute method to maximize performance and 
minimize the risk of locking conflicts. Therefore you cannot directly increment the value of a package variable as you 
process each row of data. Increment the value of a local variable instead, and set the value of the package variable to the 
value of the local variable in the PostExecute method after all data has been processed. You can also use the 
VariableDispenser property to work around this limitation, as described later in this topic. However, writing directly to a 


package variable as each row is processed will negatively impact performance and increase the risk of locking conflicts. 











For more information about the Script page of the Script Transformation Editor, see Configuring the Script 
Component in the Script Component Editor and Script Transformation Editor (Script Page). 


The Script component creates a Variables collection class in the ComponentWrapper project item with a 
strongly-typed accessor property for the value of each preconfigured variable where the property has the same 
name as the variable itself. This collection is exposed through the Variables property of the ScriptMain class. 
The accessor property provides read-only or read/write permission to the value of the variable as appropriate. 
For example, if you have added an integer variable named myIntegerVariable to the ReadOnlyVariables list, 
you can retrieve its value in your script by using the following code: 


Dim myIntegerVariableValue As Integer = Me.Variables.MyIntegerVariable 


You can also use the VariableDispenser property, accessed by calling Me.VariableDispenser , to work with 
variables in the Script component. In this case you are not using the typed and named accessor properties for 
variables, but accessing the variables directly. When using the VariableDispenser, you must handle both the 
locking semantics and the casting of data types for variable values in your own code. You have to use the 
VariableDispenser property instead of the named and typed accessor properties if you want to work with a 
variable that is not available at design time but is created programmatically at run time. 


See Also 


Integration Services (SSIS) Variables 
Use Variables in Packages 
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A connection manager is a convenient unit that encapsulates and stores the information that is required to 
connect to a data source of a particular type. For more information, see Integration Services (SSIS) Connections. 


You can make existing connection managers available for access by the custom script in the source or 
destination component by clicking the Add and Remove buttons on the Connection Managers page of the 
Script Transformation Editor. However, you must write your own custom code to load or save your data, and 
possibly to open and close the connection to the data source. For more information about the Connection 
Managers page of the Script Transformation Editor, see Configuring the Script Component in the Script 
Component Editor and Script Transformation Editor (Connection Managers Page). 


The Script component creates a Connections collection class in the ComponentWrapper project item that 
contains a strongly-typed accessor for each connection manager that has the same name as the connection 
manager itself. This collection is exposed through the Connections property of the ScriptMain class. The 
accessor property returns a reference to the connection manager as an instance of IDTSConnectionManager100. 
For example, if you have added a connection manager named MyADONETConnection on the Connection Managers 


page of the dialog box, you can obtain a reference to it in your script by adding the following code: 
Dim myADONETConnectionManager As IDTSConnectionManager100 = _ 


Me.Connections .MyADONETConnection 


NOTE 


You must know the type of connection that is returned by the connection manager before you call AcquireConnection. 
Because the Script task has Option Strict enabled, you must cast the connection, which is returned as type Object, to 
the appropriate connection type before you can use it. 











Next, you call the AcquireConnection method of the specific connection manager to obtain either the 
underlying connection or the information that is required to connect to the data source. For example, you obtain 
a reference to the System.Data.SqlConnection wrapped by an ADO.NET connection manager by using the 
following code: 


Dim myADOConnection As SqlConnection = _ 
CType(MyADONETConnectionManager .AcquireConnection(Nothing), SqlConnection) 


In contrast, the same call to a flat file connection manager returns only the path and file name of the file data 
source. 


Dim myFlatFile As String = _ 
CType(MyFlatFileConnectionManager .AcquireConnection(Nothing), String) 


You then must provide this path and file name to a System.1O.StreamReader or Streamwriter to read or 
write the data in the flat file. 





IMPORTANT 


When you write managed code in a Script component, you cannot call the AcquireConnection method of connection 
managers that return unmanaged objects, such as the OLE DB connection manager and the Excel connection manager. 
However, you can read the ConnectionString property of these connection managers, and connect to the data source 
directly in your code by using the connection string of an OLEDB connection from the System.Data.OleDb 


namespace. 


If you need to call the AcquireConnection method of a connection manager that returns an unmanaged object, use an 
ADO.NET connection manager. When you configure the ADO.NET connection manager to use an OLE DB provider, it 
connects by using the .NET Framework Data Provider for OLE DB. In this case, the AcquireConnection method returns a 
System.Data.OleDb.OleDbConnection instead of an unmanaged object. To configure an ADO.NET connection 
manager for use with an Excel data source, select the Microsoft OLE DB Provider for Jet, specify an Excel workbook, and 
then enter Excel 8.0 (for Excel 97 and later) as the value of Extended Properties on the All page of the 
Connection Manager dialog box. 











For more information about how to use connection managers with the script component, see Creating a Source 
with the Script Component and Creating a Destination with the Script Component. 


See Also 


Integration Services (SSIS) Connections 
Create Connection Managers 
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Events provide a way to report errors, warnings, and other information, such as task progress or status, to the 
containing package. The package provides event handlers for managing event notifications. The Script 
component can raise events by calling methods on the ComponentMetaData property of the ScriptMain class. 
For more information about how Integration Services packages handle events, see Integration Services (SSIS) 
Event Handlers. 


Events can be logged to any log provider that is enabled in the package. Log providers store information about 
events in a data store. The Script component can also use the Log method to log information to a log provider 
without raising an event. For more information about how to use the Log method, see the following section. 


To raise an event, the Script task calls one of the following methods of the |IDTSComponentMetaData100 
interface exposed by the ComponentMetaData property: 


EVENT DESCRIPTION 

FireCustomEvent Raises a user-defined custom event in the package. 
FireError Informs the package of an error condition. 
Firelnformation Provides information to the user. 

FireProgress Informs the package of the progress of the component. 
FireWarning Informs the package that the component is in a state that 


warrants user notification, but is not an error condition. 


Here is a simple example of raising an Error event: 
Dim myMetadata as IDTSComponentMetaData100 
myMetaData = Me.ComponentMetaData 


myMetaData.FireError(...) 


See Also 


Integration Services (SSIS) Event Handlers 
Add an Event Handler to a Package 
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Logging in Integration Services packages lets you save detailed information about execution progress, results, 
and problems by recording predefined events or user-defined messages for later analysis. The Script component 
can use the Log method of the ScriptMain class to log user-defined data. If logging is enabled, and the 
ScriptComponentLogEntry event is selected for logging on the Details tab of the Configure SSIS Logs 
dialog box, a single call to the Log method stores the event information in all the log providers that have been 
configured for the data flow task. 


Here is a simple example of logging: 
Dim bt(@) As Byte 

Me.Log("Test Log Event", _ 

8, 


bt) 





NOTE 


Although you can perform logging directly from your Script component, you may want to consider implementing events 
rather than logging. When using events, not only can you enable the logging of event messages, but you can respond to 
the event with default or user-defined event handlers. 





For more information about logging, see Integration Services (SSIS) Logging. 


See Also 


Integration Services (SSIS) Logging 
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The Script component is a configurable tool that you can use in the data flow of a package to fill almost any 
requirement that is not met by the sources, transformations, and destinations that are included with Integration 
Services. This section contains Script component code samples that demonstrate the four options for 
configuring the Script component: 


e Asa source. 

e Asa transformation with synchronous outputs. 
e Asa transformation with asynchronous outputs. 
e Asa destination. 


For additional examples of the Script component, see Additional Script Component Examples. 


In This Section 


Creating a Source with the Script Component 
Explains and demonstrates how to create a data flow source by using the Script component. 


Creating a Synchronous Transformation with the Script Component 

Explains and demonstrates how to create a data flow transformation with synchronous outputs by using the 
Script component. This kind of transformation modifies rows of data in place as they pass through the 
component. 


Creating an Asynchronous Transformation with the Script Component 

Explains and demonstrates how to create a data flow transformation with asynchronous outputs by using the 
Script component. This kind of transformation has to read all rows of data before it can add more information, 
such as calculated aggregates, to the data that passes through the component. 


Creating a Destination with the Script Component 
Explains and demonstrates how to create a data flow destination by using the Script component. 


See Also 


Comparing Scripting Solutions and Custom Objects 
Developing Specific Types of Data Flow Components 
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You use a source component in the data flow of an Integration Services package to load data from a data source 
to pass on to downstream transformations and destinations. Ordinarily you connect to the data source through 
an existing connection manager. 


For an overview of the Script component, see Extending the Data Flow with the Script Component. 


The Script component and the infrastructure code that it generates for you simplify significantly the process of 
developing a custom data flow component. However, to understand how the Script component works, you may 
find it useful to read through the steps that are involved in developing a custom data flow component. See the 
section Developing a Custom Data Flow Component, especially the topic Developing a Custom Source 
Component. 


Getting Started with a Source Component 


When you add a Script component to the Data Flow pane of SSIS Designer, the Select Script Component 
Type dialog box opens and prompts you to select a Source, Destination, or Transformation script. In this dialog 
box, select Source. 


Configuring a Source Component in Metadata-Design Mode 


After selecting to create a source component, you configure the component by using the Script 
Transformation Editor. For more information, see Configuring the Script Component in the Script Component 
Editor. 


A data flow source component has no inputs and supports one or more outputs. Configuring the outputs for the 
component is one of the steps that you must complete in metadata design mode, by using the Script 
Transformation Editor, before you write your custom script. 


You can also specify the script language by setting the ScriptLanguage property on the Script page of the 
Script Transformation Editor. 


NOTE 


To set the default script language for Script components and Script Tasks, use the Scripting language option on the 


General page of the Options dialog box. For more information, see General Page. 





Adding Connection Managers 


Ordinarily a source component uses an existing connection manager to connect to the data source from which it 
loads data into the data flow. On the Connection Managers page of the Script Transformation Editor, click 
Add to add the appropriate connection manager. 


However, a connection manager is only a convenient unit that encapsulates and stores the information that it 
must have to connect to a data source of a particular type. You must write your own custom code to load or save 
your data, and possibly to open and close the connection to the data source also. 


For general information about how to use connection managers with the Script component, see Connecting to 
Data Sources in the Script Component. 


For more information about the Connection Managers page of the Script Transformation Editor, see 
Script Transformation Editor (Connection Managers Page). 


Configuring Outputs and Output Columns 


A source component has no inputs and supports one or more outputs. On the Inputs and Outputs page of the 
Script Transformation Editor, a single output has been created by default, but no output columns have been 
created. On this page of the editor, you may need or want to configure the following items. 


e You must add and configure output columns manually for each output. Select the Output Columns folder 
for each output, and then use the Add Column and Remove Column buttons to manage the output 
columns for each output of the source component. Later, you will refer to the output columns in your 
script by the names that you assign here, by using the typed accessor properties created for you in the 
auto-generated code. 


e@ You may want to create one or more additional outputs, such as a simulated error output for rows that 
contain unexpected values. Use the Add Output and Remove Output buttons to manage the outputs of 
the source component. All input rows are directed to all available outputs unless you also specify an 
identical non-zero value for the ExclusionGroup property of those outputs where you intend to direct 
each row to only one of the outputs that share the same ExclusionGroup value. The particular integer 


value selected to identify the ExclusionGroup is not significant. 





NOTE 
You can also use a non-zero ExclusionGroup property value with a single output when you do not want to 
output all rows. In this case, however, you must explicitly call the DirectRowTo< outputbuffer> method for each 


row that you want to send to the output. 








e You may want to assign a friendly name to the outputs. Later, you will refer to the outputs by their names 
in your script, by using the typed accessor properties created for you in the auto-generated code. 


e Ordinarily multiple outputs in the same ExclusionGroup have the same output columns. However, if you 
are creating a simulated error output, you may want to add more columns to store error information. For 
information about how the data flow engine processes error rows, see Using Error Outputs in a Data 
Flow Component. In the Script component, however, you must write your own code to fill the additional 
columns with appropriate error information. For more information, see Simulating an Error Output for 
the Script Component. 


For more information about the Inputs and Outputs page of the Script Transformation Editor, see Script 
Transformation Editor (Inputs and Outputs Page). 


Adding Variables 


If there are any existing variables whose values you want to use in your script, you can add them in the 
ReadOnlyVariables and ReadWriteVariables property fields on the Script page of the Script 
Transformation Editor. 


When you enter multiple variables in the property fields, separate the variable names by commas. You can also 
enter multiple variables by clicking the ellipsis (...) button next to the ReadOnlyVariables and 
ReadWriteVariables property fields and selecting variables in the Select variables dialog box. 


For general information about how to use variables with the Script component, see Using Variables in the Script 
Component. 


For more information about the Script page of the Script Transformation Editor, see Script Transformation 
Editor (Script Page). 


Scripting a Source Component in Code-Design Mode 


After you have configured the metadata for your component, open the Microsoft Visual Studio Tools for 
Applications (VSTA) IDE to code your custom script. To open VSTA, click Edit Script on the Script page of the 
Script Transformation Editor. You can write your script by using either Microsoft Visual Basic or Microsoft 
Visual C#, depending on the script language selected for the ScriptLanguage property. 


For important information that applies to all kinds of components created by using the Script component, see 
Coding and Debugging the Script Component. 


Understanding the Auto-generated Code 


When you open the VSTA IDE after creating and configuring a source component, the editable ScriptMain class 
appears in the code editor. You write your custom code in the ScriptMain class. 


The ScriptMain class includes a stub for the CreateNewOutputRows method. The CreateNewOutputRows 
is the most important method in a source component. 


If you open the Project Explorer window in VSTA, you can see that the Script component has also generated 
read-only BufferWrapper and ComponentWrapper project items. The ScriptMain class inherits from 
UserComponent class in the ComponentWrapper project item. 


At run time, the data flow engine invokes the PrimeOutput method in the UserComponent class, which 
overrides the PrimeOutput method of the ScriptComponent parent class. The PrimeOutput method in turn 
calls the following methods: 


1. The CreateNewOutputRows method, which you override in ScriptMain to add rows from the data 
source to the output buffers, which are empty at first. 


2. The FinishOutputs method, which is empty by default. Override this method in ScriptMain to perform 
any processing that is required to complete the output. 


3. The private MarkOutputsAsFinished method, which calls the SetEndOfRowset method of the 
ScriptBuffer parent class to indicate to the data flow engine that the output is finished. You do not have to 
call SetEndOfRowset explicitly in your own code. 


Writing Your Custom Code 


To finish creating a custom source component, you may want to write script in the following methods available 
in the ScriptMain class. 


1. Override the AcquireConnections method to connect to the external data source. Extract the connection 
object, or the required connection information, from the connection manager. 


2. Override the PreExecute method to load data, if you can load all the source data at the same time. For 
example, you can execute a SqiCommand against an ADO.NET connection to a SQL Server database and 
load all the source data at the same time into a SqiDataReader. If you must load the source data one 
row ata time (for example, when reading a text file), you can load the data as you loop through rows in 
CreateNewOutputRows. 


3. Use the overridden CreateNewOutputRows method to add new rows to the empty output buffers and 
to fill in the values of each column in the new output rows. Use the AddRow method of each output 
buffer to add an empty new row, and then set the values of each column. Typically you copy values from 
the columns loaded from the external source. 


4. Override the PostExecute method to finish processing the data. For example, you can close the 
SqlDataReader that you used to load data. 


5. Override the ReleaseConnections method to disconnect from the external data source, if required. 


Examples 


The following examples demonstrate the custom code that is required in the ScriptMain class to create a 


source component. 








NOTE 


These examples use the Person.Address table in the AdventureWorks sample database and pass its first and fourth 
columns, the intAddressID and nvarchar(30)City columns, through the data flow. The same data is used in the source, 
transformation, and destination samples in this section. Additional prerequisites and assumptions are documented for 
each example. 





ADO.NET Source Example 


This example demonstrates a source component that uses an existing ADO.NET connection manager to load 
data from a SQL Server table into the data flow. 


If you want to run this sample code, you must configure the package and the component as follows: 


Te 


Create an ADO.NET connection manager that uses the SqlClient provider to connect to the 
AdventureWorks database. 


. Add a new Script component to the Data Flow designer surface and configure it as a source. 


. Open the Script Transformation Editor. On the Inputs and Outputs page, rename the default output 


with a more descriptive name such as MyAddressOutput, and add and configure the two output 
columns, AddressID and City. 





NOTE 


Be sure to change the data type of the City output column to DT_WSTR. 





. On the Connection Managers page, add or create the ADO.NET connection manager and give ita name 


such as MyADONETConnection. 


. On the Script page, click Edit Script and enter the script that follows. Then close the script development 


environment and the Script Transformation Editor. 


Create and configure a destination component, such as a SQL Server destination, or the sample 
destination component demonstrated in Creating a Destination with the Script Component, that expects 
the AddressID and City columns. Then connect the source component to the destination. (You can 
connect a source directly to a destination without any transformations.) You can create a destination table 
by running the following Transact-SQL command in the AdventureWorks database: 


CREATE TABLE [Person].[Address2]([AddressID] [int] NOT NULL, 
[City] [nvarchar](3@) NOT NULL) 


Run the sample. 





Imports System.Data.SqlClient 


Public Class ScriptMain 
Inherits UserComponent 


Dim connMgr As IDTSConnectionManager100 
Dim sqlConn As SqlConnection 
Dim sqlReader As SqlDataReader 


Public Overrides Sub AcquireConnections(ByVal Transaction As Object) 


connMgr = Me.Connections .MyADONETConnection 
sqlconn = CType(connMgr.AcquireConnection(Nothing), SqlConnection) 


End Sub 
Public Overrides Sub PreExecute() 
Dim cmd As New SqlCommand("SELECT AddressID, City, StateProvinceID FROM Person.Address", 
sqlConn) 
sqlReader = cmd.ExecuteReader 
End Sub 
Public Overrides Sub CreateNewOutputRows () 
Do While sqlReader.Read 
With MyAddressOutputBuffer 
.AddRow( ) 
.AddressID = sqlReader.GetInt32(0) 
-City = sqlReader.GetString(1) 
End With 
Loop 
End Sub 
Public Overrides Sub PostExecute() 
sqlReader.Close() 
End Sub 
Public Overrides Sub ReleaseConnections() 
connMgr ..ReleaseConnection(sqlConn) 


End Sub 


End Class 


using System.Data.SqlClient; 
public class ScriptMain: 
UserComponent 


IDTSConnectionManager1@@ connMgr; 
SqlConnection sqlConn; 
SqlDataReader sqlReader; 


public override void AcquireConnections(object Transaction) 


{ 


connMgr = this.Connections .MyADONETConnection; 
sqlconn = (SqlConnection)connMgr.AcquireConnection(null) ; 


public override void PreExecute() 


{ 


SqlCommand cmd = new SqlCommand("SELECT AddressID, City, StateProvinceID FROM 
Person.Address", sqlConn) ; 
sqlReader = cmd.ExecuteReader() ; 


} 
public override void CreateNewOutputRows () 
{ 
while (sqlReader.Read()) 
{ 
{ 
MyAddressOutputBuffer .AddRow() ; 
MyAddressOutputBuffer.AddressID = sqlReader.GetInt32(@) ; 
MyAddressOutputBuffer.City = sqlReader.GetString(1); 
t 
t 
t 
public override void PostExecute() 
{ 
sqlReader.Close(); 
} 
public override void ReleaseConnections() 
{ 
connMgr.ReleaseConnection(sqlConn) ; 
} 


Flat File Source Example 


This example demonstrates a source component that uses an existing Flat File connection manager to load data 
from a flat file into the data flow. The flat file source data is created by exporting it from SQL Server. 


If you want to run this sample code, you must configure the package and the component as follows: 


1. Use the SQL Server Import and Export Wizard to export the Person.Address table from the 
AdventureWorks sample database to a comma-delimited flat file. This sample uses the file name 
ExportedAddresses.txt. 


. Create a Flat File connection manager that connects to the exported data file. 
. Add a new Script component to the Data Flow designer surface and configure it as a source. 


. Open the Script Transformation Editor. On the Inputs and Outputs page, rename the default output 
with a more descriptive name such as MyAddressOutput. Add and configure the two output columns, 
AddressID and City. 


. On the Connection Managers page, add or create the Flat File connection manager, using a descriptive 
name such as MyFlatFileSrcConnectionManager. 


. On the Script page, click Edit Script and enter the script that follows. Then close the script development 
environment and the Script Transformation Editor. 


. Create and configure a destination component, such as a SQL Server destination, or the sample 
destination component demonstrated in Creating a Destination with the Script Component. Then connect 
the source component to the destination. (You can connect a source directly to a destination without any 
transformations.) You can create a destination table by running the following Transact-SQL command in 
the AdventureWorks database: 


CREATE TABLE [Person].[Address2]([AddressID] [int] NOT NULL, 
[City] [nvarchar](3@) NOT NULL) 


. Run the sample. 


Imports System.IO 


Public Class ScriptMain 
Inherits UserComponent 


Private textReader As StreamReader 
Private exportedAddressFile As String 


Public Overrides Sub AcquireConnections(ByVal Transaction As Object) 


Dim connMgr As IDTSConnectionManager10@ = _ 
Me.Connections .MyFlatFileSrcConnectionManager 
exportedAddressFile = _ 
CType(connMgr ..AcquireConnection(Nothing), String) 


End Sub 


Public Overrides Sub PreExecute() 

MyBase.PreExecute() 

textReader = New StreamReader(exportedAddressFile) 
End Sub 


Public Overrides Sub CreateNewOutputRows () 


Dim nextLine As String 
Dim columns As String() 


Dim delimiters As Char() 


delimiters = ",".ToCharArray 
nextLine = textReader.ReadLine 
Do While nextLine IsNot Nothing 
columns = nextLine.Split(delimiters) 
With MyAddressOutputBuffer 
.AddRow( ) 
-AddressID = columns(@) 
-City = columns(3) 
End With 
nextLine = textReader.ReadLine 
Loop 


End Sub 

Public Overrides Sub PostExecute() 
MyBase.PostExecute() 
textReader.Close() 


End Sub 


End Class 


using System.I0; 
public class ScriptMain: 


UserComponent 
{ 
private StreamReader textReader; 
private string exportedAddressFile; 
public override void AcquireConnections(object Transaction) 
{ 
IDTSConnectionManager1@@ connMgr = this.Connections.MyFlatFileSrcConnectionManager ; 
exportedAddressFile = (string)connMgr.AcquireConnection(nul1) ; 
t 
public override void PreExecute() 
{ 
base.PreExecute(); 
textReader = new StreamReader(exportedAddressFile) ; 
t 
public override void CreateNewOutputRows () 
{ 
string nextLine; 
string[] columns; 
char[] delimiters; 
delimiters = ",".ToCharArray(); 
nextLine = textReader.ReadLine(); 
while (nextLine != null) 
{ 
columns = nextLine.Split(delimiters) ; 
{ 
MyAddressOutputBuffer .AddRow() ; 
MyAddressOutputBuffer.AddressID = columns[@]; 
MyAddressOutputBuffer.City = columns[3]; 
t 
nextLine = textReader.ReadLine(); 
t 
t 
public override void PostExecute() 
{ 
base.PostExecute(); 
textReader.Close(); 
t 
t 


See Also 


Creating a Destination with the Script Component 
Developing a Custom Source Component 


Creating a Synchronous Transformation with the 
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Applies to: Q sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


You use a transformation component in the data flow of an Integration Services package to modify and analyze 
data as it passes from source to destination. A transformation with synchronous outputs processes each input 
row as it passes through the component. A transformation with asynchronous outputs waits until it has received 
all input rows to complete its processing. This topic discusses a synchronous transformation. For information 
about asynchronous transformations, see Creating an Asynchronous Transformation with the Script Component. 
For more information about the difference between synchronous and asynchronous components, see 
Understanding Synchronous and Asynchronous Transformations. 


For an overview of the Script component, see Extending the Data Flow with the Script Component. 


The Script component and the infrastructure code that it generates for you simplify significantly the process of 
developing a custom data flow component. However, to understand how the Script component works, you may 
find it useful to read the steps that you must follow in developing a custom data flow component in the section 
on Developing a Custom Data Flow Component, and especially Developing a Custom Transformation 


Component with Synchronous Outputs. 


Getting Started with a Synchronous Transformation Component 


When you add a Script component to the Data Flow pane of SSIS Designer, the Select Script Component 
Type dialog box opens and prompts you to select a Source, Destination, or Transformation component type. In 
this dialog box, select Transformation. 


Configuring a Synchronous Transformation Component in Metadata- 
Design Mode 
After you select the option to create a transformation component, you configure the component by using the 


Script Transformation Editor. For more information, see Configuring the Script Component in the Script 
Component Editor. 


To set the script language for the Script component, you set the ScriptLanguage property on the Script page 
of the Script Transformation Editor. 





NOTE 


To set the default scripting language for the Script component, use the Scripting language option on the General page 
of the Options dialog box. For more information, see eneral Page. 





A data flow transformation component has one input, and supports one or more outputs. Configuring the input 
and outputs for the component is one of the steps that you must complete in metadata design mode, by using 
the Script Transformation Editor, before you write your custom script. 


Configuring Input Columns 


A transformation component has one input. 





On the Input Columns page of the Script Transformation Editor, the column list shows the available 
columns from the output of the upstream component in the data flow. Select the columns that you want to 
transform or pass through. Mark any columns that you want to transform in place as Read/Write. 


For more information about the Input Columns page of the Script Transformation Editor, see Script 
Transformation Editor (Input Columns Page). 


Configuring Inputs, Outputs, and Output Columns 


A transformation component supports one or more outputs. 


On the Inputs and Outputs page of the Script Transformation Editor, you can see that a single output has 
been created, but the output has no columns. On this page of the editor, you may need or want to configure the 


following items. 


e Create one or more additional outputs, such as a simulated error output for rows that contain unexpected 
values. Use the Add Output and Remove Output buttons to manage the outputs of your synchronous 
transformation component. All input rows are directed to all available outputs unless you indicate that 
you intend to redirect each row to one output or the other. You indicate that you intend to redirect rows 
by specifying a non-zero integer value for the ExclusionGroup property on the outputs. The specific 
integer value entered in ExclusionGroup to identify the outputs is not significant, but you must use the 


same integer consistently for the specified group of outputs. 





NOTE 
You can also use a non-zero ExclusionGroup property value with a single output when you do not want to 
output all rows. However, in this case, you must explicitly call the DirectRowTo< outputbuffer> method for 


each row that you want to send to the output. 








e Assign a more descriptive name to the input and outputs. The Script component uses these names to 
generate the typed accessor properties that you will use to refer to the input and outputs in your script. 


e Leave columns as is for synchronous transformations. Typically a synchronous transformation does not 
add columns to the data flow. Data is modified in place in the buffer, and the buffer is passed on to the 
next component in the data flow. If this is the case, you do not have to add and configure output columns 
explicitly on the transformation's outputs. The outputs appear in the editor without any explicitly defined 


columns. 


e Add new columns to simulated error outputs for row-level errors. Ordinarily multiple outputs in the same 
ExclusionGroup have the same set of output columns. However, if you are creating a simulated error 
output, you may want to add more columns to contain error information. For information about how the 
data flow engine processes error rows, see Using Error Outputs in a Data Flow Component. Note that in 
the Script component you must write your own code to fill the additional columns with appropriate error 


information. For more information, see Simulating an Error Output for the Script Component. 


For more information about the Inputs and Outputs page of the Script Transformation Editor, see Script 
Transformation Editor (Inputs and Outputs Page). 

Adding Variables 

If you want to use existing variables in your script, you can add them in the ReadOnlyVariables and 


ReadWriteVariables property fields on the Script page of the Script Transformation Editor. 


When you add multiple variables in the property fields, separate the variable names by commas. You can also 
select multiple variables by clicking the ellipsis (...) button next to the ReadOnlyVariables and 
ReadWriteVariables property fields, and then selecting the variables in the Select variables dialog box. 


For general information about how to use variables with the Script component, see Using Variables in the Script 


Component. 


For more information about the Script page of the Script Transformation Editor, see Script Transformation 
Editor (Script Page). 


Scripting a Synchronous Transformation Component in Code-Design 
Mode 


After you have configured the metadata for your component, you can write your custom script. In the Script 
Transformation Editor, on the Script page, click Edit Script to open the Microsoft Visual Studio Tools for 
Applications (VSTA) IDE where you can add your custom script. The scripting language that you use depends on 
whether you selected Microsoft Visual Basic or Microsoft Visual C# as the script language for the 
ScriptLanguage property on the Script page. 


For important information that applies to all kinds of components created by using the Script component, see 
Coding and Debugging the Script Component. 


Understanding the Auto-generated Code 


When you open the VSTA IDE after you create and configuring a transformation component, the editable 
ScriptMain class appears in the code editor with a stub for the ProcessInputRow method. The ScriptMain 
class is where you will write your custom code, and ProcessInputRow is the most important method in a 


transformation component. 


If you open the Project Explorer window in VSTA, you can see that the Script component has also generated 
read-only BufferWrapper and ComponentWrapper project items. The ScriptMain class inherits from the 
UserComponent class in the ComponentWrapper project item. 


At run time, the data flow engine invokes the ProcessInput method in the UserComponent class, which 
overrides the Processinput method of the ScriptComponent parent class. The ProcessInput method in turn 
loops through the rows in the input buffer and calls the ProcessInputRow method one time for each row. 


Writing Your Custom Code 


A transformation component with synchronous outputs is the simplest of all data flow components to write. For 


example, the single-output example shown later in this topic consists of the following custom code: 


Row.City = UCase(Row.City) 


Row.City = (Row.City).ToUpper(); 


To finish creating a custom synchronous transformation component, you use the overridden ProcessInputRow 
method to transform the data in each row of the input buffer. The data flow engine passes this buffer, when full, 
to the next component in the data flow. 


Depending on your requirements, you may also want to write script in the PreExecute and PostExecute 
methods, available in the ScriptMain class, to perform preliminary or final processing. 


Working with Multiple Outputs 


Directing input rows to one of two or more possible outputs does not require much more custom code than the 
single-output scenario discussed earlier. For example, the two-output example shown later in this topic consists 
of the following custom code: 


Row.City = UCase(Row.City) 
If Row.City = "REDMOND" Then 

Row. DirectRowToMyRedmondAddresses() 
Else 

Row. DirectRowToMyOtherAddresses() 
End If 


Row.City = (Row.City).ToUpper(); 


if (Row.City=="REDMOND" ) 


{ 
Row. DirectRowToMyRedmondAddresses() ; 
} 
else 
{ 
Row. DirectRowToMyOtherAddresses() ; 
} 


In this example, the Script component generates the DirectRowTo<OutputBufferX> methods for you, based 
on the names of the outputs that you configured. You can use similar code to direct error rows to a simulated 
error output. 


Examples 


The examples here demonstrate the custom code that is required in the ScriptMain class to create a 
synchronous transformation component. 





NOTE 


These examples use the Person.Address table in the AdventureWorks sample database and pass its first and fourth 
columns, the intAddressID and nvarchar(30)City columns, through the data flow. The same data is used in the source, 
transformation, and destination samples in this section. Additional prerequisites and assumptions are documented for 
each example. 











Single Output Synchronous Transformation Example 


This example demonstrates a synchronous transformation component with a single output. This transformation 
passes through the AddressID column and converts the City column to uppercase. 


If you want to run this sample code, you must configure the package and the component as follows: 
1. Add a new Script component to the Data Flow designer surface and configure it as a transformation. 


2. Connect the output of a source or of another transformation to the new transformation component in 
SSIS Designer. This output should provide data from the Person.Address table of the AdventureWorks 
sample database that contains the AddressID and City columns. 


3. Open the Script Transformation Editor. On the Input Columns page, select the AddressID and City 
columns. Mark the City column as Read/Write. 


4. On the Inputs and Outputs page, rename the input and output with more descriptive names, such as 
MyAddressInput and MyAddressOutput. Notice that the SynchronousInputID of the output 
corresponds to the ID of the input. Therefore you do not have to add and configure output columns. 


5. On the Script page, click Edit Script and enter the script that follows. Then close the script development 
environment and the Script Transformation Editor. 


6. Create and configure a destination component that expects the AddressID and City columns, such as a 


SQL Server destination, or the sample destination component demonstrated in Creating a Destination 
with the Script Component. Then connect the output of the transformation to the destination component. 
You can create a destination table by running the following Transact-SQL command in the 
AdventureWorks database: 


CREATE TABLE [Person].[Address2]([AddressID] [int] NOT NULL, 
[City] [nvarchar](3@) NOT NULL) 


7. Run the sample. 


Public Class ScriptMain 
Inherits UserComponent 


Public Overrides Sub MyAddressInput_ProcessInputRow(ByVal Row As MyAddressInputBuffer ) 
Row.City = UCase(Row.City) 
End Sub 


End Class 


public class ScriptMain: 


UserComponent 
{ 
public override void MyAddressInput_ProcessInputRow(MyAddressInputBuffer Row) 
{ 
Row.City = (Row.City).ToUpper(); 
} 
} 


Two-Output Synchronous Transformation Example 


This example demonstrates a synchronous transformation component with two outputs. This transformation 


passes through the AddressID column and converts the City column to uppercase. If the city name is 


Redmond, it directs the row to one output; it directs all other rows to another output. 


If you want to run this sample code, you must configure the package and the component as follows: 


dl 


Add a new Script component to the Data Flow designer surface and configure it as a transformation. 


. Connect the output of a source or of another transformation to the new transformation component in 


SSIS Designer. This output should provide data from the Person.Address table of the AdventureWorks 
sample database that contains at least the AddressID and City columns. 


. Open the Script Transformation Editor. On the Input Columns page, select the AddressID and City 


columns. Mark the City column as Read/Write. 


. On the Inputs and Outputs page, create a second output. After you add the new output, make sure that 


you set its SynchronousInputlID to the ID of the input. This property is already set on the first output, 
which is created by default. For each output, set the ExclusionGroup property to the same non-zero 
value to indicate that you will split the input rows between two mutually exclusive outputs. You do not 
have to add any output columns to the outputs. 


. Rename the input and outputs with more descriptive names, such as MyAddressInput, 


MyRedmondAddresses, and MyOtherAddresses. 


6. On the Script page, click Edit Script and enter the script that follows. Then close the script development 
environment and the Script Transformation Editor. 


7. Create and configure two destination components that expect the AddressID and City columns, such as 
a SQL Server destination, a Flat File destination, or the sample destination component demonstrated in 
Creating a Destination with the Script Component. Then connect each of the outputs of the 
transformation to one of the destination components. You can create destination tables by running a 
Transact-SQL command similar to the following (with unique table names) in the AdventureWorks 
database: 


CREATE TABLE [Person]. [Address2]( 
[AddressID] [int] NOT NULL, 
[city] [nvarchar](3@) NOT NULL 


8. Run the sample. 
Public Class ScriptMain 
Inherits UserComponent 
Public Overrides Sub MyAddressInput_ProcessInputRow(ByVal Row As MyAddressInputBuffer ) 
Row.City = UCase(Row.City) 
If Row.City = "REDMOND" Then 
Row. DirectRowToMyRedmondAddresses() 
Else 
Row. DirectRowToMyOtherAddresses() 
End If 


End Sub 


End Class 


public class ScriptMain: 
UserComponent 


public override void MyAddressInput_ProcessInputRow(MyAddressInputBuffer Row) 


{ 
Row.City = (Row.City).ToUpper(); 
if (Row.City == "REDMOND") 
{ 
Row. DirectRowToMyRedmondAddresses() ; 
} 
else 
{ 
Row. DirectRowToMyOtherAddresses() ; 
} 
} 
} 
See Also 


Understanding Synchronous and Asynchronous Transformations 
Creating an Asynchronous Transformation with the Script Component 
Developing a Custom Transformation Component with Synchronous Outputs 


Creating an Asynchronous Transformation with the 
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Applies to: Q sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


You use a transformation component in the data flow of an Integration Services package to modify and analyze 
data as it passes from source to destination. A transformation with synchronous outputs processes each input 
row as it passes through the component. A transformation with asynchronous outputs may wait to complete its 
processing until the transformation has received all input rows, or the transformation may output certain rows 
before it has received all input rows. This topic discusses an asynchronous transformation. If your processing 
requires a synchronous transformation, see Creating a Synchronous Transformation with the Script Component. 
For more information about the differences between synchronous and asynchronous components, see 
Understanding Synchronous and Asynchronous Transformations. 


For an overview of the Script component, see Extending the Data Flow with the Script Component. 


The Script component and the infrastructure code that it generates for you simplify the process of developing a 
custom data flow component. However, to understand how the Script component works, you may find it useful 
to read through the steps that you must follow in developing a custom data flow component in the Developing 
a Custom Data Flow Component section, and especially Developing a Custom Transformation Component with 
Synchronous Outputs. 


Getting Started with an Asynchronous Transformation Component 


When you add a Script component to the Data Flow tab of SSIS Designer, the Select Script Component Type 
dialog box appears, prompting you to preconfigure the component as a source, transformation, or destination. 
In this dialog box, select Transformation. 


Configuring an Asynchronous Transformation Component in 
Metadata-Design Mode 


After you select the option to create a transformation component, you configure the component by using the 
Script Transformation Editor. For more information, see Configuring the Script Component in the Script 
Component Editor. 


To select the script language that the Script component will use, you set the ScriptLanguage property on the 
Script page of the Script Transformation Editor dialog box. 


NOTE 


To set the default scripting language for the Script component, use the Scripting language option on the General page 
of the Options dialog box. For more information, see General Page. 











A data flow transformation component has one input and supports one or more outputs. Configuring the input 
and outputs of your component is one of the steps that you must complete in metadata design mode, by using 
the Script Transformation Editor, before you write your custom script. 

Configuring Input Columns 


A transformation component created by using the Script component has a single input. 


On the Input Columns page of the Script Transformation Editor, the columns list shows the available 
columns from the output of the upstream component in the data flow. Select the columns that you want to 
transform or pass through. Mark any columns that you want to transform in place as Read/Write. 


For more information about the Input Columns page of the Script Transformation Editor, see Script 
Transformation Editor (Input Columns Page). 


Configuring Inputs, Outputs, and Output Columns 


A transformation component supports one or more outputs. 


Frequently a transformation with asynchronous outputs has two outputs. For example, when you count the 
number of addresses located in a specific city, you may want to pass the address data through to one output, 
while sending the result of the aggregation to another output. The aggregation output also requires a new 
output column. 


On the Inputs and Outputs page of the Script Transformation Editor, you see that a single output has been 
created by default, but no output columns have been created. On this page of the editor, you can configure the 


following items: 


e You may want to create one or more additional outputs, such as an output for the result of an 
aggregation. Use the Add Output and Remove Output buttons to manage the outputs of your 
asynchronous transformation component. Set the SynchronousInputID property of each output to zero 
to indicate that the output does not simply pass through data from an upstream component or transform 
it in place in the existing rows and columns. It is this setting that makes the outputs asynchronous to the 
input. 


e You may want to assign a friendly name to the input and outputs. The Script component uses these 
names to generate the typed accessor properties that you will use to refer to the input and outputs in 
your script. 


e Frequently an asynchronous transformation adds columns to the data flow. When the 
SynchronousInputID property of an output is zero, indicating that the output does not simply pass 
through data from an upstream component or transform it in place in the existing rows and columns, you 
must add and configure output columns explicitly on the output. Output columns do not have to have the 
same names as the input columns to which they are mapped. 


e You may want to add more columns to contain additional information. You must write your own code to 
fill the additional columns with data. For information about reproducing the behavior of a standard error 
output, see Simulating an Error Output for the Script Component. 


For more information about the Inputs and Outputs page of the Script Transformation Editor, see Script 
Transformation Editor (Inputs and Outputs Page). 


Adding Variables 

If there are any existing variables whose values you want to use in your script, you can add them in the 
ReadOnlyVariables and ReadWriteVariables property fields on the Script page of the Script Transformation 
Editor. 


When you add multiple variables in the property fields, separate the variable names by commas. You can also 
select multiple variables by clicking the ellipsis (...) button next to the ReadOnlyVariables and 
ReadWriteVariables property fields, and then selecting the variables in the Select variables dialog box. 


For general information about how to use variables with the Script component, see Using Variables in the Script 
Component. 


For more information about the Script page of the Script Transformation Editor, see Script Transformation 
Editor (Script Page). 


Scripting an Asynchronous Transformation Component in Code- 
Design Mode 


After you have configured all the metadata for your component, you can write your custom script. In the Script 
Transformation Editor, on the Script page, click Edit Script to open the Microsoft Visual Studio Tools for 
Applications (VSTA) IDE where you can add your custom script. The scripting language that you use depends on 
whether you selected Microsoft Visual Basic or Microsoft Visual C# as the script language for the 
ScriptLanguage property on the Script page. 


For important information that applies to all kinds of components created by using the Script component, see 
Coding and Debugging the Script Component. 


Understanding the Auto-generated Code 


When you open the VSTA IDE after creating and configuring a transformation component, the editable 
ScriptMain class appears in the code editor with stubs for the ProcessInputRow and the 
CreateNewOutputRows methods. The ScriptMain class is where you will write your custom code, and 
ProcessInputRow is the most important method in a transformation component. The CreateNewOutputRows 
method is more typically used in a source component, which is like an asynchronous transformation in that both 


components must create their own output rows. 


If you open the VSTA Project Explorer window, you can see that the Script component has also generated 
read-only BufferWrapper and ComponentWrapper project items. The ScriptMain class inherits from the 
UserComponent class in the ComponentWrapper project item. 


At run time, the data flow engine calls the PrimeOutput method in the UserComponent class, which overrides 
the PrimeOutput method of the ScriptComponent parent class. The PrimeOutput method in turn calls the 
CreateNewOutputRows method. 


Next, the data flow engine invokes the ProcessInput method in the UserComponent class, which overrides the 
ProcessInput method of the ScriptComponent parent class. The ProcessInput method in turn loops through the 
rows in the input buffer and calls the ProcessInputRow method one time for each row. 


Writing Your Custom Code 


To finish creating a custom asynchronous transformation component, you must use the overridden 
ProcessInputRow method to process the data in each row of the input buffer. Because the outputs are not 
synchronous to the input, you must explicitly write rows of data to the outputs. 


In an asynchronous transformation, you can use the AddRow method to add rows to the output as appropriate 
from within the ProcessInputRow or ProcessInput methods. You do not have to use the CreateNewOutputRows 
method. If you are writing a single row of results, such as aggregation results, to a particular output, you can 
create the output row beforehand by using the CreateNewOutputRows method, and fill in its values later after 
processing all input rows. However it is not useful to create multiple rows in the CreateNewOutputRows 
method, because the Script component only lets you use the current row in an input or output. The 
CreateNewOutputRows method is more important in a source component where there are no input rows to 


process. 


You may also want to override the ProcessInput method itself, so that you can do additional preliminary or final 
processing before or after you loop through the input buffer and call ProcessInputRow for each row. For 
example, one of the code examples in this topic overrides ProcessInput to count the number of addresses ina 
specific city as ProcessInputRow loops through rows**.** The example writes the summary value to the second 
output after all rows have been processed. The example completes the output in ProcessInput because the 
output buffers are no longer available when PostExecute is called. 


Depending on your requirements, you may also want to write script in the PreExecute and PostExecute methods 
available in the ScriptMain class to perform any preliminary or final processing. 





NOTE 


If you were developing a custom data flow component from scratch, it would be important to override the PrimeOutput 
method to cache references to the output buffers so that you could add rows of data to the buffers later. In the Script 
component, this is not necessary because you have an automatically generated class representing each output buffer in 


the BufferWrapper project item. 











Example 


This example demonstrates the custom code that is required in the ScriptMain class to create an asynchronous 


transformation component. 


NOTE 


These examples use the Person.Address table in the AdventureWorks sample database and pass its first and fourth 
columns, the intAddressID and nvarchar(30)City columns, through the data flow. The same data is used in the source, 
transformation, and destination samples in this section. Additional prerequisites and assumptions are documented for 


each example. 











This example demonstrates an asynchronous transformation component with two outputs. This transformation 
passes through the AddressID and City columns to one output, while it counts the number of addresses 
located in a specific city (Redmond, Washington, U.S.A.), and then outputs the resulting value to a second output. 


If you want to run this sample code, you must configure the package and the component as follows: 
1. Add a new Script component to the Data Flow designer surface and configure it as a transformation. 


2. Connect the output of a source or of another transformation to the new transformation component in the 
designer. This output should provide data from the Person.Address table of the AdventureWorks 
sample database that contains at least the AddressID and City columns. 


3. Open the Script Transformation Editor. On the Input Columns page, select the AddressID and City 
columns. 


4. On the Inputs and Outputs page, add and configure the AddressID and City output columns on the 
first output. Add a second output, and add an output column for the summary value on the second 
output. Set the SynchronousInputID property of the first output to 0, because this example copies each 
input row explicitly to the first output. The SynchronousInputID property of the newly-created output is 
already set to 0. 


5. Rename the input, the outputs, and the new output column to give them more descriptive names. The 
example uses MyAddressInput as the name of the input, MyAddressOutput and 
MySummaryOutput for the outputs, and MyRedmondCount for the output column on the second 
output. 


6. On the Script page, click Edit Script and enter the script that follows. Then close the script development 
environment and the Script Transformation Editor. 


7. Create and configure a destination component for the first output that expects the AddressID and City 
columns, such as a SQL Server destination, or the sample destination component demonstrated in 
Creating a Destination with the Script Component, . Then connect the first output of the transformation, 
MyAddressOutput, to the destination component. You can create a destination table by running the 
following Transact-SQL command in the AdventureWorks database: 


CREATE TABLE [Person].[Address2]([AddressID] [int] NOT NULL, 
[City] [nvarchar](3@) NOT NULL) 


8. Create and configure another destination component for the second output. Then connect the second 
output of the transformation, MySummaryOutput, to the destination component. Because the second 
output writes a single row with a single value, you can easily configure a destination with a Flat File 
connection manager that connects to a new file that has a single column. In the example, this destination 
column is named MyRedmondCount. 


9. Run the sample. 
Public Class ScriptMain 
Inherits UserComponent 
Private myRedmondAddressCount As Integer 
Public Overrides Sub CreateNewOutputRows () 
MySummaryOutputBuf fer .AddRow() 
End Sub 
Public Overrides Sub MyAddressInput_ProcessInput(ByVal Buffer As MyAddressInputBuffer ) 
While Buffer.NextRow() 
MyAddressInput_ProcessInputRow(Buffer ) 
End While 
If Buffer.EndOfRowset Then 
MyAddressOutputBuf fer. SetEndOfRowset ( ) 
MySummaryOutputBuffer.MyRedmondCount = myRedmondAddressCount 
MySummaryOutputBuffer .SetEndOfRowset () 
End If 
End Sub 
Public Overrides Sub MyAddressInput_ProcessInputRow(ByVal Row As MyAddressInputBuffer ) 
With MyAddressOutputBuffer 
.AddRow( ) 
-AddressID = Row.AddressID 
-City = Row.City 
End With 
If Row.City.ToUpper = "REDMOND" Then 
myRedmondAddressCount += 1 
End If 


End Sub 


End Class 


public class ScriptMain: 


UserComponent 
i 
private int myRedmondAddressCount; 
public override void CreateNewOutputRows () 
{ 
MySummaryOutputBuffer .AddRow() ; 
t 
public override void MyAddressInput_ProcessInput(MyAddressInputBuffer Buffer) 
{ 
while (Buffer.NextRow()) 
{ 
MyAddressInput_ProcessInputRow( Buffer) ; 
i 
if (Buffer.EndOfRowset() ) 
{ 
MyAddressOutputBuffer.SetEndOfRowset(); 
MySummaryOutputBuffer.MyRedmondCount = myRedmondAddressCount ; 
MySummaryOutputBuffer. SetEndOfRowset(); 
y 
t 
public override void MyAddressInput_ProcessInputRow(MyAddressInputBuffer Row) 
{ 
{ 
MyAddressOutputBuffer .AddRow() ; 
MyAddressOutputBuffer.AddressID = Row.AddressID; 
MyAddressOutputBuffer.City = Row.City; 
i 
if (Row.City.ToUpper() == "REDMOND" ) 
{ 
myRedmondAddressCount += 1; 
y 
t 
i 
See Also 


Understanding Synchronous and Asynchronous Transformations 
Creating a Synchronous Transformation with the Script Component 
Developing a Custom Transformation Component with Asynchronous Outputs 


Creating a Destination with the Script Component 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


You use a destination component in the data flow of an Integration Services package to save data received from 
upstream sources and transformations to a data source. Ordinarily the destination component connects to the 
data source through an existing connection manager. 


For an overview of the Script component, see Extending the Data Flow with the Script Component. 


The Script component and the infrastructure code that it generates for you simplify significantly the process of 
developing a custom data flow component. However, to understand how the Script component works, you may 
find it useful to read through the steps for developing a custom data flow components in the Developing a 
Custom Data Flow Component section, and especially Developing a Custom Destination Component. 


Getting Started with a Destination Component 


When you add a Script component to the Data Flow tab of SSIS Designer, the Select Script Component Type 
dialog box opens and prompts you to select a Source, Destination, or Transformation script. In this dialog 
box, select Destination. 


Next, connect the output of a transformation to the destination component in SSIS Designer. For testing, you can 
connect a source directly to a destination without any transformations. 


Configuring a Destination Component in Metadata-Design Mode 


After you select the option to create a destination component, you configure the component by using the Script 
Transformation Editor. For more information, see Configuring the Script Component in the Script Component 
Editor. 


To select the script language that the Script destination will use, you set the ScriptLanguage property on the 
Script page of the Script Transformation Editor dialog box. 


NOTE 


To set the default scripting language for the Script component, use the Scripting language option on the General page 


of the Options dialog box. For more information, see General Page. 





A data flow destination component has one input and no outputs. Configuring the input for the component is 
one of the steps that you must complete in metadata design mode, by using the Script Transformation 
Editor, before you write your custom script. 


Adding Connection Managers 


Ordinarily a destination component uses an existing connection manager to connect to the data source to which 
it saves data from the data flow. On the Connection Managers page of the Script Transformation Editor, 
click Add to add the appropriate connection manager. 


However, a connection manager is just a convenient unit that encapsulates and stores the information that is 
required to connect to a data source of a particular type. You must write your own custom code to load or save 
your data, and possibly to open and close the connection to the data source. 


For general information about how to use connection managers with the Script component, see Connecting to 
Data Sources in the Script Component. 


For more information about the Connection Managers page of the Script Transformation Editor, see 
Script Transformation Editor (Connection Managers Page). 


Configuring Inputs and Input Columns 


A destination component has one input and no outputs. 


On the Input Columns page of the Script Transformation Editor, the column list shows the available 
columns from the output of the upstream component in the data flow. Select the columns that you want to save. 


For more information about the Input Columns page of the Script Transformation Editor, see Script 
Transformation Editor (Input Columns Page). 


The Inputs and Outputs page of the Script Transformation Editor shows a single input, which you can 
rename. You will refer to the input by its name in your script by using the accessor property created in the auto- 
generated code. 


For more information about the Inputs and Outputs page of the Script Transformation Editor, see Script 
Transformation Editor (Inputs and Outputs Page). 


Adding Variables 


If you want to use existing variables in your script, you can add them in the ReadOnlyVariables and 
ReadWriteVariables property fields on the Script page of the Script Transformation Editor. 


When you add multiple variables in the property fields, separate the variable names by commas. You can also 
select multiple variables by clicking the ellipsis (...) button next to the ReadOnlyVariables and 
ReadWriteVariables property fields, and then selecting the variables in the Select variables dialog box. 


For general information about how to use variables with the Script component, see Using Variables in the Script 
Component. 


For more information about the Script page of the Script Transformation Editor, see Script Transformation 
Editor (Script Page). 


Scripting a Destination Component in Code-Design Mode 


After you have configured the metadata for your component, you can write your custom script. In the Script 
Transformation Editor, on the Script page, click Edit Script to open the Microsoft Visual Studio Tools for 
Applications (VSTA) IDE where you can add your custom script. The scripting language that you use depends on 
whether you selected Microsoft Visual Basic or Microsoft Visual C# as the script language for the 
ScriptLanguage property on the Script page. 


For important information that applies to all kinds of components created by using the Script component, see 
Coding and Debugging the Script Component. 


Understanding the Auto-generated Code 


When you open the VSTA IDE after you create and configuring a destination component, the editable 
ScriptMain class appears in the code editor with a stub for the ProcessInputRow method. The ScriptMain 
class is where you will write your custom code, and ProcessInputRow is the most important method in a 
destination component. 


If you open the Project Explorer window in VSTA, you can see that the Script component has also generated 
read-only BufferWrapper and ComponentWrapper project items. The ScriptMain class inherits from 
UserComponent class in the ComponentWrapper project item. 


At run time, the data flow engine invokes the ProcessInput method in the UserComponent class, which 


overrides the Processinput method of the ScriptComponent parent class. The ProcessInput method in turn 
loops through the rows in the input buffer and calls the ProcessInputRow method one time for each row. 


Writing Your Custom Code 
To finish creating a custom destination component, you may want to write script in the following methods 


available in the ScriptMain class. 


1. Override the AcquireConnections method to connect to the external data source. Extract the connection 
object, or the required connection information, from the connection manager. 


2. Override the PreExecute method to prepare to save the data. For example, you may want to create and 
configure aSqlCommand and its parameters in this method. 


3. Use the overridden ProcessInputRow method to copy each input row to the external data source. For 
example, for a SQL Server destination, you can copy the column values into the parameters of a 
SqlCommand and execute the command one time for each row. For a flat file destination, you can write 


the values for each column to a StreamWriter, separating the values by the column delimiter. 


4. Override the PostExecute method to disconnect from the external data source, if required, and to 
perform any other required cleanup. 


Examples 


The examples that follow demonstrate code that is required in the ScriptMain class to create a destination 
component. 





NOTE 


These examples use the Person.Address table in the AdventureWorks sample database and pass its first and fourth 
columns, the intAddress/D and nvarchar(30)City columns, through the data flow. The same data is used in the source, 
transformation, and destination samples in this section. Additional prerequisites and assumptions are documented for 
each example. 











ADO.NET Destination Example 


This example demonstrates a destination component that uses an existing ADO.NET connection manager to save 
data from the data flow into a SQL Server table. 


If you want to run this sample code, you must configure the package and the component as follows: 


1. Create an ADO.NET connection manager that uses the SqlClient provider to connect to the 
AdventureWorks database. 


2. Create a destination table by running the following Transact-SQL command in the AdventureWorks 


database: 


CREATE TABLE [Person].[Address2]([AddressID] [int] NOT NULL, 
[City] [nvarchar](3@) NOT NULL) 


3. Add a new Script component to the Data Flow designer surface and configure it as a destination. 


4. Connect the output of an upstream source or transformation to the destination component in SSIS 
Designer. (You can connect a source directly to a destination without any transformations.) This output 
should provide data from the Person.Address table of the AdventureWorks sample database that 
contains at least the AddressID and City columns. 


5. Open the Script Transformation Editor. On the Input Columns page, select the AddressID and City 


input columns. 


. On the Inputs and Outputs page, rename the input with a more descriptive name such as 
MyAddressInput. 


. On the Connection Managers page, add or create the ADO.NET connection manager with a name such 
as MyADONETConnectionManager. 


. On the Script page, click Edit Script and enter the script that follows. Then close the script development 
environment. 


. Close the Script Transformation Editor and run the sample. 


Imports System.Data.SqlClient 


Public Class ScriptMain 
Inherits UserComponent 


Dim connMgr As IDTSConnectionManager100 
Dim sqlConn As SqlConnection 

Dim sqlCmd As SqlCommand 

Dim sqlParam As SqlParameter 


Public Overrides Sub AcquireConnections(ByVal Transaction As Object) 


connMgr = Me.Connections .MyADONETConnectionManager 
sqlconn = CType(connMgr.AcquireConnection(Nothing), SqlConnection) 


End Sub 
Public Overrides Sub PreExecute() 


sqlcmd = New SqlCommand("INSERT INTO Person.Address2(AddressID, City) " & _ 
"VALUES(@addressid, @city)", sqlConn) 

sqlParam = New SqlParameter("@addressid", SqlDbType. Int) 

sqlcCmd.Parameters.Add(sqlParam) 

sqlParam = New SqlParameter("@city", SqlDbType.NVarChar, 30) 

sqlcmd.Parameters.Add(sqlParam) 


End Sub 
Public Overrides Sub MyAddressInput_ProcessInputRow(ByVal Row As MyAddressInputBuffer) 
With sqlcmd 
.Parameters("@addressid").Value = Row.AddressID 
.Parameters("@city").Value = Row.City 
-ExecuteNonQuery () 
End With 
End Sub 
Public Overrides Sub ReleaseConnections() 
connMgr ..ReleaseConnection(sqlConn) 


End Sub 


End Class 


using System.Data.SqlClient; 
public class ScriptMain: 


UserComponent 
{ 
IDTSConnectionManager1@@ connMgr; 
SqlConnection sqlConn; 
SqlCommand sqlCmd; 
SqlParameter sqlParam; 
public override void AcquireConnections(object Transaction) 
{ 
connMgr = this.Connections .MyADONETConnectionManager ; 
sqlconn = (SqlConnection)connMgr.AcquireConnection(null) ; 
} 
public override void PreExecute() 
{ 
sqlcmd = new SqlCommand("INSERT INTO Person.Address2(AddressID, City) " + 
"VALUES(@addressid, @city)", sqlConn); 
sqlParam = new SqlParameter("@addressid", SqlDbType. Int) ; 
sqlcCmd.Parameters.Add(sqlParam) ; 
sqlParam = new SqlParameter("@city", SqlDbType.NVarChar, 30); 
sqlcmd.Parameters.Add(sqlParam) ; 
} 
public override void MyAddressInput_ProcessInputRow(MyAddressInputBuffer Row) 
{ 
{ 
sqlcmd.Parameters["@addressid"].Value = Row.AddressID; 
sqlcmd.Parameters["@city"].Value = Row.City; 
sqlcmd.ExecuteNonQuery() ; 
} 
} 
public override void ReleaseConnections() 
ib 
connMgr.ReleaseConnection(sqlConn) ; 
} 
i 


Flat File Destination Example 


This example demonstrates a destination component that uses an existing Flat File connection manager to save 
data from the data flow to a flat file. 


If you want to run this sample code, you must configure the package and the component as follows: 


1. Create a Flat File connection manager that connects to a destination file. The file does not have to exist; 
the destination component will create it. Configure the destination file as a comma-delimited file that 
contains the AddressID and City columns. 


2. Add anew Script component to the Data Flow designer surface and configure it as a destination. 


3. Connect the output of an upstream source or transformation to the destination component in SSIS 
Designer. (You can connect a source directly to a destination without any transformations.) This output 
should provide data from the Person.Address table of the AdventureWorks sample database, and 
should contain at least the AddressID and City columns. 


. Open the Script Transformation Editor. On the Input Columns page, select the AddressID and City 
columns. 


. On the Inputs and Outputs page, rename the input with a more descriptive name, such as 
MyAddressInput. 


. On the Connection Managers page, add or create the Flat File connection manager with a descriptive 
name such as MyFlatFileDestConnectionManager. 


. On the Script page, click Edit Script and enter the script that follows. Then close the script development 
environment. 


. Close the Script Transformation Editor and run the sample. 


Imports System.IO 


Public Class ScriptMain 
Inherits UserComponent 


Dim copiedAddressFile As String 


Private textwWriter As StreamWriter 
Private columnDelimiter As String = 


a 
Public Overrides Sub AcquireConnections(ByVal Transaction As Object) 
Dim connMgr As IDTSConnectionManager10@ = _ 
Me.Connections .MyFlatFileDestConnectionManager 
copiedAddressFile = CType(connMgr.AcquireConnection(Nothing), String) 
End Sub 
Public Overrides Sub PreExecute() 
textWriter = New StreamWriter(copiedAddressFile, False) 
End Sub 
Public Overrides Sub MyAddressInput_ProcessInputRow(ByVal Row As MyAddressInputBuffer) 
With textWriter 
If Not Row.AddressID_IsNull Then 
.Write(Row.AddressID) 
End If 
.Write(columnDelimiter) 
If Not Row.City_IsNull Then 
-Write(Row.City) 
End If 
.WriteLine() 
End With 
End Sub 
Public Overrides Sub PostExecute() 
textwWriter.Close() 


End Sub 


End Class 


using System.I0; 
public class ScriptMain: 


UserComponent 
{ 
string copiedAddressFile; 
private StreamWriter textWriter; 
private string columnDelimiter = ","; 
public override void AcquireConnections(object Transaction) 
{ 
IDTSConnectionManager1@@ connMgr = this.Connections.MyFlatFileDestConnectionManager ; 
copiedAddressFile = (string) connMgr.AcquireConnection(null) ; 
t 
public override void PreExecute() 
{ 
textWriter = new StreamWriter(copiedAddressFile, false); 
} 
public override void MyAddressInput_ProcessInputRow(MyAddressInputBuffer Row) 
{ 
{ 
if (!Row.AddressID_IsNul1l1l) 
{ 
textWriter.Write(Row.AddressID) ; 
t 
textwWriter.Write(columnDelimiter) ; 
if (!Row.City_IsNull1) 
{ 
textWriter.Write(Row.City) ; 
t 
textWriter.WriteLine(); 
} 
t 
public override void PostExecute() 
{ 
textWriter.Close(); 
t 
t 


See Also 


Creating a Source with the Script Component 
Developing a Custom Destination Component 


Additional Script Component Examples 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


The Script component is a configurable tool that you can use in the data flow of a package to fill almost any 
requirement that is not met by the sources, transformations, and destinations that are included with Integration 
Services. This section contains Script component code samples that demonstrate the various types of 
functionality that are available. 


For samples that demonstrate how to configure the Script component as a basic source, transformation, or 
destination, see Developing Specific Types of Script Components. 


NOTE 


If you want to create components that you can more easily reuse across multiple Data Flow tasks and multiple packages, 
consider using the code in these Script component samples as the starting point for custom data flow components. For 
more information, see Developing a Custom Data Flow Component. 











In This Section 


Simulating an Error Output for the Script Component 
The Script component does not support a standard error output, but you can simulate a standard error output 
with very little additional configuration and coding. 


Enhancing an Error Output with the Script Component 
Explains and demonstrates how to add additional information to a standard error output by using the Script 
component. 


Creating an ODBC Destination with the Script Component 
Explains and demonstrates how to create an ODBC data flow destination by using the Script component. 


Parsing Non-Standard Text File Formats with the Script Component 
Explains and demonstrates how to parse two different non-standard text file formats into destination tables. 


Creating an ODBC Destination with the Script 


Component 
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In SQL Server Integration Services, you typically save data to an ODBC destination by using an ADO.NET 
destination and the INET Framework Data Provider for ODBC. However, you can also create an ad hoc ODBC 
destination for use in a single package. To create this ad hoc ODBC destination, you use the Script component as 
shown in the following example. 





NOTE 


If you want to create a component that you can more easily reuse across multiple Data Flow tasks and multiple packages, 
consider using the code in this Script component sample as the starting point for a custom data flow component. For 


more information, see Developing a Custom Data Flow Component. 





Example 


The following example demonstrates how to create a destination component that uses an existing ODBC 
connection manager to save data from the data flow into a Microsoft SQL Server table. 


This example is a modified version of the custom ADO.NET destination that was demonstrated in the topic, 
Creating a Destination with the Script Component. However, in this example, the custom ADO.NET destination 
has been modified to work with an ODBC connection manager and save data to an ODBC destination. These 
modifications also include the following changes: 


e You cannot call the AcquireConnection method of the ODBC connection manager from managed code, 
because it returns a native object. Therefore, this sample uses the connection string of the connection 
manager to connect to the data source directly by using the managed ODBC .NET Framework Data 
Provider. 


e The OdbcCommand expects positional parameters. The positions of the parameters are indicated by the 
question marks (?) in the text of the command. (In contrast, a SqiCommand expects named parameters.) 


This example uses the Person.Address table in the AdventureWorks sample database. The example passes 
the first and fourth columns, the int Address/D and nvarchar(30) City columns, of this table through the data 
flow. This same data is used in the source, transformation, and destination samples in the topic, Developing 
Specific Types of Script Components. 


To configure this Script Component example 


1. Create an ODBC connection manager that connects to the AdventureWorks database. 


2. Create a destination table by running the following Transact-SQL command in the AdventureWorks 
database: 


CREATE TABLE [Person].[Address2]([AddressID] [int] NOT NULL, 
[City] [nvarchar](3@) NOT NULL) 


3. Add a new Script component to the Data Flow designer surface and configure it as a destination. 





. Connect the output of an upstream source or transformation to the destination component in SSIS 
Designer. (You can connect a source directly to a destination without any transformations.) To ensure that 
this sample works, the output of the upstream component must include at least the AddressID and City 
columns from the Person.Address table of the AdventureWorks sample database. 


. Open the Script Transformation Editor. On the Input Columns page, select the AddressID and City 
columns. 


. On the Inputs and Outputs page, rename the input with a more descriptive name such as 
MyAddressInput. 


. On the Connection Managers page, add or create the ODBC connection manager with a descriptive 
name such as MyODBCConnectionManager. 


. On the Script page, click Edit Script, and then enter the script shown below in the ScriptMain class. 


. Close the script development environment, close the Script Transformation Editor, and then run the 
sample. 


Imports System.Data.Odbc 


Public Class ScriptMain 
Inherits UserComponent 


Dim odbcConn As OdbcConnection 
Dim odbcCmd As OdbcCommand 
Dim odbcParam As OdbcParameter 
Public Overrides Sub AcquireConnections(ByVal Transaction As Object) 
Dim connectionString As String 
connectionString = Me.Connections .MyODBCConnectionManager .ConnectionString 
odbcConn = New OdbcConnection(connectionString) 
odbcConn.Open() 
End Sub 
Public Overrides Sub PreExecute() 
odbcCmd = New OdbcCommand("INSERT INTO Person.Address2(AddressID, City) " & _ 
"VALUES(?, ?)", odbcConn) 
odbcParam = New OdbcParameter("@addressid", OdbcType. Int) 
odbcCmd. Parameters .Add(odbcParam) 
odbcParam = New OdbcParameter("@city", OdbcType.NVarChar, 30) 
odbcCmd.Parameters.Add(odbcParam) 
End Sub 
Public Overrides Sub MyAddressInput_ProcessInputRow(ByVal Row As MyAddressInputBuffer) 
With odbcCmd 
.Parameters("@addressid").Value = Row.AddressID 
.Parameters("@city").Value = Row.City 
-ExecuteNonQuery () 
End With 
End Sub 
Public Overrides Sub ReleaseConnections() 
odbcConn.Close() 


End Sub 


End Class 


using System.Data.Odbc; 


public class ScriptMain : 


UserComponent 
{ 
OdbcConnection odbcConn; 
OdbcCommand odbcCmd; 
OdbcParameter odbcParam; 
public override void AcquireConnections(object Transaction) 
{ 
string connectionString; 
connectionString = this.Connections.MyODBCConnectionManager.ConnectionString; 
odbcConn = new OdbcConnection(connectionString) ; 
odbcConn.Open(); 
t 
public override void PreExecute() 
{ 
odbcCmd = new OdbcCommand("INSERT INTO Person.Address2(AddressID, City) " + 
"VALUES(?, ?)", odbcConn); 
odbcParam = new OdbcParameter("@addressid", OdbcType. Int) ; 
odbcCmd.Parameters.Add(odbcParam) ; 
odbcParam = new OdbcParameter("@city", OdbcType.NVarChar, 30); 
odbcCmd. Parameters .Add(odbcParam) ; 
t 
public override void MyAddressInput_ProcessInputRow(MyAddressInputBuffer Row) 
{ 
{ 
odbcCmd.Parameters["@addressid"].Value = Row.AddressID; 
odbcCmd.Parameters["@city"].Value = Row.City; 
odbcCmd.ExecuteNonQuery () ; 
} 
t 
public override void ReleaseConnections() 
{ 
odbcConn.Close(); 
t 
t 


See Also 


Creating a Destination with the Script Component 


Enhancing an Error Output with the Script 


Component 
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By default, the two extra columns in an Integration Services error output, ErrorCode and ErrorColumn, contain 
only numeric codes that represent an error number and the ID of the column in which the error occurred. These 
numeric values may be of limited use without the corresponding error description and column name. 


This topic describes how to add the error description and the column name to existing error output data in the 
data flow by using the Script component. The example adds the error description that corresponds to a specific 
predefined Integration Services error code by using the GetErrorDescription method of the 
IDTSComponentMetaData1 00 interface, available through the ComponentMetaData property of the Script 
component. Then the example adds the column name that corresponds to the captured lineage ID by using the 
GetldentificationStringByID method of the same interface. 


NOTE 


If you want to create a component that you can more easily reuse across multiple Data Flow tasks and multiple packages, 
consider using the code in this Script component sample as the starting point for a custom data flow component. For 
more information, see Developing a Custom Data Flow Component. 











Example 


The example shown here uses a Script component configured as a transformation to add the error description 
and the column name to existing error output data in the data flow. 


For more information about how to configure the Script component for use as a transformation in the data flow, 
see Creating a Synchronous Transformation with the Script Component and Creating an Asynchronous 
Transformation with the Script Component. 


To configure this Script Component example 

1. Before creating the new Script component, configure an upstream component in the data flow to redirect 
rows to its error output when an error or truncation occurs. For testing purposes, you may want to 
configure a component in a manner that ensures that errors will occur-for example, by configuring a 
Lookup transformation between two tables where the lookup will fail. 


2. Add a new Script component to the Data Flow designer surface and configure it as a transformation. 
3. Connect the error output from the upstream component to the new Script component. 


4. Open the Script Transformation Editor, and on the Script page, for the ScriptLanguage property, 
select the script language. 


5. Click Edit Script to open the Microsoft Visual Studio Tools for Applications (VSTA) IDE and add the 
sample code shown below. 


6. Close VSTA. 


7. In the Script Transformation Editor, on the Input Columns page, select the ErrorCode and ErrorColumn 
columns. 


10. 


Walls 


On the Inputs and Outputs page, add two new columns. 


e Add anew output column of type String named ErrorDescription. Increase the default length of 
the new column to 255 to support long messages. 


e Add another new output column of type String named ColumnName. Increase the default length 
of the new column to 255 to support long values. 


Close the Script Transformation Editor. 


Attach the output of the Script component to a suitable destination. A Flat File destination is the easiest to 
configure for ad hoc testing. 


Run the package. 


Public Class ScriptMain " VB 
Inherits UserComponent 
Public Overrides Sub Input@_ProcessInputRow(ByVal Row As Input@Buffer) 


Row.ErrorDescription = _ 
Me. ComponentMetaData.GetErrorDescription(Row.ErrorCode) 


Dim componentMetaData13@ = TryCast(Me.ComponentMetaData, IDTSComponentMetaData130) 
If componentMetaData13@ IsNot Nothing Then 


If Row.ErrorColumn = @ Then 
" @ means no specific column is identified by ErrorColumn, this time. 
Row.ColumnName = "Check the row for a violation of a foreign key constraint." 

ELSE If Row.ErrorColumn = -1 Then 


-1 means you are using Table Lock for a Memory Optimised destination table which is not 


supported. 
Row.ColumnName = "Table lock is not compatible with Memory Optimised tables." 
Else 
Row.ColumnName = componentMetaData130.GetIdentificationStringByID(Row.ErrorColumn) 
End If 
End If 
End Sub 


End Class 


public class ScriptMain: // C# 


UserComponent 
ib 
public override void Input@_ProcessInputRow(Input@Buffer Row) 
{ 
Row.ErrorDescription = this.ComponentMetaData.GetErrorDescription(Row.ErrorCode) ; 
var componentMetaData13@ = this.ComponentMetaData as IDTSComponentMetaData130; 
if (componentMetaData130 != null) 
{ 
// ® means no specific column is identified by ErrorColumn, this time. 
if (Row.ErrorColumn == @) 
{ 
Row.ColumnName = "Check the row for a violation of a foreign key constraint."; 
t 
// -1 means you are using Table Lock for a Memory Optimised destination table which is not 
supported. 
else if (Row.ErrorColumn == -1) 
{ 
Row.ColumnName = "Table lock is not compatible with Memory Optimised tables."; 
t 
else 
it 
Row.ColumnName = componentMetaData130.GetIdentificationStringByID(Row.ErrorColumn) ; 
t 
i 
} 
t 


See Also 


Error Handling in Data 
Using Error Outputs in a Data Flow Component 
Creating a Synchronous Transformation with the Script Component 


Parsing Non-Standard Text File Formats with the 


Script Component 
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When your source data is arranged in a non-standard format, you may find it more convenient to consolidate all 
your parsing logic in a single script than to chain together multiple Integration Services transformations to 
achieve the same result. 


Example 1: Parsing Row-Delimited Records 


Example 2: Splitting Parent and Child Records 


NOTE 


If you want to create a component that you can more easily reuse across multiple Data Flow tasks and multiple packages, 
consider using the code in this Script component sample as the starting point for a custom data flow component. For 
more information, see Developing a Custom Data Flow Component. 











Example 1: Parsing Row-Delimited Records 


This example shows how to take a text file in which each column of data appears on a separate line and parse it 
into a destination table by using the Script component. 


For more information about how to configure the Script component for use as a transformation in the data flow, 
see Creating a Synchronous Transformation with the Script Component and Creating an Asynchronous 
Transformation with the Script Component. 


To configure this Script Component example 


1. Create and save a text file named rowdelimiteddata.txt that contains the following source data: 


FirstName: Nancy 

LastName: Davolio 

Title: Sales Representative 
City: Seattle 
StateProvince: WA 


FirstName: Andrew 

LastName: Fuller 

Title: Vice President, Sales 
City: Tacoma 

StateProvince: WA 


FirstName: Steven 
LastName: Buchanan 
Title: Sales Manager 
City: London 
StateProvince: 


2. Open Management Studio and connect to an instance of SQL Server. 


3. Select a destination database, and open a new query window. In the query window, execute the following 


10. 


11. 


12. 


13; 


14. 


1S: 


script to create the destination table: 


create table RowDelimitedData 
( 

FirstName varchar(32), 
LastName varchar(32), 

Title varchar(32), 

City varchar(32), 
StateProvince varchar (32) 


} 


. Open SQL Server Data Tools and create a new Integration Services package named ParseRowDelim.dtsx. 


. Add a Flat File connection manager to the package, name it RowDelimitedData, and configure it to 


connect to the rowdelimiteddata.txt file that you created in a previous step. 


. Add an OLE DB connection manager to the package and configure it to connect to the instance of SQL 


Server and the database in which you created the destination table. 


. Add a Data Flow task to the package and click the Data Flow tab of SSIS Designer. 


. Add a Flat File Source to the data flow and configure it to use the RowDelimitedData connection manager. 


On the Columns page of the Flat File Source Editor, select the single available external column. 


. Add a Script Component to the data flow and configure it as a transformation. Connect the output of the 


Flat File Source to the Script Component. 
Double-click the Script component to display the Script Transformation Editor. 


On the Input Columns page of the Script Transformation Editor, select the single available input 


column. 


On the Inputs and Outputs page of the Script Transformation Editor, select Output 0 and set its 
SynchronousInputID to None. Create 5 output columns, all of type string [DT_STR] with a length of 32: 


e FirstName 

e LastName 

e Title 

e City 

e StateProvince 


On the Script page of the Script Transformation Editor, click Edit Script and enter the code shown in 
the ScriptMain class of the example. Close the script development environment and the Script 
Transformation Editor. 


Add a SQL Server Destination to the data flow. Configure it to use the OLE DB connection manager and 
the RowDelimitedData table. Connect the output of the Script Component to this destination. 


Run the package. After the package has finished, examine the records in the SQL Server destination table. 


Public Overrides Sub Input@_ProcessInputRow(ByVal Row As Input@Buffer) 


Dim columnName As String 
Dim columnValue As String 
" Check for an empty row. 
If Row.Column@.Trim.Length > @ Then 
columnName = Row.Column@.Substring(@, Row.Column@.IndexOf(":")) 
" Check for an empty value after the colon. 
If Row.Column@.Substring(Row.Column@.IndexOf(":")).TrimEnd.Length > 1 Then 
" Extract the column value from after the colon and space. 
columnValue = Row.Column@.Substring(Row.Column@.IndexOf(":") + 2) 
Select Case columnName 
Case "FirstName" 
" The FirstName value indicates a new record. 
Me.Output@Buffer .AddRow() 
Me.Output@Buffer. FirstName = columnValue 
Case "LastName" 


Me.Output@Buffer.LastName = columnValue 


Case "Title" 
Me.Output@Buffer.Title = columnValue 
Case "City" 


Me.Output@Buffer.City = columnValue 
Case "StateProvince" 
Me.Output@Buffer.StateProvince = columnValue 
End Select 
End If 
End If 


End Sub 


public override void Input@_ProcessInputRow(Input@Buffer Row) 


{ 
string columnName; 
string columnValue; 
// Check for an empty row. 
if (Row.Column@.Trim().Length > @) 
{ 
columnName = Row.Column@.Substring(@, Row.Column@.IndexOf(":")); 
// Check for an empty value after the colon. 
if (Row.Column@.Substring(Row.Column®@.IndexOf(":")).TrimEnd().Length > 1) 
// Extract the column value from after the colon and space. 
{ 
columnValue = Row.Column@.Substring(Row.Column®@.IndexOf(":") + 2); 
switch (columnName) 
{ 
case "FirstName": 
// The FirstName value indicates a new record. 
this .Output@Buffer .AddRow() ; 
this.Output@Buffer.FirstName = columnValue; 
break; 
case "LastName": 
this .Output@Buffer.LastName = columnValue; 
break; 
case "Title": 
this.Output@Buffer.Title = columnValue; 
break; 
case "City": 
this.Output@Buffer.City = columnValue; 
break; 
case "StateProvince"™: 
this .Output@Buffer.StateProvince = columnValue; 
break; 
t 
t 
i 
t 


Example 2: Splitting Parent and Child Records 


This example shows how to take a text file, in which a separator row precedes a parent record row that is 
followed by an indefinite number of child record rows, and parse it into properly normalized parent and child 
destination tables by using the Script component. This simple example could easily be adapted for source files 
that use more than one row or column for each parent and child record, as long as there is some way to identify 
the beginning and end of each record. 

Caution 

This sample is intended for demonstration purposes only. If you run the sample more than once, it inserts 


duplicate key values into the destination table. 


For more information about how to configure the Script component for use as a transformation in the data flow, 
see Creating a Synchronous Transformation with the Script Component and Creating an Asynchronous 


Transformation with the Script Component. 


To configure this Script Component example 


1. Create and save a text file named parentchilddata.txt that contains the following source data: 


2. 


3: 


10. 


All 


12. 


FRR OR OK OK OK OK OK KK 


PARENT 1 DATA 
child 1 data 
child 2 data 
child 3 data 
child 4 data 
2K KOK KK OK KOK KK 
PARENT 2 DATA 
child 5 data 
child 6 data 
child 7 data 
child 8 data 


FRR OR OK OK OK OK OK KK 


Open SQL Server Management Studio and connect to an instance of SQL Server. 


Select a destination database, and open a new query window. In the query window, execute the following 


script to create the destination tables: 


CREATE TABLE [dbo].[Parents]([ParentID] [int] NOT NULL, 
[ParentRecord] [varchar](32) NOT NULL, 

CONSTRAINT [PK_Parents] PRIMARY KEY CLUSTERED 
([ParentID] ASC)) 
GO 
CREATE TABLE [dbo].[Children]([ChildID] [int] NOT NULL, 
[ParentID] [int] NOT NULL, 

[ChildRecord] [varchar](32) NOT NULL, 

CONSTRAINT [PK_Children] PRIMARY KEY CLUSTERED 
({ChildID] ASC)) 

GO 
ALTER TABLE [dbo].[Children] ADD CONSTRAINT [FK_Children_ Parents] FOREIGN KEY([ParentID]) 
REFERENCES [dbo].[Parents] ([ParentID]) 


. Open SQL Server Data Tools (SSDT) and create a new Integration Services package named 


SplitParentChild.dtsx. 


. Add a Flat File connection manager to the package, name it ParentChildData, and configure it to connect 


to the parentchilddata.txt file that you created in a previous step. 


. Add an OLE DB connection manager to the package and configure it to connect to the instance of SQL 


Server and the database in which you created the destination tables. 


. Add a Data Flow task to the package and click the Data Flow tab of SSIS Designer. 


. Add a Flat File Source to the data flow and configure it to use the ParentChildData connection manager. 


On the Columns page of the Flat File Source Editor, select the single available external column. 


. Add a Script Component to the data flow and configure it as a transformation. Connect the output of the 


Flat File Source to the Script Component. 
Double-click the Script component to display the Script Transformation Editor. 


On the Input Columns page of the Script Transformation Editor, select the single available input 


column. 


On the Inputs and Outputs page of the Script Transformation Editor, select Output 0, rename it to 
ParentRecords, and set its SynchronousInputID to None. Create 2 output columns: 


e ParentID (the primary key), of type four-byte signed integer [DT_I4] 


13. 


14. 


15. 


16. 


ee 


e ParentRecord, of type string [DT_STR] with a length of 32. 


Create a second output and name it ChildRecords. The SynchronousInputID of the new output is 
already set to None. Create 3 output columns: 


e ChildID (the primary key), of type four-byte signed integer [DT_I4] 
e ParentliD (the foreign key), also of type four-byte signed integer [DT_I4] 
e ChildRecord, of type string [DT_STR] with a length of 50 


On the Script page of the Script Transformation Editor, click Edit Script. In the ScriptMain class, 
enter the code shown in the example. Close the script development environment and the Script 
Transformation Editor. 


Add a SQL Server Destination to the data flow. Connect the ParentRecords output of the Script 
Component to this destination.Configure it to use the OLE DB connection manager and the Parents table. 


Add another SQL Server Destination to the data flow. Connect the ChildRecords output of the Script 
Component to this destination. Configure it to use the OLE DB connection manager and the Children 
table. 


Run the package. After the package has finished, examine the parent and child records in the two SQL 


Server destination tables. 


Public Overrides Sub Input@_ProcessInputRow(ByVal Row As Input@Buffer) 


Static nextRowIsParent As Boolean = False 
Static parentCounter As Integer = 0 
Static childCounter As Integer = @ 


" If current row starts with separator characters, 
then following row contains new parent record. 
If Row.Column@.StartsWith("***") Then 
nextRowIsParent = True 
Else 
If nextRowIsParent Then 
" Current row contains parent record. 
parentCounter += 1 
Me.ParentRecordsBuffer .AddRow() 
Me.ParentRecordsBuffer.ParentID = parentCounter 
Me.ParentRecordsBuffer.ParentRecord = Row.Column@ 
nextRowIsParent = False 
Else 
" Current row contains child record. 
childCounter += 1 
Me.ChildRecordsBuffer .AddRow( ) 
Me.ChildRecordsBuffer.ChildID = childCounter 
Me.ChildRecordsBuffer.ParentID = parentCounter 
Me.ChildRecordsBuffer.ChildRecord = Row.Column@ 
End If 
End If 


End Sub 


public override void Input@_ProcessInputRow(Input@Buffer Row) 


{ 


int static_Input@_ProcessInputRow_childCounter = 0; 
int static_Input@_ProcessInputRow_parentCounter = Q; 
bool static_Input@_ProcessInputRow_nextRowIsParent = false; 


// If current row starts with separator characters, 
// then following row contains new parent record. 
if (Row.Column@.StartswWith("***")) 


{ 
static_Input@_ProcessInputRow_nextRowIsParent = true; 
i 
else 
{ 
if (static_Input@_ProcessInputRow_nextRowIsParent ) 
{ 
// Current row contains parent record. 
static_Input@®_ProcessInputRow_parentCounter += 1; 
this.ParentRecordsBuffer.AddRow() ; 
this.ParentRecordsBuffer.ParentID = static_Input@_ProcessInputRow_parentCounter; 
this.ParentRecordsBuffer.ParentRecord = Row.Column@; 
static_Input@®_ProcessInputRow_nextRowIsParent = false; 
t 
else 
{ 
// Current row contains child record. 
static_Input@_ProcessInputRow_childCounter += 1; 
this.ChildRecordsBuffer .AddRow() ; 
this.ChildRecordsBuffer.ChildID = static_Input@_ProcessInputRow_childCounter; 
this.ChildRecordsBuffer.ParentID = static_Input@_ProcessInputRow_parentCounter; 
this.ChildRecordsBuffer.ChildRecord = Row.Column@; 
t 
} 


See Also 


Creating a Synchronous Transformation with the Script Component 
Creating an Asynchronous Transformation with the Script Component 


Simulating an Error Output for the Script 


Component 
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Although you cannot directly configure an output as an error output in the Script component for automatic 
handling of error rows, you can reproduce the functionality of a built-in error output by creating an additional 
output and using conditional logic in your script to direct rows to this output when appropriate. You may want 
to imitate the behavior of a built-in error output by adding two additional output columns to receive the error 
number and the ID of the column in which an error occurred. 


If you want to add the error description that corresponds to a specific predefined Integration Services error 
code, you can use the GetErrorDescription method of the |IDTSComponentMetaData100 interface, available 
through the Script component's ComponentMetaData property. 


Example 


The example shown here uses a Script component configured as a transformation that has two synchronous 
outputs. The purpose of the Script component is to filter error rows from address data in the AdventureWorks 
sample database. This fictitious example assumes that we are preparing a promotion for North American 
customers and need to filter out addresses that are not located in North America. 


To configure the example 

1. Before creating the new Script component, create a connection manager and configure a data flow source 
that selects address data from the AdventureWorks sample database. For this example, which only looks 
at the CountryRegionName column, you can simply use the Person.vStateCountryProvinceRegion view, 
or you can select data by joining the Person.Address, Person.StateProvince, and Person.CountryRegion 
tables. 


2. Add a new Script component to the Data Flow designer surface and configure it as a transformation. 
Open the Script Transformation Editor. 


3. On the Script page, set the ScriptLanguage property to the script language that you want to use to 
code the script. 


4. Click Edit Script to open Microsoft Visual Studio Tools for Applications (VSTA). 
5. In the InputO_ProcessInputRow method, type or paste the sample code shown below. 
6. Close VSTA. 


7. On the Input Columns page, select the columns that you want to process in the Script transformation. 
This example uses only the CountryRegionName column. Available input columns that you leave 
unselected will simply be passed through unchanged in the data flow. 


8. On the Inputs and Outputs page, add a new, second output, and set its SynchronousInputID value to 
the ID of the input, which is also the value of the SynchronousInputID property of the default output. 
Set the ExclusionGroup property of both outputs to the same non-zero value (for example, 1) to 
indicate that each row will be directed to only one of the two outputs. Give the new error output a 
distinctive name, such as "MyErrorOutput." 


9. Add additional output columns to the new error output to capture the desired error information, which 


10. 


ule 


12. 


may include the error code, the ID of the column in which the error occurred, and possibly the error 
description. This example creates the new columns, ErrorColumn and ErrorMessage. If you are catching 
predefined Integration Services errors in your own implementation, make sure to add an ErrorCode 
column for the error number. 


Note the ID value of the input column or columns that the Script component will check for error 
conditions. This example uses this column identifier to populate the ErrorColumn value. 


Close the Script Transformation Editor. 


Attach the outputs of the Script component to suitable destinations. Flat file destinations are the easiest to 
configure for ad hoc testing. 


13. Run the package. 
Public Overrides Sub Input@_ProcessInputRow(ByVal Row As Input@Buffer) 
If Row.CountryRegionName <> "Canada" _ 

And Row.CountryRegionName <> "United States" Then 
Row.ErrorColumn = 68 ' ID of CountryRegionName column 
Row.ErrorMessage = "Address is not in North America." 
Row. DirectRowToMyErrorOutput ( ) 

Else 
Row. DirectRowToOutput@() 
End If 
End Sub 
public override void Input@_ProcessInputRow(Input@Buffer Row) 
{ 
if (Row. CountryRegionName! ="Canada"&&Row.CountryRegionName!="United States") 
ul 
Row.ErrorColumn = 68; // ID of CountryRegionName column 
Row.ErrorMessage = "Address is not in North America."; 
Row. DirectRowToMyErrorOutput ( ) ; 
} 
else 
{ 
Row. DirectRowToOutput@() ; 
t 
i 


Error Handling in Data 


Using Error Outputs in a Data Flow Component 


Creating a Synchronous Transformation with the Script Component 


Extending Packages with Custom Objects 
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If you find that the components provided in Integration Services do not meet your requirements, you can extend 
the power of Integration Services by coding your own extensions. You have two discrete options for extending 
your packages: you can write code within the powerful wrappers provided by the Script task and the Script 
component, or you can create custom Integration Services extensions from scratch by deriving from the base 
classes provided by the Integration Services object model. 


This section explores the more advanced of the two options - extending packages with custom objects. 


When your custom Integration Services solution requires more flexibility than the Script task and the Script 
component provide, or when you need a component that you can reuse in multiple packages, the Integration 
Services object model lets you build custom tasks, data flow components, and other package objects in 
managed code from the ground up. 


In This Section 


Developing Custom Objects for Integration Services 
Discusses the custom objects that can be created for Integration Services, and summarizes the essential steps 
and settings. 


Persisting Custom Objects 
Discusses the default persistence of custom objects, and the process of implementing custom persistence. 


Building, Deploying, and Debugging Custom Objects 
Discusses the common approaches to building, deploying and testing the various types of custom objects. 


Developing a Custom Task 


Describes the process of coding a custom task. 


Developing a Custom Connection Manager 
Describes the process of coding a custom connection manager. 


Developing a Custom Log Provider 


Describes the process of coding a custom log provider. 


Developing a Custom ForEach Enumerator 


Describes the process of coding a custom enumerator. 
Developing a Custom Data Flow Component 


Discusses how to program custom data flow sources, transformations, and destinations. 


Reference 


Integration Services Error and Message Reference 


Lists the predefined Integration Services error codes with their symbolic names and descriptions. 


Related Sections 


Extending Packages with Scripting 


Discusses how to extend the control flow by using the Script task, or extend the data flow by using the Script 


component. 


Building Packages Programmatically 
Describes how to create, configure, run, load, save, and manage Integration Services packages 
programmatically. 


See Also 


Comparing Scripting Solutions and Custom Objects 
SQL Server Integration Services 


Developing Custom Objects for Integration Services 


11/23/2021 * 4 minutes to read « Edit Online 





Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


When the control flow and data flow objects that are included with SQL Server Integration Services do not 
completely meet your requirements, you can develop many types of custom objects on your own including: 


e Custom tasks. 
e Custom connection managers. Connect to external data sources that are not currently supported. 
e Custom log providers. Log package events in formats that are not currently supported. 


e Custom enumerators. Support iteration over a set of objects or values formats that are not currently 
supported. 


e Custom data flow components. Can be configured as sources, transformations, or destinations. 


The Integration Services object model facilitates this custom development with base classes that provide a 
consistent and reliable framework for your custom implementation. 


If you do not have to reuse custom functionality across multiple packages, the Script task and the Script 
component give you the full power of a managed programming language with significantly less infrastructure 
code to write. For more information, see Comparing Scripting Solutions and Custom Objects. 


Steps in Developing a Custom Object for Integration Services 


When you develop a custom object for use in Integration Services, you develop a Class Library (a DLL) that will 
be loaded at design time and run time by SSIS Designer and by the Integration Services runtime. The most 
important methods that you must implement are not methods that you call from your own code, but methods 
that the runtime calls at appropriate times to initialize and validate your component and to invoke its 
functionality. 


Here are the steps that you follow in developing a custom object: 

1. Create a new project of type Class Library in your preferred managed programming language. 
2. Inherit from the appropriate base class, as shown in the following table. 

3. Apply the appropriate attribute to your new class, as shown in the following table. 


4. Override the methods of the base class as required and write code for the custom functionality of your 
object. 


5. Optionally, build a custom user interface for your component. For ease of deployment, you may want to 
develop the user interface as a separate project within the same solution, and to build it as a separate 
assembly. 


6. Optionally, display a link to samples and Help content for the custom object, in the SSIS Toolbox. 


7. Build, deploy, and debug your new custom object as described in Building, Deploying, and Debugging 
Custom Objects. 


Base Classes, Attributes, and Important Methods 


This table provides an easy reference to the most important elements in the Integration Services object model 


for each type of custom object that you can develop. 


CUSTOM OBJECT 


Task 


Connection manager 


Log provider 


Enumerator 


Data flow component 


BASE CLASS 


Task 


ConnectionManagerBase 


LogProviderBase 


ForEachEnumerator 


PipelineComponent 


ATTRIBUTE 


DtsTaskAttribute 


DtsConnectionAttribute 


DtsLogProviderAttribute 


DtsForEachEnumeratorAttri 
bute 


DtsPipelineComponentAttri 
bute 


Providing Links to Samples and Help Content 


IMPORTANT METHODS 


Execute 


AcquireConnection, 
ReleaseConnection 


OpenLog, Log, CloseLog 


GetEnumerator 


ProvideComponentProperti 
es, PrimeOutput, 
ProcessInput 


To display a link in the SSIS Toolbox to samples and Help content for a custom object written in managed code, 


use the following properties. 


e Microsoft.SqlServer.Dts.Pipeline.DTSPipelineComponentAttribute.SamplesTag* 


Microsoft.SqlServer.Dts.Pipeline.DTSPipelineComponentAttribute.HelpCollection* 


Microsoft.SqlServer.Dts.Pipeline.DTSPipelineComponentAttribute.HelpKeyword* 


Microsoft.SqlServer.Dts.Runtime.DTS TaskAttribute.SamplesTag* 


Microsoft.SqlServer.Dts.Runtime.DTS TaskAttribute.HelpCollection* 


Microsoft.SqlServer.Dts.Runtime.DTS TaskAttribute.HelpKeyword* 


To display a link to samples and Help content for a custom object written in native code, add entries in the 


Registry Script (.rgs) file for SamplesTag, HelpKeyword, and HelpCollection. The following is an example. 


val HelpKeyword = s 'sqli1.dts.designer.executepackagetask.F1' 


val SamplesTag = s ‘ExecutePackageTask’' 


Providing a Custom User Interface 


To allow users of your custom object to configure its properties, you may have to develop a custom user 


interface also. In those cases where a custom user interface is not strictly required, you may choose to create 


one to provide a more user-friendly interface than the default editor. 


In a custom user interface project or assembly, you generally have two classes -a class that implements an 


Integration Services interface for user interfaces for the specific type of custom object, and the Windows form 


that it displays to gather information from the user. The interfaces that you implement have only a few methods, 


and a custom user interface is not difficult to develop. 





NOTE 





UlTypeName property of the DtsLogProviderAttribute has no effect. 


Many Integration Services log providers have a custom user interface that implements |DtsLogProviderUI and replaces 
the Configuration text box with a filtered drop-down list of available connection managers. However custom user 
interfaces for custom log providers are not implemented in this release of Integration Services. Specifying a value for the 





The following table provides an easy reference to the interfaces that you must implement when you develop a 


custom user interface for each type of custom object. It also explains what the user sees if you choose not to 


develop a custom user interface for your object, or if you fail to link your object to its user interface by using the 


UITypeName property in the object's attribute. Although the powerful Advanced Editor may be satisfactory for 


a data flow component, the Properties window is a less user-friendly solution for tasks and connection 


managers, and a custom ForEach enumerator cannot be configured at all without a custom form. 


CUSTOM OBJECT 


Task 


Connection manager 


Log provider 


Enumerator 


Data flow component 


External Resources 


BASE CLASS FOR USER INTERFACE 


IDtsTaskUI 


IDtsConnectionManagerUI 


IDtsLogProviderUI 


(Not implemented in Integration 
Services) 


ForEachEnumeratorUI 


|IDtsComponentUI 


DEFAULT EDITING BEHAVIOR IF NO 
CUSTOM USER INTERFACE IS 
PROVIDED 


Properties window only 


Properties window only 


Text box in Configuration column 


Properties window only. Enumerator 
Configuration area of editor is empty. 


Advanced Editor 


e Blog entry, Visual Studio solution build process give a warning about indirect dependency on the .NET 


Framework assembly due to SSIS references, on blogs.msdn.com. 


See Also 


Persisting Custom Objects 


Building, Deploying, and Debugging Custom Objects 
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You do not need to implement custom persistence for the custom objects that you create as long as their 
properties use only simple data types such as integer and string. The default implementation of persistence 
saves the metadata for your object along with the values of all its properties. 


However, if your object has properties that use complex data types, or if you want to perform custom processing 
on property values as they are loaded and saved, you can implement the IDTSComponentPersist interface and 
its LoadFromXML and SaveToXML methods. In these methods you load from (or save to) the XML definition of 
the package an XML fragment that contains the properties of your object and their current values. The format of 
this XML fragment is not defined; it must only be well-formed XML. 


IMPORTANT 


When you implement custom persistence, you must persist all the properties of the object, including both inherited 


properties and custom properties that you have added. 





Example 


Although the Sql Server Custom Connection Manager Sample does not require custom persistence for its three 
properties of type string, the following code shows an example of the custom code that would be required to 
persist the connection manager and its properties. The class that contains this code must implement the 
IDTSComponentPersist interface. 


Private Const PERSIST_ELEMENT As String = "SqlConnectionManager” 
Private Const PERSIST_SERVER As String = "Server" 

Private Const PERSIST_DATABASE As String = "Database" 

Private Const PERSIST_CONNECTIONSTRING As String = "ConnectionString"” 


Public Sub LoadFromxXML(ByVal node As System.Xm1.XmlElement, _ 
ByVal infoEvents As Microsoft.SqlServer.Dts.Runtime.IDTSInfoEvents) _ 
Implements Microsoft.SqlServer.Dts.Runtime.IDTSComponentPersist.LoadFromXML 


Dim propertyNode As XmlNode 
" Make sure that the correct node is being loaded. 
If node.Name <> PERSIST ELEMENT Then 
Throw New Exception("Persisted element is not of type " & PERSIST_ELEMENT) 
End If 
" Load the three properties of the object from XML into variables. 
For Each propertyNode In node.ChildNodes 
Select Case propertyNode.Name 
Case PERSIST_SERVER 
_serverName = propertyNode. InnerText 
Case PERSIST_DATABASE 
_databaseName = propertyNode.InnerText 
Case PERSIST_CONNECTIONSTRING 
_connectionString = propertyNode.InnerText 
End Select 
Next 


End Sub 


Public Sub SaveToXML(ByVal doc As System.Xml.XmlDocument, _ 
ByVal infoEvents As Microsoft.SqlServer.Dts.Runtime.IDTSInfoEvents) _ 
Implements Microsoft.SqlServer.Dts.Runtime.IDTSComponentPersist.SaveToXML 


Dim elementRoot As XmlElement 
Dim propertyNode As XmlNode 

" Create a new node to persist the object and its properties. 

elementRoot = doc.CreateElement(String.Empty, PERSIST_ELEMENT, String.Empty) 
" Save the three properties of the object from variables into XML. 

propertyNode = doc.CreateNode(XmlNodeType.Element, PERSIST_SERVER, String.Empty) 
propertyNode.InnerText = _serverName 

elementRoot .AppendChild(propertyNode) 


propertyNode = doc.CreateNode(XmlNodeType.Element, PERSIST_DATABASE, String.Empty) 
propertyNode.InnerText = _databaseName 

elementRoot .AppendChild(propertyNode) 

propertyNode = doc.CreateNode(XmlNodeType.Element, PERSIST_CONNECTIONSTRING, String.Empty) 
propertyNode.InnerText = _connectionString 

elementRoot .AppendChild(propertyNode) 


doc.AppendChild(elementRoot ) 


End Sub 


private const string PERSIST_ELEMENT = "SqlConnectionManager" ; 


private const string PERSIST_SERVER = "Server"; 
private const string PERSIST_DATABASE = "Database"; 


private const string PERSIST_CONNECTIONSTRING = "ConnectionString"; 


public void LoadFromxXML(System.Xm1.XmlElement node, 


Microsoft.SqlServer.Dts.Runtime.IDTSInfoEvents infoEvents) 


// Make sure that the correct node is being loaded. 


if (node.Name != PERSIST_ELEMENT) 
{ 


throw new Exception("Persisted element is not of type " + PERSIST_ELEMENT) ; 


// Save the three properties of the object from variables into XML. 


foreach (XmlNode propertyNode in node.ChildNodes) 


{ 
switch (propertyNode.Name) 


{ 
case PERSIST_SERVER: 


_serverName = propertyNode.InnerText; 


break; 
case PERSIST_DATABASE: 


_databaseName = propertyNode. InnerText; 


break; 
case PERSIST_CONNECTIONSTRING: 


_connectionString = propertyNode. InnerText}; 


break; 


public void SaveToXML(System.Xm1.XmlDocument doc, 


Microsoft.SqlServer.Dts.Runtime.IDTSInfoEvents infoEvents) 


XmlElement elementRoot; 
Xm1Node propertyNode; 


// Create a new node to persist the object and its properties. 
elementRoot = doc.CreateElement(String.Empty, PERSIST_ELEMENT, String.Empty) ; 


// Save the three properties of the object from variables into XML. 
propertyNode = doc.CreateNode(XmlNodeType.Element, PERSIST_SERVER, String.Empty) ; 


propertyNode.InnerText = _serverName; 
elementRoot .AppendChild(propertyNode) ; 


propertyNode = doc.CreateNode(XmlNodeType.Element, PERSIST DATABASE, String.Empty) ; 


propertyNode.InnerText = _databaseName; 
elementRoot .AppendChild(propertyNode) ; 


propertyNode = doc.CreateNode(XmlNodeType.Element, 
propertyNode.InnerText = _connectionString; 


elementRoot .AppendChild(propertyNode) ; 


doc.AppendChild(elementRoot) ; 


See Also 


Developing Custom Objects for Integration Services 
Building, Deploying, and Debugging Custom Objects 


PERSIST_CONNECTIONSTRING, String.Empty) ; 


Building, Deploying, and Debugging Custom 
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After you have written the code for a custom object for Integration Services, you must build the assembly, 
deploy it, and integrate it into SSIS Designer to make it available for use in packages, and test and debug it. 


Steps in Building, Deploying, and Debugging a Custom Object for 
Integration Services 


You have already written the custom functionality for your object. Now you have to test it and to make it 
available to users. The steps are very similar for all the types of custom objects that you can create for 
Integration Services. 


Here are the steps to build, deploy, and test it. 
1. Sign the assembly to be generated with a strong name. 
2. Build the assembly. 
3. Deploy the assembly by moving or copying it to the appropriate Integration Services folder. 
4. Install the assembly in the global assembly cache (GAC). 
The object is automatically added to the Toolbox. 
5. Troubleshoot the deployment, if necessary. 


6. Test and debug your code. 


You can now use SSIS Designer in SQL Server Data Tools (SSDT) to create, maintain, and run packages that 
target different versions of SQL Server. For more info about the impact of this improvement on your custom 
extensions, see Getting your SSIS custom extensions to be supported by the multi-version support of SSDT 
2015 for SQL Server 2016 


Signing the Assembly 


When an assembly is meant to be shared, it must be installed in the global assembly cache. After the assembly 
has been added to the global assembly cache, the assembly can be used by applications such as SQL Server 
Data Tools (SSDT). A requirement of the global assembly cache is that the assembly must be signed with a 
strong name, which guarantees that an assembly is globally unique. A strong-named assembly has a fully 
qualified name that includes the name, culture, public key, and version number of the assembly. The runtime 
uses this information to locate the assembly and to differentiate it from other assemblies with the same name. 


To sign an assembly with a strong name, you must first have or create a public/private key pair. This public and 
private cryptographic key pair is used at build time to create a strong-named assembly. 


For more information about strong names and on the steps that you must followto sign an assembly, see the 
following topics in the .NET Framework SDK documentation: 


e@ Strong-Named Assemblies 


e Creating a Key Pair 
e Signing an Assembly with a Strong Name 


You can easily sign your assembly with a strong name in Visual Studio at build time. In the Project Properties 
dialog box, select the Signing tab. Select the option to Sign the assembly and then provide the path of the 
key (.snk) file. 


Building the Assembly 


After signing the project, you must build or rebuild the project or the solution by using the commands available 
on the Build menu of SQL Server Data Tools. Your solution may contain a separate project for a custom user 
interface, which must also be signed with a strong name, and can be built at the same time. 


The most convenient method for performing the next two steps-deploying the assembly and installing it in the 
global assembly cache-is to script these steps as a post-build event in Visual Studio. Build events are available 
from the Compile page of Project Properties for a Visual Basic project, and from the Build Events page for a 
C# project. The full path is required for command prompt utilities such as gacutil.exe. Quotation marks are 
required both around paths that contain spaces and around macros such as $(TargetPath) that expand to paths 


that contain spaces. 


Here is an example of a post-build event command line for a custom log provider: 


"C:\Program Files (x86)\Microsoft SDKs\Windows\v7.@A\bin\NETFX 4.0 Tools\gacutil.exe" -u $(TargetName) 
"C:\Program Files (x86)\Microsoft SDKs\Windows\v7.@A\bin\NETFX 4.0 Tools\gacutil.exe" -i $(TargetFileName) 
copy $(TargetFileName) “C:\Program Files\Microsoft SQL Server\130\DTS\LogProviders " 


Deploying the Assembly 


The SSIS Designer locates the custom objects available for use in packages by enumerating the files found ina 
series of folders that are created when SQL Server Integration Services is installed. When the default SQL Server 
installation settings are used, this set of folders is located under C:\Program Files\Microsoft SQL 
Server\130\DTS. However if you create a setup program for your custom object, you should check the value 
of the HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Microsoft SQL 
Server\130\SSIS\Setup\DtsPath registry key to verify the location of this folder. 


NOTE 

For info about how to deploy custom components to work well with the multi-version support in SQL Server Data Tools, 
see Getting your SSIS custom extensions to be supported by the multi-version support of SSDT 2015 for SQL Server 
2016. 











You can put the assembly in the folder in two ways: 


e Move or copy the compiled assembly to the appropriate folder after building it. (For convenience, you can 


include the copy command in a Post-build Event.) 
e Build the assembly directly in the appropriate folder. 


The following deployment folders under C:\Program Files\Microsoft SQL Server\130\DTS are used for 
the various types of custom objects: 


CUSTOM OBJECT DEPLOYMENT FOLDER 





Task Tasks 

Connection manager Connections 

Log provider LogProviders 

Data flow component PipelineComponents 
NOTE 


Assemblies are copied to these folders to support the enumeration of available tasks, connection managers, and so on. 
Therefore you do not have to deploy assemblies that contain only the custom user interface for custom objects to these 


folders. 











Installing the Assembly in the Global Assembly Cache 


To install the task assembly into the global assembly cache (GAC), use the command line tool gacutil.exe, or 
drag the assemblies to the %system%\assembly directory. For convenience, you can also include the call to 
gacutil.exe in a Post-build Event. 


The following command installs a component named My/7ask.d//into the GAC by using gacutil.exe. 
gacutil /iF MyTask.dll 


You must close and reopen SSIS Designer after you install a new version of your custom object. If you have 
installed earlier versions of your custom object in the global assembly cache, you must remove them before 
installing the new version. To uninstall an assembly, run gacutil.exe and specify the assembly name with the 
/u option. 


For more information about the global assembly cache, see Global Assembly Cache Tool (Gactutil.exe) in the 
.NET Framework Tools. 


Troubleshooting the Deployment 


If your custom object appears in the Toolbox or the list of available objects, but you are not able to add it toa 
package, try the following: 


1. Look in the global assembly cache for multiple versions of your component. If there are multiple versions 
of the component in the global assembly cache, the designer may not be able to load your component. 
Delete all instances of the assembly from the global assembly cache, and re-add the assembly. 


2. Make sure that only a single instance of the assembly exists in the deployment folder. 
3. Refresh the Toolbox. 


4. Attach Visual Studio to devenv.exe and set a breakpoint to step through your initialization code to 
ensure that no exceptions occur. 


Testing and Debugging Your Code 


The simplest approach to debugging the run-time methods of a custom object is to start dtexec.exe from 
Visual Studio after building your custom object and run a package that uses the component. 


If you want to debug the component's design-time methods, such as the Validate method, open a package that 


uses the component in a second instance of Visual Studio, and attach to its devenv.exe process. 


If you also want to debug the component's run-time methods when a package is open and running in SSIS 
designer, you must force a pause in the execution of the package so that you can also attach to the 
DtsDebugHost.exe process. 


To debug an object's run-time methods by attaching to dtexec.exe 
1. Sign and build your project in the Debug configuration, deploy it, and install it in the global assembly 
cache as described in this topic. 


2. On the Debug tab of Project Properties, select Start external program as the Start Action, and 
locate dtexec.exe, which is installed by default in C:\Program Files\Microsoft SQL Server\130\DTS\Binn. 


3. In the Command line options text box, under Start Options, enter the command line arguments 
required to run a package that uses your component. Often the command-line argument will consist of 
the /F[ILE] switch followed by the path and file name of the .dtsx file. For more information, see dtexec 
Utility. 


4. Set breakpoints in the source code where appropriate in the run-time methods of your component. 
5. Run your project. 


To debug a custom object's design-time methods by attaching to SQL Server Data Tools 
1. Sign and build your project in the Debug configuration, deploy it, and install it in the global assembly 
cache as described in this topic. 


2. Set breakpoints in the source code where appropriate in the design-time methods of your custom object. 


3. Open a second instance of Visual Studio and load an Integration Services project that contains a package 
that uses the custom object. 


4. From the first instance of Visual Studio, attach to the second instance of devenv.exe in which the 
package is loaded by selecting Attach to Process from the Debug menu of the first instance. 


5. Run the package from the second instance of Visual Studio. 


To debug a custom object's run-time methods by attaching to SQL Server Data Tools 

1. After you have completed the steps listed in the previous procedure, force a pause in the execution of 
your package so that you can attach to DtsDebugHost.exe. You can force this pause by adding a 
breakpoint to the OnPreExecute event, or by adding a Script task to your project and entering script that 
displays a modal message box. 


2. Run the package. When the pause occurs, switch to the instance of Visual Studio in which your code 
project is open, and select Attach to Process from the Debug menu. Make sure to attach to the 
instance of DtsDebugHost.exe listed as Managed, x86 in the Type column, not to the instance listed 
as x86 only. 


3. Return to the paused package and continue past the breakpoint, or click OK to dismiss the message box 
raised by the Script task, and continue package execution and debugging. 


See Also 


Developing Custom Objects for Integration Services 
Persisting Custom Objects 
Troubleshooting Tools for Package Development 
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You can now use SSIS Designer in SQL Server Data Tools (SSDT) to create, maintain, and run packages that 
target SQL Server 2016, SQL Server 2014, or SQL Server 2012. To get SSDT for Visual Studio 2015, see 
Download Latest SQL Server Data Tools. 


In Solution Explorer, right-click on an Integration Services project and select Properties to open the property 
pages for the project. On the General tab of Configuration Properties, select the TargetServerVersion 
property, and then choose SQL Server 2016, SQL Server 2014, or SQL Server 2012. 


Configuration: Active(Development) » Platform: N/A md Configuration Manager... 


4 Common Properties Vv De farget Version 
Project LE sion SQL Server 2017 

4 Configuration Properties ‘SQL Server 2012 
General ‘SQL Server 2014 
Build ‘SQL Server 2016 
Deployment SQL Server 2017 
Debugging 


TargetServerVersion 
Specifies the version that is used to save, deploy, execute and debug packages in ... 


OK Cancel Apply 





Multiple version support and multi-targeting for custom components 


All five types of SSIS custom extensions support multi-targeting. 


e Connection managers 
e Tasks 

e Enumerators 

e Log providers 


e Data flow components 


For managed extensions, SSIS Designer loads the version of the extension for the specified target version. For 


example: 


e When the target version is SQL Server 2012, the designer loads the 2012 version of the extension. 


e When the target version is SQL Server 2016, the designer loads the 2016 version of the extension. 


COM extensions do not support multi-targeting. SSIS Designer always loads the COM extension for the current 
version of SQL Server, regardless of the specified target version. 


Add basic support for multiple versions and multi-targeting 


For basic guidance, see Getting your SSIS custom extensions to be supported by the multi-version support of 
SSDT 2015 for SQL Server 2016. This blog post describes the following steps or requirements. 


e Deploy your assemblies to the appropriate folders. 


e Create an extension map file for SQL Server 2014 and high versions. 


Add code to switch versions 


Switch versions in a custom connection manager, task, enumerator, or log provider 


For a custom connection manager, task, enumerator, or log provider, add downgrade logic in the SaveToXML 
method. 


public void SaveToXML(Xm1Document doc, IDTSInfoEvents events) 


{ 
if (TargetServerVersion == DTSTargetServerVersion.SQLServer2014) 
if 
// Add logic to downgrade from SQL Server 2016 to SQL Server 2014. 
} 
if (TargetServerVersion == DTSTargetServerVersion.SQLServer2012) 
{ 
// Add logic to downgrade from SQL Server 2016 to SQL Server 2012. 
t 
t 


Switch versions in a custom data flow component 


For a custom connection manager, task, enumerator, or log provider, add downgrade logic in the new 
PerformDowngrade method. 


public override void PerformDowngrade(int pipelineVersion, DTSTargetServerVersion targetServerVersion) 


{ 
if (targetServerVersion == DTSTargetServerVersion.DTSTSV_SQLSERVER2014) 


{ 
// Add logic to downgrade from SQL Server 2016 to SQL Server 2014. 
ComponentMetaData.Version = 8; 
} 
if (targetServerVersion == DTSTargetServerVersion.DTSTSV_SQLSERVER2@12) 
{ 
// Add logic to downgrade from SQL Server 2016 to SQL Server 2012. 
ComponentMetaData.Version = 6; 
} 


Common errors 


InvalidCastException 


Error message. Unable to cast COM object of type 'System.__ComObject' to interface type 
‘Microsoft.SqlServer.Dts.Pipeline.Wrapper.|DTSComponentMetaData100'. This operation failed because the 
Querylnterface call on the COM component for the interface with IID '{BE8C48A3-155B-4810-BA5C- 
BDF68A659E9E}' failed due to the following error: No such interface supported (Exception from HRESULT: 
0x80004002 (E_NOINTERFACE)). (Microsoft.SqlServer.DTSPipelineWrap). 


Solution. If your custom extension references SSIS interop assemblies such as 
Microsoft.SqlServer.DTSPipelineWrap or Microsoft.SqlServer.DTSRuntimeWrap, set the value of the Embed 
Interop Types property to False. 


Properties yx 
Microsoft.SqlServer.DTSRuntimeWrap Reference Properties ’ 





Microsoft.SqlServer.DTSRuntimeWrap 


Aliases global 

Copy Local False 

Culture 

Description 

Embed Interop Types False ina 
File Type Assembly 


Unable to load some types when target version is SQL Server 2012 


This issue affects certain types such as |ErrorReportingService or IUserPromptService. 


Error message (example). Could not load type 'Microsoft.DataWarehouse.Design.lErrorReportingSer vice’ 
from assembly 'Microsoft.DataWarehouse, Version=13.0.0.0, Culture=neutral, 
PublicKeyToken=89845dcd8080cc91'. 


Workaround. Use a MessageBox instead of these interfaces when the target version is SQL Server 2012. 
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Integration Services uses tasks to perform units of work in support of the extraction, transformation, and 
loading of data. Integration Services includes a variety of tasks that perform the most frequently used actions, 
from executing an SQL statement to downloading a file from an FTP site. If the included tasks and supported 
actions do not completely meet your requirements, you can create a custom task. 


To create a custom task, you have to create a class that inherits from the Microsoft.SqlServer.Dts.Runtime. Task 
base class, apply the DtsTaskAttribute attribute to your new class, and override the important methods and 
properties of the base class, including the Execute method. 


In This Section 
This section describes how to create, configure, and code a custom task and its optional custom user interface. 


Creating a Custom Task 


Describes the first step, which is creating the custom task. 


Coding a Custom Task 
Describes how to code the principal methods of a custom task. 


Connecting to Data Sources in a Custom Task 


Describes how to connect a custom task to a data source. 


Raising and Defining Events in a Custom Task 


Describes how to raise events and define custom events from the custom task. 


Adding Support for Debugging in a Custom Task 
Describes how to create breakpoint targets in the custom task. 


Developing a User Interface for a Custom Task 


Describes how to create a user interface that shows in SSIS Designer to configure properties on the custom task. 


Related Sections 


Information Common to all Custom Objects 
For information that is common to all the type of custom objects that you can create in Integration Services, see 


the following topics: 


Developing Custom Objects for Integration Services 


Describes the basic steps in implementing all kinds of custom objects for Integration Services. 


Persisting Custom Objects 
Describes custom persistence and explains when it is necessary. 


Building, Deploying, and Debugging Custom Objects 
Describes the techniques for building, signing, deploying, and debugging custom objects. 
Information about Other Custom Objects 


For information about the other types of custom objects that you can create in Integration Services, see the 
following topics: 


Developing a Custom Connection Manager 
Discusses how to program custom connection managers. 


Developing a Custom Log Provider 
Discusses how to program custom log providers. 


Developing a Custom ForEach Enumerator 
Discusses how to program custom enumerators. 


Developing a Custom Data Flow Component 
Discusses how to program custom data flow sources, transformations, and destinations. 


See Also 


Extending the Package with the Script Task 
Comparing Scripting Solutions and Custom Objects 
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The steps involved in creating a custom task are similar to the steps for creating any other custom object for 
Integration Services: 


e Create a new class that inherits from the base class. For a task, the base class is 
Microsoft.SqlServer.Dts.Runtime.Task. 


e Apply the attribute that identifies the type of object to the class. For a task, the attribute is 
DtsTaskAttribute. 


e Override the implementation of the base class's methods and properties. For a task, these include the 
Validate and Execute methods. 


@ Optionally, develop a custom user interface. For a task, this requires a class that implements the 
|DtsTaskUI interface. 


Getting Started with a Custom Task 


Creating Projects and Classes 


Because all managed tasks derive from the Microsoft.SqlServer.Dts.Runtime.Task base class, the first step when 
you create a custom task is to create a class library project in your preferred managed programming language 
and create a class that inherits from the base class. In this derived class you will override the methods and 
properties of the base class to implement your custom functionality. 


In the same solution, create a second class library project for the custom user interface. A separate assembly for 
the user interface is recommended for ease of deployment because it allows you to update and redeploy the 
connection manager or its user interface independently. 


Configure both projects to sign the assemblies that will be generated at build time by using a strong name key 
file. 


Applying the DtsTask Attribute 
Apply the DtsTaskAttribute attribute to the class that you have created to identify it as a task. This attribute 


provides design-time information such as the name, description, and task type of the task. 


Use the UlTypeName property to link the task to its custom user interface. To obtain the public key token that is 
required for this property, you an use sn.exe -t to display the public key token from the key pair (.snk) file that 
you intend to use to sign the user interface assembly. 


using System; 
using Microsoft.SqlServer.Dts.Runtime; 
namespace Microsoft.SSIS.Samples 
i 
[DtsTask 
( 
DisplayName = "MyTask", 
IconResource = "MyTask.MyTaskIcon.ico", 
UITypeName = "My Custom Task," + 
"Version=1.0.0.0," + 
"Culture = Neutral," + 
"PublickeyToken = 12345abc6789de01", 
TaskType = "PackageMaintenance", 
TaskContact = "MyTask; company name; any other information”, 
RequiredProductLevel = DTSProductLevel.None 
)] 
public class MyTask : Task 
{ 


// Your code here. 


Imports System 
Imports Microsoft.SqlServer.Dts.Runtime 


<DtsTask(DisplayName:="MyTask", _ 
IconResource:="MyTask.MyTaskIcon.ico", _ 

UITypeName:="My Custom Task," & _ 
"Version=1.0.0.0,Culture=Neutral," & _ 
"PublickKeyToken=12345abc6789de@1", _ 
TaskType:="PackageMaintenance", _ 

TaskContact:="MyTask; company name; any other information", 


RequiredProductLevel:=DTSProductLevel.None)> _ 
Public Class MyTask 
Inherits Task 


Your code here. 


End Class 'MyTask 


Building, Deploying, and Debugging a Custom Task 


The steps for building, deploying, and debugging a custom task in Integration Services are similar to the steps 
required for other types of custom objects. For more information, see Building, Deploying, and Debugging 
Custom Objects. 


See Also 


Creating a Custom Task 
Coding a Custom Task 
Developing a User Interface for a Custom Task 
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After you have created a class that inherits from the Microsoft.SqlServer.Dts.Runtime.Task base class, and 
applied the DtsTaskAttribute attribute to the class, you must override the implementation of the properties and 
methods of the base class to provide your custom functionality. 


Configuring the Task 


Validating the Task 


When you are designing an Integration Services package, you can use validation to verify settings on each task, 
so that you can catch incorrect or inappropriate settings as soon as they are set, instead of finding all errors at 
run-time only. The purpose of validation is to determine whether the task contains invalid settings or 
connections that will prevent it from running successfully. This makes sure that the package contains tasks that 
have a good chance of running on their first run. 


You can implement validation by using the Validate method in custom code. The run-time engine validates a 
task by calling the Validate method on the task. It is the responsibility of the task developer to define the 
criteria that give you a successful or failed task validation, and to notify the run-time engine of the result of this 
evaluation. 


Task Abstract Base Class 

The Microsoft.SqlServer.Dts.Runtime.Task abstract base class provides the Validate method that each task 
overrides to define its validation criteria. The SSIS Designer automatically calls the Validate method multiple 
times during package design, and provides visual cues to the user when warnings or errors occur to help 
identify problems with the configuration of the task. Tasks provide validation results by returning a value from 
the DTSExecResult enumeration, and by raising warning and error events. These events contain information that 
is displayed to the user in SSIS Designer. 


Some examples for validation follow: 

e Aconnection manager validates the specific file name. 

e Aconnection manager validates that the type of input is the expected type, such as an XML file. 

e A task that expects database input verifies that it cannot receive data from a non-database connection. 
e A task guarantees that none of its properties contradicts other properties set on the same task. 

e A task guarantees that all required resources used by the task at execution time are available. 


Performance is something to consider in determining what is validated and what is not. For example, the input 
to a task might be a connection over a network that has low bandwidth or heavy traffic. The validation may take 
several seconds to process if you decide to validate that the resource is available. Another validation may cause 
a round-trip to a server that is in high demand, and the validation routine might be slow. Although there are 
many properties and settings that can be validated, not everything should be validated. 


@ The code in the Validate method is also called by the TaskHost before the task is run, and the TaskHost 


cancels execution if validation fails. 


User Interface Considerations during Validation 


The Microsoft.SqlServer.Dts.Runtime.Task includes an IDTSComponentEvents interface as a parameter to the 


Validate method. The IDTSComponentEvents interface contains the methods that are called by the task in order 
to raise events to the run-time engine. The FireWarning and FireError methods are called when a warning or 
error condition occurs during validation. Both warning methods require the same parameters, which include an 
error code, source component, description, Help file, and Help context information. The SSIS Designer uses this 
information to display visual cues on the design surface. The visual cues that are provided by the designer 
include an exclamation icon that appears next to the task on the designer surface. This visual cue signals to the 
user that the task requires additional configuration before execution can continue. 


The exclamation icon also displays a ToolTip that contains an error message. The error message is provided by 
the task in the description parameter of the event. Error messages are also displayed in the Task List pane of 
SQL Server Data Tools (SSDT), providing the user with a central location for viewing all validation errors. 


Validation Example 

The following code example shows a task with a UserName property. This property has been specified as 
required for validation to succeed. If the property is not set, the task posts an error, and returns Failure from the 
DTSExecResult enumeration. The Validate method is wrapped in a try/catch block, and fails validation if an 
exception occurs. 


using System; 
using Microsoft.SqlServer.Dts.Runtime; 


public class SampleTask : Task 
{ 


private string userName = ""; 

public override DTSExecResult Validate(Connections connections, 
VariableDispenser variableDispenser, IDTSComponentEvents events, 
IDTSLogging log) 


try 
{ 
if (this.userName == "") 
< 
uy Raise an OnError event. 
events.FireError(@, "SampleTask", "The UserName property must be configured.", "", @); 
Hf Fail validation. 
return DTSExecResult.Failure; 
} 
// Return success. 
return DTSExecResult.Success; 
} 
catch (System.Exception exception) 
{ 
ee Capture exceptions, post an error, and fail validation. 
events.FireError(@, "Sampletask", exception.Message, "", @); 
return DTSExecResult.Failure; 


} 


public string UserName 


return this.userName; 


} 


set 


{ 


this.userName = value; 


Imports System 
Imports Microsoft.SqlServer.Dts.Runtime 


Public Class SampleTask 
Inherits Task 


Private _userName As String = 


Public Overrides Function Validate(ByVal connections As Connections, _ 
ByVal variableDispenser As VariableDispenser, _ 
ByVal events As IDTSComponentEvents, _ 
ByVal log As IDTSLogging) As DTSExecResult 


Try 

If Me._userName = "" Then 

: Raise an OnError event. 

events.FireError(@, "SampleTask", "The UserName property must be configured.", "", @) 
: Fail validation. 

Return DTSExecResult.Failure 
End If 
; Return success. 

Return DTSExecResult.Success 
Catch exception As System.Exception 

: Capture exceptions, post an error, and fail validation. 
events.FireError(@, "Sampletask", exception.Message, "", @) 
Return DTSExecResult.Failure 


End Try 
End Function 


Public Property UserName() As String 
Get 
Return Me._userName 
End Get 
Set(ByVal Value As String) 
Me._userName = Value 
End Set 
End Property 


End Class 


Persisting the Task 


Ordinarily you do not have to implement custom persistence for a task. Custom persistence is required only 
when the properties of an object use complex data types. For more information, see Developing Custom Objects 
for Integration Services. 


Executing the Task 


This section describes how to use the Execute method that is inherited and overridden by tasks. This section 
also explains various ways of providing information about the results of task execution. 


Execute Method 


Tasks that are contained in a package run when the Integration Services runtime calls their Execute method. 
Tasks implement their core business logic and functionality in this method, and provide the results of execution 
by posting messages, returning a value from the DTSExecResult enumeration, and overriding the property get 
of the ExecutionValue property. 


The Microsoft.SqlServer.Dts.Runtime.Task base class provides a default implementation of the Execute method. 
The custom tasks override this method to define their run-time functionality. The TaskHost object wraps the task, 
isolating it from the run-time engine and the other objects in the package. Because of this isolation, the task is 
unaware of its location in the package with regard to its execution order, and runs only when it is called by the 


runtime. This architecture prevents problems that can occur when tasks modify the package during execution. 
The task is provided access to the other objects in the package only through the objects supplied to it as 
parameters in the Execute method. These parameters let tasks raise events, write entries to the event log, access 
the variables collection, and enlist connections to data sources in transactions, while still maintaining the 
isolation that is necessary to guarantee the stability and reliability of the package. 


The following table lists the parameters provided to the task in the Execute method. 
PARAMETER DESCRIPTION 


Connections Contains a collection of ConnectionManager objects 
available to the task. 


VariableDispenser Contains the variables available to the task. The tasks use 
variables through the VariableDispenser; the tasks do not 
use variables directly. The variable dispenser locks and 
unlocks variables, and prevents deadlocks or overwrites. 


IDTSComponentEvents Contains the methods called by the task to raise events to 
the run-time engine. 


IDTSLogging Contains methods and properties used by the task to write 
entries to the event log. 


Object Contains the transaction object that the container is a part 
of if any. This value is passed as a parameter to the 
AcquireConnection method of a ConnectionManager object. 


Providing Execution Feedback 


Tasks wrap their code in try/catch blocks to prevent exceptions from being raised to the run-time engine. This 
ensures that the package finishes execution and does not stop unexpectedly. However, the run-time engine 
provides other mechanisms for handling error conditions that can occur during the execution of a task. These 
include posting error and warning messages, returning a value from the DTSExecResult structure, posting 
messages, returning the DTSExecResult value, and disclosing information about the results of task execution 
through the ExecutionValue property. 


The IDTSComponentEvents interface contains the FireWarning and FireError methods, which can be called by 
the task to post error and warning messages to the run-time engine. Both methods require parameters such as 
the error code, source component, description, Help file, and help context information. Depending on the 
configuration of the task, the runtime responds to these messages by raising events and breakpoints, or by 
writing information to the event log. 


The TaskHost also provides the ExecutionValue property that can be used to provide additional information 
about the results of execution. For example, if a task deletes rows from a table as part of its Execute method, it 
might return the number of rows deleted as the value of the ExecutionValue property. In addition, the TaskHost 
provides the ExecValueVariable property. This property lets the user map the ExecutionValue returned from the 
task to any variable visible to the task. The specified variable can then be used to establish precedence 


constraints between tasks. 


Execution Example 


The following code example demonstrates an implementation of the Execute method, and shows an overridden 
ExecutionValue property. The task deletes the file that is specified by the fileName property of the task. The 
task posts a warning if the file does not exist, or if the fileName property is an empty string. The task returns a 
Boolean value in the ExecutionValue property to indicate whether the file was deleted. 


using System; 
using Microsoft.SqlServer.Dts.Runtime; 


public class SampleTask : Task 
{ 
private string fileName = 
private bool fileDeleted = false; 


un, 
H 


public override DTSExecResult Execute(Connections cons, 
VariableDispenser vars, IDTSComponentEvents events, 
IDTSLogging log, Object txn) 


try 
{ 
if (this.fileName == "") 
{ 
events.FireWarning(@, "SampleTask", "No file specified.", "", 0); 
this.fileDeleted = false; 
} 


else 


{i 
if (System.I0.File.Exists(this.fileName) ) 


{ 
System.1I0.File.Delete(this.fileName) ; 
this.fileDeleted = true; 
t 
else 
this.fileDeleted = false; 
} 


return DTSExecResult.Success; 

} 

catch (System.Exception exception) 

{ 
// Capture the exception and post an error. 
events.FireError(@, "Sampletask", exception.Message, "", @); 
return DTSExecResult.Failure; 


} 


public string FileName 

{ 
get { return this.fileName; } 
set { this.fileName = value; } 


} 
public override object ExecutionValue 
{ 
get { return this.fileDeleted; } 
} 


Imports System 
Imports Microsoft.SqlServer.Dts.Runtime 


Public Class SampleTask 
Inherits Task 


Private _fileName As String = 
Private _fileDeleted As Boolean = False 


Public Overrides Function Execute(ByVal cons As Connections, _ 


ByVal vars As VariableDispenser, ByVal events As IDTSComponentEvents, _ 


ByVal log As IDTSLogging, ByVal txn As Object) As DTSExecResult 


Try 
If Me._fileName = "" Then 
events.FireWarning(@, "SampleTask", "No file specified.", "", 0) 
Me. _fileDeleted = False 
Else 
If System.1I0.File.Exists(Me. fileName) Then 
System.1I0.File.Delete(Me. fileName) 
Me._fileDeleted = True 
Else 
Me. _fileDeleted = False 
End If 
End If 
Return DTSExecResult.Success 
Catch exception As System.Exception 
: Capture the exception and post an error. 
events.FireError(@, "Sampletask", exception.Message, "", @) 
Return DTSExecResult.Failure 
End Try 


End Function 


Public Property FileName() As String 
Get 
Return Me._fileName 
End Get 
Set(ByVal Value As String) 
Me._fileName = Value 
End Set 
End Property 


Public Overrides ReadOnly Property ExecutionValue() As Object 
Get 
Return Me._fileDeleted 
End Get 
End Property 


End Class 


See Also 


Creating a Custom Task 
Coding a Custom Task 
Developing a User Interface for a Custom Task 


Connecting to Data Sources in a Custom Task 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Tasks connect to external data sources to retrieve or save data by using a connection manager. At design time, a 
connection manager represents a logical connection, and describes key information such as the server name 
and any authentication properties. At run time, tasks call the AcquireConnection method of the connection 
manager to establish the physical connection to the data source. 


Because a package can contain many tasks, each of which may have connections to different data sources, the 
package tracks all the connection managers in a collection, the Connections collection. Tasks use the collection in 
their package to find the connection manager that they will use during validation and execution. The 
Connections collection is the first parameter to the Validate and Execute methods. 


You can prevent the task from using the wrong connection manager by displaying the ConnectionManager 
objects from the collection to the user, by using a dialog box or drop-down list in the graphical user interface. 
This gives the user a way to select from among only those ConnectionManager objects of the appropriate type 
that are contained in the package. 


Tasks call the AcquireConnection method to establish the physical connection to the data source. The method 
returns the underlying connection object that can then be used by the task. Because the connection manager 
isolates the implementation details of the underlying connection object from the task, the task only has to call 
the AcquireConnection method to establish the connection, and does not have to be concerned with other 
aspects of the connection. 


Example 


The following sample code demonstrates validation of the ConnectionManager name in the Validate and 
Execute methods, and shows how to use the AcquireConnection method to establish the physical connection in 
the Execute method. 


muy 
a) 


private string connectionManagerName = 


public string ConnectionManagerName 

ib 
get { return this.connectionManagerName; } 
set { this.connectionManagerName = value; } 


public override DTSExecResult Validate( 
Connections connections, VariableDispenser variableDispenser, 
IDTSComponentEvents componentEvents, IDTSLogging log) 


// If the connection manager exists, validation is successful; 
// otherwise, fail validation. 
try 
{ 
ConnectionManager cm = connections[this.connectionManagerName] ; 
return DTSExecResult.Success; 
} 
catch (System.Exception e) 
{ 
componentEvents.FireError(@, "SampleTask", "Invalid connection manager.", "" 
return DTSExecResult.Failure; 


public override DTSExecResult Execute(Connections connections, 
VariableDispenser variableDispenser, IDTSComponentEvents componentEvents, 
IDTSLogging log, object transaction) 


try 

{ 
ConnectionManager cm = connections[this.connectionManagerName] ; 
object connection = cm.AcquireConnection(transaction) ; 
return DTSExecResult.Success; 

t 

catch (System.Exception exception) 

{ 
componentEvents.FireError(@, "“SampleTask", exception.Message, "", 0); 
return DTSExecResult.Failure; 


» 9); 


Private _connectionManagerName As String = 


Public Property ConnectionManagerName() As String 
Get 
Return Me._connectionManagerName 
End Get 
Set(ByVal Value As String) 
Me._connectionManagerName = value 
End Set 
End Property 


Public Overrides Function Validate( _ 
ByVal connections As Microsoft.SqlServer.Dts.Runtime.Connections, _ 
ByVal variableDispenser As Microsoft.SqlServer.Dts.Runtime.VariableDispenser, _ 
ByVal componentEvents As Microsoft.SqlServer.Dts.Runtime.IDTSComponentEvents, _ 
ByVal log As Microsoft.SqlServer.Dts.Runtime.IDTSLogging) _ 
As Microsoft.SqlServer.Dts.Runtime.DTSExecResult 


If the connection manager exists, validation is successful; 
" otherwise fail validation. 
Try 

Dim cm As ConnectionManager = connections(Me._connectionManagerName) 

Return DTSExecResult.Success 
Catch e As System.Exception 
componentEvents.FireError(@, "SampleTask", "Invalid connection manager.", "", @) 
Return DTSExecResult.Failure 


End Try 
End Function 


Public Overrides Function Execute( _ 
ByVal connections As Microsoft.SqlServer.Dts.Runtime.Connections, _ 
ByVal variableDispenser As Microsoft.SqlServer.Dts.Runtime.VariableDispenser, _ 
ByVal componentEvents As Microsoft.SqlServer.Dts.Runtime.IDTSComponentEvents, _ 
ByVal log As Microsoft.SqlServer.Dts.Runtime.IDTSLogging, ByVal transaction As Object) _ 
As Microsoft.SqlServer.Dts.Runtime.DTSExecResult 


Try 
Dim cm As ConnectionManager = connections(Me._connectionManagerName) 
Dim connection As Object = cm.AcquireConnection(transaction) 
Return DTSExecResult.Success 

Catch exception As System.Exception 
componentEvents.FireError(@, "SampleTask", exception.Message, "", Q) 
Return DTSExecResult.Failure 

End Try 


End Function 


See Also 


Integration Services (SSIS) Connections 
Create Connection Managers 


Raising and Defining Events in a Custom Task 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


The Integration Services run-time engine provides a collection of events that provide status on the progress of a 
task as the task is validated and executed. The IDTSComponentEvents interface defines these events, and is 
provided to tasks as a parameter to the Validate and Execute methods. 


There is another set of events, which are defined in the IDTSEvents interface, that are raised on behalf of the task 
by the TaskHost. The TaskHost raises events that occur before and after validation and execution, whereas the 
task raises the events that occur during execution and validation. 


Creating Custom Events 


Custom task developers can define new, custom events by creating a new Eventinfo in their overridden 
implementation of the InitializeTask method. After the Eventinfo is created, it is added to the Eventinfos 
collection by using the Add method. The method signature of the Add method is as follows: 


public void Add(string eventName, string description, bool allowEventHandlers, string[] parameterNames, 
TypeCode[] parameterTypes, string[] parameterDescriptions) ; 


The following code sample shows the InitializeTask method of a custom task, where two custom events are 
created and their properties are set. The new events are then added to the Eventinfos collection. 


The first custom event has an eventName of "OnBeforelncrement" and description of "Fires after the initial 
value is updated." The next parameter, the true value, indicates that this event should allow an event handler 
container to be created to handle the event. The event handler is a container that provides structure in a package 
and services to tasks, like other containers such as the package, Sequence, ForLoop, and ForEachLoop. When the 
allowEventHandlers parameter is true, DtsEventHandler objects are created for the event. Any parameters that 
were defined for the event are now available to the DtsEventHandler in the variables collection of the 
DtsEventHandler. 


public override void InitializeTask(Connections connections, 
VariableDispenser variables, IDTSInfoEvents events, 
IDTSLogging log, EventInfos eventInfos, 
LogEntryInfos logEntryInfos, ObjectReferenceTracker refTracker) 


this.eventInfos = eventiInfos; 

string[] paramNames = new string[1]; 

TypeCode[] paramTypes = new TypeCode[1]{TypeCode. Int32}; 
string[] paramDescriptions = new string[1]; 


paramNames[Q] = "InitialValue"; 
paramDescriptions[@] = "The value before it is incremented."; 


this.eventInfos.Add("OnBeforeIncrement", 

"Fires before the task increments the value.", 

true, paramNames,paramTypes, paramDescriptions) ; 
this.onBeforeIncrement = this.eventInfos["OnBeforeIncrement” ] ; 


paramDescriptions[@] = "The value after it has been incremented."; 
this.eventInfos.Add("OnAfterIncrement", 

"Fires after the initial value is updated.", 

true,paramNames, paramTypes, paramDescriptions) ; 
this.onAfterIncrement = this.eventInfos["OnAfterIncrement" ]; 


Public Overrides Sub InitializeTask(ByVal connections As Connections, _ 

ByVal variables As VariableDispenser, ByVal events As IDTSInfoEvents, _ 

ByVal log As IDTSLogging, ByVal eventInfos As EventInfos, _ 

ByVal logEntryInfos As LogEntryInfos, ByVal refTracker As ObjectReferenceTracker) 


Dim paramNames(@) As String 
Dim paramTypes(®@) As TypeCode = {TypeCode. Int32} 


Dim paramDescriptions(@) As String 


Me.eventInfos = eventInfos 


"InitialValue" 


paramDescriptions(@) = "The value before it is incremented." 


paramNames (@) 


Me.eventInfos.Add("OnBeforeIncrement", _ 

"Fires before the task increments the value.", _ 

True, paramNames, paramTypes, paramDescriptions) 
Me.onBeforeIncrement = Me.eventInfos("OnBeforeIncrement" ) 


paramDescriptions(@) = "The value after it has been incremented." 
Me.eventInfos.Add("OnAfterIncrement", _ 
"Fires after the initial value is updated.", True, _ 
paramNames, paramTypes, paramDescriptions) 
Me.onAfterIncrement = Me.eventInfos("OnAfterIncrement" ) 


End Sub 


Raising Custom Events 


Custom events are raised by calling the FireCustomEvent method. The following line of code raises a custom 
event. 


componentEvents.FireCustomEvent(this.onBeforeIncrement.Name, 
this.onBeforeIncrement.Description, ref arguments, 
null, ref bFireOnBeforeIncrement) ; 


componentEvents.FireCustomEvent (Me.onBeforeIncrement.Name, _ 


Me.onBeforeIncrement.Description, arguments, _ 
Nothing, bFireOnBeforeIncrement) 


Sample 


The following example shows a task that defines a custom event in the InitializeTask method, adds the custom 


event to the Eventinfos collection, and then raises the custom event during its Execute method by calling the 


FireCustomEvent method. 


DtsTask(DisplayName = "CustomEventTask" 
play 
public class CustomEventTask : Task 


{ 


public override DTSExecResult Execute(Connections connections, 


VariableDispenser variableDispenser, IDTSComponentEvents componentEvents, 


IDTSLogging log, object transaction) 


{ 
bool fireAgain; 
object[] args = new object[1] { "The value of the parameter." }; 
componentEvents.FireCustomEvent( "MyCustomEvent", 
"Firing the custom event.", ref args, 
"CustomEventTask" , ref fireAgain ); 
return DTSExecResult.Success; 
i; 


public override void InitializeTask(Connections connections, 
VariableDispenser variableDispenser, IDTSInfoEvents events, 


IDTSLogging log, EventInfos eventInfos, 


LogEntryInfos logEntryInfos, ObjectReferenceTracker refTracker) 


string[] names = new string[1] {"Parameteri"}; 


TypeCode[] types = new TypeCode[1] {TypeCode.String}; 
string[] descriptions = new string[1] {"Parameter description." 


eventInfos .Add("MyCustomEvent" , 
"Fires when my interesting event happens.", 
true, names, types, descriptions) ; 


}3 


<DtsTask(DisplayName = "CustomEventTask")> _ 
Public Class CustomEventTask 
Inherits Task 
Public Overrides Function Execute(ByVal connections As Connections, _ 

ByVal variableDispenser As VariableDispenser, _ 
ByVal componentEvents As IDTSComponentEvents, _ 
ByVal log As IDTSLogging, ByVal transaction As Object) _ 
As DTSExecResult 


Dim fireAgain As Boolean 
Dim args() As Object = New Object(1) {"The value of the parameter."} 


componentEvents.FireCustomEvent("MyCustomEvent", _ 
"Firing the custom event.", args, _ 
"CustomEventTask" , fireAgain) 
Return DTSExecResult.Success 
End Function 


Public Overrides Sub InitializeTask(ByVal connections As Connections, _ 
ByVal variableDispenser As VariableDispenser, 
ByVal events As IDTSInfoEvents, 
ByVal log As IDTSLogging, ByVal eventInfos As EventInfos, ByVal logEnTryInfos As LogEnTryInfos, 
ByVal refTracker As ObjectReferenceTracker ) 


Dim names() As String = New String(1) {"Parameter1"} 
Dim types() As TypeCode = New TypeCode(1) {TypeCode. String} 
Dim descriptions() As String = New String(1) {"Parameter description."} 
eventInfos.Add("MyCustomEvent", _ 
"Fires when my interesting event happens.", _ 
True, names, types, descriptions) 


End Sub 


End Class 


See Also 


Integration Services (SSIS) Event Handlers 
Add an Event Handler to a Package 


Adding Support for Debugging in a Custom Task 
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The Integration Services run-time engine enables packages, tasks, and other types of containers to be 
suspended during execution by using breakpoints. The use of breakpoints lets you review and correct errors that 
prevent your application or tasks from running correctly. The breakpoint architecture enables the client to 
evaluate the run-time value of objects in the package at defined points of execution while task processing is 
suspended. 


Custom task developers can use this architecture to create custom breakpoint targets by using the 
IDTSBreakpointSite interface, and its parent interface, IDTSSuspend. The IDTSBreakpointSite interface defines the 
interaction between the run-time engine and the task for creating and managing custom breakpoint sites or 
targets. The |IDTSSuspend interface provides methods and properties that are called by the run-time engine to 
notify the task to suspend or resume its execution. 


A breakpoint site or target is a point in the execution of the task where processing can be suspended. Users 
select from available breakpoint sites in the Set Breakpoints dialog box. For example, in addition to the default 
breakpoint options, the Foreach Loop Container offers the "Break at the beginning of every iteration of the loop" 
option. 


When a task reaches a breakpoint target during execution, it evaluates the breakpoint target to determine 
whether a breakpoint is enabled. This indicates that the user wants execution to stop at that breakpoint. If the 
breakpoint is enabled, the task raises the OnBreakpointHit event to the run-time engine. The run-time engine 
responds to the event by calling the Suspend method of each task that is currently running in the package. 
Execution of the task resumes when the runtime calls the ResumeExecution method of the suspended task. 


Tasks that do not use breakpoints should still implement the IDTSBreakpointSite and IDTSSuspend interfaces. 
This ensures that the task is suspended correctly when other objects in the package raise OnBreakpointHit 
events. 


IDTSBreakpointSite Interface and BreakpointManager 


Tasks create breakpoint targets by calling the CreateBreakpointTarget method of the BreakpointManager, 
providing an integer ID and string description as parameters. When the task reaches the point in its code that 
contains a breakpoint target, it evaluates the breakpoint target by using the IsBreakpointlargetEnabled method 
to determine whether that breakpoint is enabled. If true, the task notifies the run-time engine by raising the 
OnBreakpointHit event. 


The IDTSBreakpointSite interface defines a single method, AcceptBreakpointManager, which is called by the run- 
time engine during task creation. This method provides as a parameter the BreakpointManager object, which is 
then used by the task to create and manage its breakpoints. Tasks should store the BreakpointManager locally 
for use during the Validate and Execute methods. 


The following sample code demonstrates how to create a breakpoint target by using the BreakpointManager. 
The sample calls the OnBreakpointHit method to raise the event. 


public void AcceptBreakpointManager( BreakpointManager breakPointManager ) 


{ 
// Store the breakpoint manager locally. 


this.bpm = breakPointManager; 


} 

public override DTSExecResult Execute( Connections connections, 
Variables variables, IDTSComponentEvents events, 
IDTSLogging log, DtsTransaction txn) 


// Create a breakpoint. 
this.bpm.CreateBreakPointTarget( 1 , "A sample breakpoint target." ); 


if( this.bpm.IsBreakpointTargetEnabled( 1 ) == true ) 
events.OnBreakpointHit( this.bpm.GetBreakpointTarget( 1 ) ); 


Public Sub AcceptBreakpointManager(ByVal breakPointManager As BreakpointManager ) 


Store the breakpoint manager locally. 
Me.bpm = breakPointManager 


End Sub 


Public Overrides Function Execute(ByVal connections As Connections, _ 
ByVal variables As Variables, ByVal events As IDTSComponentEvents, _ 
ByVal log As IDTSLogging, ByVal txn As DtsTransaction) As DTSExecResult 


Create a breakpoint. 
Me.bpm.CreateBreakPointTarget(1 , "A sample breakpoint target.") 


If Me.bpm.IsBreakpointTargetEnabled(1) = True Then 
events .OnBreakpointHit (Me. bpm.GetBreakpointTarget (1) ) 
End If 


End Function 


IDTSSuspend Interface 


The IDTSSuspend interface defines the methods that are called by the run-time engine when it pauses or 
resumes execution of a task. The |DTSSuspend interface is implemented by the IDTSBreakpointSite interface, and 
its Suspend and ResumeExecution methods are usually overridden by the custom task. When the run-time 
engine receives an OnBreakpointHit event from a task, it calls the Suspend method of each running task, 
notifying the tasks to pause. When the client resumes execution, the run-time engine calls the 
ResumeExecution method of the tasks that are suspended. 


Suspending and resuming task execution involves pausing and resuming the task's execution thread. In 
managed code, you do this using the ManualResetEvent class in System.Threading namespace of the .NET 
Framework. 


The following code sample demonstrates suspension and resumption of task execution. Notice that the Execute 
method has changed from the previous code sample, and the execution thread is paused when firing the 
breakpoint. 


private ManualResetEvent m_suspended = new ManualResetEvent( true ); 
private ManualResetEvent m_canExecute = new ManualResetEvent( true ); 
private int m_suspendRequired = @; 

private int m_debugMode = @; 


public override DTSExecResult Execute( Connections connections, Variables variables, IDTSComponentEvents 
events, IDTSLogging log, DtsTransaction txn) 


// While a task is not executing, it is suspended. 
// Now that we are executing, 

// change to not suspended. 
ChangeEvent(m_suspended, false); 


// Check for a suspend before doing any work, 
// in case the suspend and execute calls 
// were initiated at virtually the same time. 


CheckAndSuspend(); 

CheckAndFireBreakpoint( componentEvents, 1); 
t 
private void CheckAndSuspend() 
{ 


// Loop until we can execute. 
// The loop is required rather than a simple If 
// because there is a time between the return from WaitOne and the 
// reset that we might receive another Suspend call. 
// Suspend() will see that we are suspended 
// and return. So we need to rewait. 
while (!m_canExecute.WaitOne(@, false)) 
{ 
ChangeEvent(m_suspended, true); 
m_canExecute.WaitOne(); 
ChangeEvent(m_suspended, false); 


} 
private void CheckAndFireBreakpoint(IDTSComponentEvents events, int breakpointID) 
{ 
// If the breakpoint is enabled, fire it. 
if (m_debugMode != @ && this.bpm.IsBreakpointTargetEnabled(breakpointID) ) 
{ 
// Enter a suspend mode before firing the breakpoint. 
// Firing the breakpoint will cause the runtime 
// to call Suspend on this task. 
// Because we are blocked on the breakpoint, 
// we are suspended. 
ChangeEvent(m_suspended, true); 
events .OnBreakpointHit(this.bpm.GetBreakpointTarget(breakpointID) ) ; 
ChangeEvent(m_suspended, false); 


// Check for a suspension for two reasons: 
Vee 1. If we are at a point where we could fire a breakpoint, 


VE we are at a valid suspend point. Even if we didn't hit a 
Hy breakpoint, the runtime may have called suspend, 
// so check for it. 
Hef 2. Between the return from OnBreakpointHit 
Hef and the reset of the event, it is possible to have 
Ti received a suspend call from which we returned because 
TL we were already suspended. We need to be sure it is okay 
Vaf to continue executing now. 
CheckAndSuspend(); 
} 
static void ChangeEvent(ManualResetEvent e, bool shouldSet) 
{ 
bool succeeded; 
if (shouldSet) 
succeeded = e.Set(); 
else 
succeeded = e.Reset(); 
if (!succeeded) 
throw new Exception("Synchronization object failed."); 
t 
public bool SuspendRequired 
{ 


get {return m_suspendRequired != 0;} 
set 


// This lock is also taken by Suspend(). 

// Because it is possible for the package to be 

// suspended and resumed in quick succession, 

// this property might be set before 

// the actual Suspend() call. 

// Without the lock, the Suspend() might reset the canExecute 
// event after we set it to abort the suspension. 

lock (this) 


{ 
Interlocked.Exchange(ref m_suspendRequired, value ? 1: @); 
if (!value) 
ResumeExecution(); 
} 
} 
i; 
public void ResumeExecution() 
{ 
ChangeEvent( m_canExecute,true ); 
t 
public void Suspend() 
{ 


// This lock is also taken by the set SuspendRequired method. 
// It prevents this call from overriding an 
// aborted suspension. See comments in set SuspendRequired. 
lock (this) 
{ 

// If a Suspend is required, do it. 

if (m_suspendRequired != @) 

ChangeEvent(m_canExecute, false); 


// We can't return from Suspend until the task is "suspended". 

// This can happen one of two ways: 

// the m_suspended event occurs, indicating that the execute thread 
// has suspended, or the canExecute flag is set, 

// indicating that a suspend is no longer required. 

WaitHandle [] suspendOperationComplete = {m_suspended, m_canExecute}; 
WaitHandle.WaitAny(suspendOperationComplete) ; 


Private m_suspended As ManualResetEvent = New ManualResetEvent(True) 
Private m_canExecute As ManualResetEvent = New ManualResetEvent(True) 
Private m_suspendRequired As Integer = @ 

Private m_debugMode As Integer = @ 


Public Overrides Function Execute(ByVal connections As Connections, _ 
ByVal variables As Variables, ByVal events As IDTSComponentEvents, _ 
ByVal log As IDTSLogging, ByVal txn As DtsTransaction) As DTSExecResult 


While a task is not executing it is suspended. 
" Now that we are executing, 
" change to not suspended. 


ChangeEvent(m_suspended, False) 


Check for a suspend before doing any work, 


in case the suspend and execute calls 
"were initiated at virtually the same time. 
CheckAndSuspend() 


CheckAndFireBreakpoint(componentEvents, 1) 
End Function 


Private Sub CheckAndSuspend() 


Loop until we can execute. 


The loop is required rather than a simple if 
" because there is a time between the return from WaitOne and the 


" reset that we might receive another Suspend call. 

" Suspend() will see that we are suspended 

"and return. So we need to rewait. 

Do While Not m_canExecute.WaitOne(@, False) 
ChangeEvent(m_suspended, True) 
m_canExecute.WaitOne() 
ChangeEvent(m_suspended, False) 


Loop 
End Sub 


Private Sub CheckAndFireBreakpoint(ByVal events As IDTSComponentEvents, _ 
ByVal breakpointID As Integer) 


" If the breakpoint is enabled, fire it. 
If m_debugMode <> @ AndAlso Me.bpm.IsBreakpointTargetEnabled(breakpointID) Then 
: Enter a suspend mode before firing the breakpoint. 


Firing the breakpoint will cause the runtime 


to call Suspend on this task. 


Because we are blocked on the breakpoint, 
: we are suspended. 
ChangeEvent(m_suspended, True) 
events .OnBreakpointHit (Me. bpm.GetBreakpointTarget (breakpointID) ) 
ChangeEvent(m_suspended, False) 
End If 
" Check for a suspension for two reasons: 
3 1. If we are at a point where we could fire a breakpoint, 
: we are at a valid suspend point. Even if we didn't hit a 
i breakpoint, the runtime may have called suspend, 
so check for it. 
: 2. Between the return from OnBreakpointHit 
‘ and the reset of the event, it is possible to have 
. received a suspend call from which we returned because 
: we were already suspended. We need to be sure it is okay 


to continue executing now. 
CheckAndSuspend() 


End Sub 
Shared Sub ChangeEvent(ByVal e As ManualResetEvent, ByVal shouldSet As Boolean) 


Dim succeeded As Boolean 
If shouldSet Then 

succeeded = e.Set() 
Else 

succeeded = e.Reset() 
End If 


If (Not succeeded) Then 
Throw New Exception("Synchronization object failed.") 
End If 


End Sub 


Public Property SuspendRequired() As Boolean 
Get 
Return m_suspendRequired <> @ 
End Get 
Set 
" This lock is also taken by Suspend(). 
X Because it is possible for the package to be 
" suspended and resumed in quick succession, 
y this property might be set before 
3 the actual Suspend() call. 
Without the lock, the Suspend() might reset the canExecute 
i event after we set it to abort the suspension. 
SyncLock Me 
Interlocked.Exchange(m_suspendRequired,IIf(Value, 1, 9)) 


If (Not Value) Then 
ResumeExecution() 
End If 
End SyncLock 
End Set 
End Property 


Public Sub ResumeExecution() 
ChangeEvent (m_canExecute, True) 
End Sub 


Public Sub Suspend() 


" This lock is also taken by the set SuspendRequired method. 
" It prevents this call from overriding an 
" aborted suspension. See comments in set SuspendRequired. 
SyncLock Me 
" If a Suspend is required, do it. 

If m_suspendRequired <> @ Then 

ChangeEvent(m_canExecute, False) 

End If 
End SyncLock 
" We can't return from Suspend until the task is “suspended”. 
" This can happen one of two ways: 
" the m_suspended event occurs, indicating that the execute thread 
" has suspended, or the canExecute flag is set, 
" indicating that a suspend is no longer required. 
Dim suspendOperationComplete As WaitHandle() = {m_suspended, m_canExecute} 
WaitHandle.WaitAny(suspendOperationComplete) 


End Sub 


See Also 


Debugging Control Flow 
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The Integration Services object model provides custom task developers the ability to easily create a custom user 
interface for a task that can then be integrated and displayed in SQL Server Data Tools (SSDT). The user interface 
can provide helpful information to the user in SSIS Designer, and guide users to correctly configure the 
properties and settings of the custom task. 


Developing a custom user interface for a task involves using two important classes. The following table 
describes those classes. 


CLASS DESCRIPTION 


DtsTaskAttribute An attribute that identifies a managed task, and supplies 
design-time information through its properties to control 
how SSIS Designer displays and interacts with the object. 


IDtsTaskUI An interface used by the task to associate the task with its 
custom user interface. 


This section describes the role of the DtsTaskAttribute attribute and the |DtsTaskUI interface when you are 
developing a user interface for a custom task, and provides details about how to create, integrate, deploy, and 
debug the task within SSIS Designer. 


The SSIS Designer provides multiple entry points to the user interface for the task: the user can select Edit on 
the shortcut menu, double-click the task, or click the Show Editor link at the bottom of the property sheet. 
When the user accesses one of these entry points, SSIS Designer locates and loads the assembly that contains 
the user interface for the task. The user interface for the task is responsible for creating the properties dialog 
box that is displayed to the user in SQL Server Data Tools (SSDT). 


A task and its user interface are separate entities. They should be implemented in separate assemblies to reduce 
localization, deployment, and maintenance work. The task DLL does not load, call, or generally contain any 
knowledge of its user interface, except for the information that is contained in the DtsTaskAttribute attribute 
values coded in the task. This is the only way that a task and its user interface are associated. 


The DtsTask Attribute 


The DtsTaskAttribute attribute is included in the task class code to associate a task with its user interface. The 
SSIS Designer uses the properties of the attribute to determine how to display the task in the designer. These 
properties include the name to display and the icon, if any. 


The following table describes the properties of the DtsTaskAttribute attribute. 


PROPERTY DESCRIPTION 
DisplayName Displays the task name in the Control Flow toolbox. 
Description The task description (inherited from DtsLocalizableAttribute). 


This property is shown in ToolTips. 


PROPERTY 


IconResource 


RequiredProductLevel 


TaskContact 


TaskType 


Attribute.Typeld 


UlTypeName 


DESCRIPTION 


The icon displayed in SSIS Designer. 


If used, set it to one of the values in the DTSProductLevel 
enumeration. For example, 


RequiredProductLevel = DTSProductLevel.None 


Holds contact information for occasions when the task 
requires technical support. 


Assigns a type to the task. 


When implemented in a derived class, gets a unique 
identifier for this Attribute. For more information, see 
Attribute.TypelD property in the NET Framework Class 
Library. 


The type name of the assembly that is used by SSIS Designer 
to load the assembly. This property is used to find the user 
interface assembly for the task. 


The following code example shows the DtsTaskAttribute as it would look, coded above the class definition. 


using System; 


using Microsoft.SqlServer.Dts.Runtime; 
namespace Microsoft.SSIS.Samples 


{ 
[DtsTask 


( 


DisplayName = "MyTask", 


IconResource = "MyTask.MyTaskIcon.ico", 
UITypeName = "My Custom Task," + 


"Version=1.0.0.0," + 
"Culture = Neutral," 


"PublickeyToken = 12345abc6789de01", 
TaskType = "PackageMaintenance", 


ee 


TaskContact = "MyTask; company name; any other information", 


RequiredProductLevel = DTSProductLevel.None 


)] 
public class MyTask : 


it 


// Your code here. 


Task 


Imports System 
Imports Microsoft.SqlServer.Dts.Runtime 


<DtsTask(DisplayName:="MyTask", _ 
IconResource:="MyTask.MyTaskIcon.ico", _ 
UITypeName:="My Custom Task," & _ 
"Version=1.0.0.0,Culture=Neutral," & _ 
"PublickeyToken=12345abc6789de@1", _ 
TaskType:="PackageMaintenance", _ 
TaskContact:="MyTask; company name; any other information", _ 
RequiredProductLevel:=DTSProductLevel.None)> _ 
Public Class MyTask 
Inherits Task 


" Your code here. 


End Class 'MyTask 


The SSIS Designer uses the UlTypeName property of the attribute that includes the assembly name, type name, 
version, culture, and public key token, to locate the assembly in the Global Assembly Cache (GAC) and load it for 
use by the designer. 


After the assembly has been located, SSIS Designer uses the other properties in the attribute to display 
additional information about the task in SSIS Designer, such as the name, icon, and description of the task. 


The DisplayName, Description, and lconResource properties specify how the task is presented to the user. The 
lconResource property contains the resource ID of the icon embedded in the user interface assembly. The 
designer loads the icon resource by ID from the assembly, and displays it next to the task name in the toolbox 
and on the designer surface when the task is added to a package. If a task does not provide an icon resource, the 
designer uses a default icon for the task. 


The IDTSTaskUI Interface 


The |DtsTaskUI interface defines the collection of methods and properties called by SSIS Designer to initialize 
and display the user interface associated with the task. When the user interface for a task is invoked, the 
designer calls the Initialize method, implemented by the task user interface when you wrote it, and then 
provides the TaskHost and Connections collections of the task and package, respectively, as parameters. These 
collections are stored locally, and used subsequently in the GetView method. 


The designer calls the GetView method to request the window that is displayed in SSIS Designer. The task 
creates an instance of the window that contains the user interface for the task, and returns the user interface to 
the designer for display. Typically, the TaskHost and Connections objects are provided to the window through an 
overloaded constructor so they can be used to configure the task. 


The SSIS Designer calls the GetView method of the task UI to display the user interface for the task. The task 
user interface returns the Windows form from this method, and SSIS Designer shows this form as a modal 
dialog box. When the form is closed, SSIS Designer examines the value of the DialogResult property of the 
form to determine whether the task has been modified and if these modifications should be saved. If the value 
of the DialogResult property is OK, the SSIS Designer calls the persistence methods of the task to save the 
changes; otherwise, the changes are discarded. 


The following code sample implements the |DtsTaskUI interface, and assumes the existence of a Windows form 
class named SampleTaskForm. 


using System; 

using System.Windows. Forms; 

using Microsoft.SqlServer.Dts.Runtime; 

using Microsoft.SqlServer.Dts.Runtime.Design; 


namespace Sample 
{ 
public class HelloWorldTaskUI : IDtsTaskUI 
{ 
TaskHost taskHost; 
Connections connections; 
public void Initialize(TaskHost taskHost, IServiceProvider serviceProvider) 
this.taskHost = taskHost; 
IDtsConnectionService cs = serviceProvider.GetService 
( typeof( IDtsConnectionService ) ) as IDtsConnectionService; 
this.connections = cs.GetConnections(); 

t 
public ContainerControl GetView() 

{ 

return new HelloWorldTaskForm(this.taskHost, this.connections); 

t 

public void Delete(IWin32Window parentWindow) 

{ 

} 

public void New(IWin32Window parentWindow) 

{ 

} 


Imports System 

Imports Microsoft.SqlServer.Dts.Runtime 
Imports Microsoft.SqlServer.Dts.Runtime.Design 
Imports System.Windows.Forms 


Public Class HelloWorldTaskUI 
Implements IDtsTaskUI 


Dim taskHost As TaskHost 
Dim connections As Connections 


Public Sub Initialize(ByVal taskHost As TaskHost, ByVal serviceProvider As IServiceProvider) _ 
Implements IDtsTaskUI.Initialize 


Dim cs As IDtsConnectionService 

Me.taskHost = taskHost 

cs = DirectCast(serviceProvider.GetService(GetType(IDtsConnectionService)), IDtsConnectionService) 
Me.connections = cs.GetConnections() 


End Sub 


Public Function GetView() As ContainerControl _ 
Implements IDtsTaskUI.GetView 


Return New HelloWorldTaskForm(Me.taskHost, Me.connections) 
End Function 


Public Sub Delete(ByVal parentWindow As IWin32Window) _ 
Implements IDtsTaskUI.Delete 


End Sub 


Public Sub [New](ByVal parentWindow As IWin32Window) _ 
Implements IDtsTaskUI. [New] 


End Sub 


End Class 


See Also 


Creating a Custom Task 
Coding a Custom Task 
Developing a User Interface for a Custom Task 
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Integration Services uses connection managers to encapsulate the information needed to connect to an external 
data source. Integration Services includes a variety of connection managers that support connections to the 
most commonly used data sources, from enterprise databases to text files and Excel worksheets. If the 
connection managers and external data sources supported by Integration Services do not entirely meet your 


requirements, you can create a custom connection manager. 


To create a custom connection manager, you have to create a class that inherits from the 
ConnectionManagerBase base class, apply the DtsConnectionAttribute attribute to your new class, and override 
the important methods and properties of the base class, including the ConnectionString property and the 
AcquireConnection method. 





IMPORTANT 


Most of the tasks, sources, and destinations that have been built into Integration Services work only with specific types of 
built-in connection managers. Before developing a custom connection manager for use with built-in tasks and 
components, check whether those components restrict the list of available connection managers to those of a specific 
type. If your solution requires a custom connection manager, you might also have to develop a custom task, or a custom 


source or destination, for use with the connection manager. 





In This Section 


This section describes how to create, configure, and code a custom connection manager and its optional custom 
user interface. The code snippets shown in this section are drawn from the Sql Server Custom Connection 
Manager Sample. 


Creating a Custom Connection Manager 


Describes how to create the classes for a custom connection manager project. 


Coding a Custom Connection Manager 
Describes how to implement a custom connection manager by overriding the methods and properties of the 
base class. 


Developing a User Interface for a Custom Connection Manager 
Describes how to implement the user interface class and the form that is used to configure the custom 
connection manager. 


Related Sections 


Information Common to all Custom Objects 


For information that is common to all the type of custom objects that you can create in Integration Services, see 
the following topics: 


Developing Custom Objects for Integration Services 
Describes the basic steps in implementing all types of custom objects for Integration Services. 


Persisting Custom Objects 





Describes custom persistence and explains when it is necessary. 


Building, Deploying, and Debugging Custom Objects 

Describes the techniques for building, signing, deploying, and debugging custom objects. 

Information about Other Custom Objects 

For information on the other types of custom objects that you can create in Integration Services, see the 


following topics: 


Developing a Custom Task 
Discusses how to program custom tasks. 


Developing a Custom Log Provider 
Discusses how to program custom log providers. 


Developing a Custom ForEach Enumerator 


Discusses how to program custom enumerators. 


Developing a Custom Data Flow Component 
Discusses how to program custom data flow sources, transformations, and destinations. 


Creating a Custom Connection Manager 
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The steps that you must follow to create a custom connection manager are similar to the steps for creating any 
other custom object for Integration Services: 


e Create a new class that inherits from the base class. For a connection manager, the base class is 
ConnectionManagerBase. 


e Apply the attribute that identifies the type of object to the class. For a connection manager, the attribute is 
DtsConnectionAttribute. 


e Override the implementation of the methods and properties of the base class. For a connection manager, 
these include the ConnectionString property and the AcquireConnection and ReleaseConnection 
methods. 


e@ Optionally, develop a custom user interface. For a connection manager, this requires a class that 
implements the |DtsConnectionManagerU! interface. 





NOTE 


Most of the tasks, sources, and destinations that have been built into Integration Services work only with specific types of 
built-in connection managers. Therefore, these samples cannot be tested with the built-in tasks and components. 











Getting Started with a Custom Connection Manager 


Creating Projects and Classes 


Because all managed connection managers derive from the ConnectionManagerBase base class, the first step 
when you create a custom connection manager is to create a class library project in your preferred managed 
programming language and create a class that inherits from the base class. In this derived class, you will 
override the methods and properties of the base class to implement your custom functionality. 


In the same solution, create a second class library project for the custom user interface. A separate assembly for 
the user interface is recommended for ease of deployment because it lets you update and redeploy the 
connection manager or its user interface independently. 


Configure both projects to sign the assemblies that will be generated at build time by using a strong name key 
file. 


Applying the DtsConnection Attribute 


Apply the DtsConnectionAttribute attribute to the class that you have created to identify it as a connection 
manager. This attribute provides design-time information such as the name, description, and connection type of 
the connection manager. The ConnectionType and Description properties correspond to the Type and 
Description columns displayed in the Add SSIS Connection Manager dialog box, which is displayed when 
configuring connections for a package in SQL Server Data Tools (SSDT). 


Use the UlTypeName property to link the connection manager to its custom user interface. To obtain the public 
key token that is required for this property, you an use sn.exe -t to display the public key token from the key 
pair (.snk) file that you intend to use to sign the user interface assembly. 


<DtsConnection(ConnectionType:="SQLVB", _ 

DisplayName:="SqlConnectionManager (VB)", _ 

Description:="Connection manager for Sql Server", _ 

UITypeName : ="SqlConnMgrUIVB.SqiConnMgrUIVB, SqlConnMgrUIVB, Version=1.0.0.0,Culture=neutral, PublicKeyToken= 
<insert public key token here>")> _ 
Public Class SqlConnMgrVB 

Inherits ConnectionManagerBase 


End Class 


[DtsConnection(ConnectionType = "SQLCS", 
DisplayName = "SqlConnectionManager (CS)", 
Description = "Connection manager for Sql Server", 
UITypeName = "SqlConnMgrUICS.SqlConnMgrUICS , SqlConnMgrUICS, Version=1.0.0.0,Culture=neutral, PublickeyToken= 
<insert public key token here>") ] 
public class SqlConnMgrcs : 
ConnectionManagerBase 


{ 


Building, Deploying, and Debugging a Custom Connection Manager 


The steps for building, deploying, and debugging a custom connection manager in Integration Services are 
similar to the steps for other types of custom objects. For more information, see Building, Deploying, and 
Debugging Custom Objects. 


See Also 


Coding a Custom Connection Manager 
Developing a User Interface for a Custom Connection Manager 
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After you have created a class that inherits from the ConnectionManagerBase base class, and applied the 
DtsConnectionAttribute attribute to the class, you must override the implementation of the properties and 
methods of the base class to provide your custom functionality. 


For samples of custom connection managers, see Developing a User Interface for a Custom Connection 
Manager. The code examples shown in this topic are drawn from the SQL Server Custom Connection Manager 
sample. 


NOTE 


Most of the tasks, sources, and destinations that have been built into Integration Services work only with specific types of 


built-in connection managers. Therefore, these samples cannot be tested with the built-in tasks and components. 





Configuring the Connection Manager 


Setting the ConnectionString Property 


The ConnectionString property is an important property and the only property unique to a custom connection 
manager. The connection manager uses the value of this property to connect to the external data source. If you 
are combining several other properties, such as server name and database name, to create the connection 
string, you can use a helper function to assemble the string by replacing certain values in a connection string 
template with the new value supplied by the user. The following code example shows an implementation of the 
ConnectionString property that relies on a helper function to assemble the string. 


Default values. 

Private _serverName As String = "(local)" 

Private _databaseName As String = "AdventureWorks" 
Private _connectionString As String = String.Empty 


Private Const CONNECTIONSTRING_TEMPLATE As String = _ 
"Data Source=<servername>;Initial Catalog=<databasename>; Integrated Security=SSPI" 


Public Property ServerName() As String 
Get 
Return _serverName 
End Get 
Set(ByVal value As String) 
_serverName = value 
End Set 
End Property 


Public Property DatabaseName() As String 
Get 
Return _databaseName 
End Get 
Set(ByVal value As String) 
_databaseName = value 
End Set 
End Property 


Public Overrides Property ConnectionString() As String 
Get 
UpdateConnectionString() 
Return _connectionString 
End Get 
Set(ByVal value As String) 
_connectionString = value 
End Set 
End Property 


Private Sub UpdateConnectionString() 
Dim temporaryString As String = CONNECTIONSTRING_TEMPLATE 
If Not String.IsNullOrEmpty(_serverName) Then 
temporaryString = temporaryString.Replace("<servername>", _serverName) 
End If 
If Not String.IsNullOrEmpty(_databaseName) Then 
temporaryString = temporaryString.Replace("<databasename>", _databaseName) 
End If 


_connectionString = temporaryString 


End Sub 


// Default values. 

private string _serverName = "(local)"; 

private string _databaseName = "AdventureWorks"; 
private string _connectionString = String.Empty; 


private const string CONNECTIONSTRING_TEMPLATE = "Data Source=<servername>;Initial Catalog= 
<databasename>; Integrated Security=SSPI"; 


public string ServerName 


{ 
get 
{ 
return _serverName; 
} 
set 
{ 
_serverName = value; 
} 
} 
public string DatabaseName 
{ 
get 
{ 
return _databaseName; 
} 
set 
{ 
_databaseName = value; 
t 
i 
public override string ConnectionString 
{ 
get 
{ 
UpdateConnectionString() ; 
return _connectionString; 
} 
set 
{ 
_connectionString = value; 
} 
} 


private void UpdateConnectionString() 


{ 
string temporaryString = CONNECTIONSTRING_TEMPLATE; 


if (!String.IsNullOrEmpty(_serverName) ) 


{ 
temporaryString = temporaryString.Replace("<servername>", _serverName) ; 
} 
if (!String.IsNulloOrEmpty(_databaseName) ) 
{ 
temporaryString = temporaryString.Replace("<databasename>", _databaseName) ; 
} 


_connectionString = temporaryString; 


Validating the Connection Manager 


You override the Validate method to make sure that the connection manager has been configured correctly. At a 


minimum, you should validate the format of the connection string and make sure that values have been 
provided for all arguments. Execution cannot continue until the connection manager returns Success from the 
Validate method. 


The following code example shows an implementation of Validate that makes sure that the user has specified a 


server name for the connection. 


Public Overrides Function Validate(ByVal infoEvents As Microsoft.SqlServer.Dts.Runtime.IDTSInfoEvents) As 
Microsoft.SqlServer.Dts.Runtime.DTSExecResult 


If String.IsNullOrEmpty(_serverName) Then 
infoEvents.FireError(@, "SqlConnectionManager", "No server name specified", String.Empty, @) 
Return DTSExecResult. Failure 

Else 
Return DTSExecResult.Success 

End If 


End Function 


public override Microsoft.SqlServer.Dts.Runtime.DTSExecResult 
Validate(Microsoft.SqlServer.Dts.Runtime.IDTSInfoEvents infoEvents) 


{ 


if (String. IsNullOrEmpty(_serverName) ) 
{ 


infoEvents.FireError(@, "SqlConnectionManager", "No server name specified", String.Empty, @); 
return DTSExecResult.Failure; 


} 


else 


{ 


return DTSExecResult.Success; 


Persisting the Connection Manager 


Usually, you do not have to implement custom persistence for a connection manager. Custom persistence is 
required only when the properties of an object use complex data types. For more information, see Developing 
Custom Objects for Integration Services. 


Working with the External Data Source 


The methods that support connecting to an external data source are the most important methods of a custom 
connection manager. The AcquireConnection and ReleaseConnection methods are called at various times during 
both design time and run time. 


Acquiring the Connection 


You need to decide what type of object it is appropriate for the AcquireConnection method to return from your 
custom connection manager. For example, a File connection manager returns only a string that contains a path 
and filename, whereas an ADO.NET connection manager returns a managed connection object that is already 
open. An OLE DB connection manager returns a native OLE DB connection object that cannot be used from 
managed code. The custom SQL Server connection manager, from which the code snippets in this topic are 
taken, returns an open SqlConnection object. 


Users of your connection manager need to know in advance what type of object to expect, so that they can cast 
the returned object to the appropriate type and access its methods and properties. 


Public Overrides Function AcquireConnection(ByVal txn As Object) As Object 
Dim sqlConnection As New SqlConnection 
UpdateConnectionString() 
With sqlConnection 
-ConnectionString = _connectionString 
-Open() 
End With 


Return sqlConnection 


End Function 


public override object AcquireConnection(object txn) 


i 


SqlConnection sqlConnection = new SqlConnection(); 
UpdateConnectionString(); 


sqlConnection.ConnectionString = _connectionString; 
sqlConnection.Open(); 


return sqlConnection; 


Releasing the Connection 


The action that you take in the ReleaseConnection method depends on the type of object that you returned from 
the AcquireConnection method. If there is an open connection object, you should close it and to release any 
resources that it is using. If AcquireConnection returned only a string value, no action needs to be taken. 


Public Overrides Sub ReleaseConnection(ByVal connection As Object) 
Dim sqlConnection As SqlConnection 
sqlConnection = DirectCast(connection, SqlConnection) 
If sqlConnection.State <> ConnectionState.Closed Then 
sqlConnection.Close() 


End If 


End Sub 


public override void ReleaseConnection(object connection) 
{ 
SqlConnection sqlConnection; 
sqlConnection = (SqlConnection) connection; 
if (sqlConnection.State != ConnectionState.Closed) 
sqlConnection.Close(); 


See Also 


Creating a Custom Connection Manager 


Developing a User Interface for a Custom Connection Manager 


Developing a User Interface for a Custom 
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After you have overridden the implementation of the properties and methods of the base class to provide your 
custom functionality, you may want to create a custom user interface for your connection manager. If you do not 
create a custom user interface, users can configure your connection manager only by using the Properties 
window. 


In a custom user interface project or assembly, you normally have two classes-a class that implements 
|DtsConnectionManagerUI, and the Windows form that it displays to gather information from the user. 





IMPORTANT 


After signing and building your custom user interface and installing it in the global assembly cache as described in Coding 
a Custom Connection Manager, remember to provide the fully qualified name of this class in the UlTypeName property of 
the DtsConnectionAttribute. 


NOTE 


Most of the tasks, sources, and destinations that have been built into Integration Services work only with specific types of 
built-in connection managers. Therefore, these samples cannot be tested with the built-in tasks and components. 





Coding the User Interface Class 


The |DtsConnectionManagerUI interface has four methods: Initialize, New, Edit, and Delete. The following 
sections describe these four methods. 








NOTE 


You may not need to write any code for the Delete method if no cleanup is required when the user deletes an instance of 
the connection manager. 











Initializing the User Interface 


In the Initialize method, the designer provides a reference to the connection manager that is being configured so 
that the user interface class can modify the connection manager's properties. As shown in the following code, 
your code needs to cache the reference to the connection managerfor later use. 


Public Sub Initialize(ByVal connectionManager As Microsoft.SqlServer.Dts.Runtime.ConnectionManager, ByVal 
serviceProvider As System.IServiceProvider) Implements 
Microsoft.SqlServer.Dts.Runtime.Design.IDtsConnectionManagerUL. Initialize 


_connectionManager = connectionManager 
_serviceProvider = serviceProvider 


End Sub 


public void Initialize(Microsoft.SqlServer.Dts.Runtime.ConnectionManager connectionManager, 
System. IServiceProvider serviceProvider) 


if 


_connectionManager = connectionManager; 
_serviceProvider = serviceProvider; 


Creating a New Instance of the User Interface 


The New method, which is not a constructor, is called after the Initialize method when the user creates a new 
instance of the connection manager. In the New method, you usually want to display the form for editing, unless 
the user has copied and pasted an existing connection manager. The following code shows an implementation of 
this method. 


Public Function [New](ByVal parentWindow As System.Windows.Forms.IWin32Window, ByVal connections As 
Microsoft.SqlServer.Dts.Runtime.Connections, ByVal connectionUIArgs As 
Microsoft.SqlServer.Dts.Runtime.Design.ConnectionManagerUIArgs) As Boolean Implements 
Microsoft.SqlServer.Dts.Runtime.Design. IDtsConnectionManagerUI .New 


Dim clipboardService As IDtsClipboardService 


clipboardService = _ 

DirectCast(_serviceProvider.GetService(GetType(IDtsClipboardService)), IDtsClipboardService) 
If Not clipboardService Is Nothing Then 

" If the connection manager has been copied and pasted, take no action. 
If clipboardService.IsPasteActive Then 

Return True 
End If 


End If 
Return EditSqlConnection(parentWindow) 


End Function 


public bool New(System.Windows.Forms.IWin32Window parentWindow, Microsoft.SqlServer.Dts.Runtime.Connections 
connections, Microsoft.SqlServer.Dts.Runtime.Design.ConnectionManagerUIArgs connectionUIArgs) 


{ 


IDtsClipboardService clipboardService; 


clipboardService = (IDtsClipboardService)_serviceProvider.GetService(typeof(IDtsClipboardService) ) ; 
if (clipboardService != null) 
// If connection manager has been copied and pasted, take no action. 


{ 


if (clipboardService.IsPasteActive) 


{ 


return true; 


return EditSqlConnection(parentWindow) ; 


Editing the Connection Manager 


Because the form for editing is called from both the New and the Edit methods, it is convenient to use a helper 
function to encapsulate the code that displays the form. The following code shows an implementation of this 
helper function. 


Private Function EditSqlConnection(ByVal parentWindow As IWin32Window) As Boolean 
Dim sqlCMUIForm As New SqlConnMgrUIFormvVB 


sqlCMUIForm. Initialize(_connectionManager, _serviceProvider) 
If sqlCMUIForm.ShowDialog(parentWindow) = DialogResult.OK Then 
Return True 
Else 
Return False 
End If 


End Function 


private bool EditSqlConnection(IWin32Window parentWindow) 


{ 


SqlConnMgrUIFormCS sqlCMUIForm = new SqlConnMgrUIFormCs() ; 


sqlCMUIForm. Initialize(_connectionManager, _serviceProvider) ; 
if (sqlCMUIForm.ShowDialog(parentWindow) == DialogResult.OK) 
{ 


return true; 


} 


else 


1 


return false; 


In the Edit method, you simply have to display the form for editing. The following code shows an 
implementation of the Edit method that uses a helper function to encapsulate the code for the form. 


Public Function Edit(ByVal parentWindow As System.Windows.Forms.IWin32Window, ByVal connections As 
Microsoft.SqlServer.Dts.Runtime.Connections, ByVal connectionUIArg As 
Microsoft.SqlServer.Dts.Runtime.Design.ConnectionManagerUIArgs) As Boolean Implements 
Microsoft.SqlServer.Dts.Runtime.Design.IDtsConnectionManagerUI. Edit 


Return EditSqlConnection(parentWindow) 


End Function 


public bool Edit(System.Windows.Forms.IWin32Window parentWindow, Microsoft.SqlServer.Dts.Runtime.Connections 
connections, Microsoft.SqlServer.Dts.Runtime.Design.ConnectionManagerUIArgs connectionUIArg) 


{ 


return EditSqlConnection(parentWindow) ; 


Coding the User Interface Form 


After creating the user interface class that implements the methods of the IDtsConnectionManagerUI interface, 
you must create a Windows form where the user can configure the properties of your connection manager. 
Initializing the User Interface Form 


When you display your custom form for editing, you can pass a reference to the connection manager that is 
being edited. You can pass this reference either by using a custom constructor for the form class, or by creating 


your own Initialize method as shown here. 


Public Sub Initialize(ByVal connectionManager As ConnectionManager, ByVal serviceProvider As 
IServiceProvider) 


_connectionManager = connectionManager 
_serviceProvider = serviceProvider 
ConfigureControlsFromConnectionManager ( ) 
EnableControls() 


End Sub 


public void Initialize(ConnectionManager connectionManager, IServiceProvider serviceProvider) 


{ 


_connectionManager = connectionManager; 
_serviceProvider = serviceProvider; 
ConfigureControlsFromConnectionManager() ; 
EnableControls(); 


Setting Properties on the User Interface Form 


Finally, your form class needs a helper function that populates the controls on the form when it is first loaded 
with the existing or the default values of the properties of the connection manager. Your form class also needs a 
similar function that sets the values of the properties to the values entered by the user when the user clicks OK 
and closes the form. 


Private Const CONNECTIONNAME_BASE As String = "SqlConnectionManager” 
Private Sub ConfigureControlsFromConnectionManager ( ) 
Dim tempName As String 
Dim tempServerName As String 
Dim tempDatabaseName As String 
With _connectionManager 
tempName = .Properties("Name") .GetValue(_connectionManager) . ToString 


If Not String.IsNullOrEmpty(tempName) Then 
_connectionName = tempName 


Else 
_connectionName = CONNECTIONNAME_BASE 
End If 
tempServerName = .Properties("ServerName") .GetValue(_connectionManager) . ToString 


If Not String.IsNullOrEmpty(tempServerName) Then 
_serverName = tempServerName 


txtServerName.Text = _serverName 
End If 
tempDatabaseName = .Properties("DatabaseName").GetValue(_connectionManager) . ToString 


If Not String.IsNullOrEmpty(tempDatabaseName) Then 
_databaseName = tempDatabaseName 
txtDatabaseName.Text = _databaseName 

End If 


End With 
End Sub 
Private Sub ConfigureConnectionManagerFromControls() 
With _connectionManager 
.Properties("Name").SetValue(_connectionManager, _connectionName) 
-Properties("ServerName").SetValue(_connectionManager, _serverName) 
-Properties( "DatabaseName" ) .SetValue(_connectionManager, _databaseName) 


End With 


End Sub 


private const string CONNECTIONNAME_BASE = "SqlConnectionManager" ; 


private void ConfigureControlsFromConnectionManager() 


{ 


string tempName; 
string tempServerName; 
string tempDatabaseName; 


tempName = _connectionManager .Properties[ "Name" ].GetValue(_connectionManager ) . ToString(); 
if (!String.IsNullOrEmpty (tempName) ) 
{ 
_connectionName = tempName; 
} 


else 


{ 
_connectionName = CONNECTIONNAME_BASE; 


tempServerName = _connectionManager.Properties[ "ServerName" ].GetValue(_connectionManager) . ToString() ; 
if (!String.IsNullOrEmpty(tempServerName) ) 
{ 

_serverName = tempServerName; 

txtServerName.Text = _serverName; 


tempDatabaseName = 
_connectionManager .Properties[ "DatabaseName" ].GetValue(_connectionManager) . ToString() ; 
if (!String.IsNullOrEmpty(tempDatabaseName) ) 


{ 
_databaseName = tempDatabaseName; 
txtDatabaseName.Text = _databaseName; 
y 
} 
} 
private void ConfigureConnectionManagerFromControls() 
{ 
{ 
_connectionManager.Properties["Name"].SetValue(_connectionManager, _connectionName) ; 
_connectionManager.Properties[ "ServerName" ].SetValue(_connectionManager, _serverName) ; 
_connectionManager.Properties[ "DatabaseName" ].SetValue(_connectionManager, _databaseName) ; 
} 
} 


See Also 


Creating a Custom Connection Manager 
Coding a Custom Connection Manager 
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Integration Services has extensive logging capabilities that make it possible to capture events that occur during 
package execution. Integration Services includes a variety of log providers that enable logs to be created and 
stored in formats such as XML, text, database, or in the Windows event log. If the log providers and the output 
formats that are provided do not entirely meet your requirements, you can create a custom log provider. 


To create a custom log provider, you have to create a class that inherits from the LogProviderBase base class, 
apply the DtsLogProviderAttribute attribute to your new class, and override the important methods and 
properties of the base class, including the ConfigString property and the Log method. 


In This Section 
This section describes how to create, configure, and code a custom log provider. 


Creating a Custom Log Provider 


Describes how to create the classes for a custom log provider project. 


Coding a Custom Log Provider 


Describes how to implement a custom log provider by overriding the methods and properties of the base class. 


Developing a User Interface for a Custom Log Provider 


Custom user interfaces for custom log providers are not supported in SQL Server Integration Services. 


Related Topics 


Information Common to all Custom Objects 
For information that is common to all the type of custom objects that you can create in Integration Services, see 


the following topics: 


Developing Custom Objects for Integration Services 


Describes the basic steps in implementing all types of custom objects for Integration Services. 


Persisting Custom Objects 
Describes custom persistence and explains when it is necessary. 


Building, Deploying, and Debugging Custom Objects 

Describes the techniques for building, signing, deploying, and debugging custom objects. 

Information about Other Custom Objects 

For information on the other types of custom objects that you can create in Integration Services, see the 


following topics: 


Developing a Custom Task 
Discusses how to program custom tasks. 


Developing a Custom Connection Manager 


Discusses how to program custom connection managers. 


Developing a Custom ForEach Enumerator 
Discusses how to program custom enumerators. 


Developing a Custom Data Flow Component 
Discusses how to program custom data flow sources, transformations, and destinations. 


Creating a Custom Log Provider 
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The Integration Services run-time environment has extensive logging capabilities. A log lets you capture events 
that occur during package execution. Integration Services includes a variety of log providers that enable logs to 
be created and stored in multiple formats, such as XML, text, database, or in the Windows event log. If one of 
these providers or output formats does not fit your needs, you can create a custom log provider. 


The steps involved in creating a custom log provider are similar to the steps for creating any other custom 
object for Integration Services: 


e Create a new class that inherits from the base class. For a log provider, the base class is LogProviderBase. 


e Apply the attribute that identifies the type of object to the class. For a log provider, the attribute is 
DtsLogProviderAttribute. 


e Override the implementation of the base class's methods and properties. For a log provider, these include 
the ConfigString property and the OpenLog, Log, and CloseLog methods. 


e Custom user interfaces for custom log providers are not implemented in SQL Server Integration Services. 


Getting Started with a Custom Log Provider 


Creating Projects and Classes 


Because all managed log providers derive from the LogProviderBase base class, the first step when you create a 
custom log provider is to create a class library project in your preferred managed programming language, and 
then create a class that inherits from the base class. In this derived class you will override the methods and 
properties of the base class to implement your custom functionality. 


Configure the project to sign the assembly that will be generated with a strong name key file. 





NOTE 


Many Integration Services log providers have a custom user interface that implements |DtsLogProviderUI and replaces 
the Configuration text box in the Configure SSIS Logs dialog box with a filtered dropdown list of available connection 


managers. However custom user interfaces for custom log providers are not implemented in Integration Services. 





Applying the DtsLogProvider Attribute 


Apply the DtsLogProviderAttribute attribute to the class that you have created to identify it as a log provider. 
This attribute provides design-time information such as the name and description of the log provider. The 
DisplayName and Description properties of the attribute correspond to the Name and Description columns 
displayed in the Configure SSIS Logs editor, which is displayed when configuring logging for a package in 
SQL Server Data Tools (SSDT). 


IMPORTANT 


The LogProviderType property of the attribute is not used. However, you must enter a value for it, or the custom log 


provider will not appear in the list of available log providers. 














NOTE 


Since custom user interfaces for custom log providers are not implemented in Integration Services, specifying a value for 


the UlTypeName property of the DtsLogProviderAttribute has no effect. 








<DtsLogProvider(DisplayName:="MyLogProvider", Description:="A simple log provider.", 
LogProviderType:="Custom")> _ 
Public Class MyLogProvider 
Inherits LogProviderBase 
" TODO: Override the base class methods. 
End Class 


[DtsLogProvider(DisplayName="MyLogProvider", Description="A simple log provider.", 
LogProviderType="Custom") ] 
public class MyLogProvider : LogProviderBase 


ib 
// TODO: Override the base class methods. 


Building, Deploying, and Debugging a Custom Log Provider 


The steps for building, deploying, and debugging a custom log provider in Integration Services are very similar 
to the steps required for other types of custom objects. For more information, see Building, Deploying, and 
Debugging Custom Objects. 


See Also 


Coding a Custom Log Provider 
Developing a User Interface for a Custom Log Provider 


Coding a Custom Log Provider 
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After you have created a class that inherits from the LogProviderBase base class, and applied the 
DtsLogProviderAttribute attribute to the class, you must override the implementation of the properties and 
methods of the base class to provide your custom functionality. 


For working samples of custom log providers, see Developing a User Interface for a Custom Log Provider. 


Configuring the Log Provider 


Initializing the Log Provider 


You override the InitializeLogProvider method to cache references to the connections collection and the events 
interface. You can use these cached references later in other methods of the log provider. 


Using the ConfigString Property 


At design time, a log provider receives configuration information from the Configuration column. This 
configuration information corresponds to the ConfigString property of the log provider. By default, this column 
contains a text box from which you can retrieve any string information. Most of the log providers included with 
Integration Services use this property to store the name of the connection manager that the provider uses to 
connect to an external data source. If your log provider uses the ConfigString property, use the Validate method 
to validate this property and make sure that the property is set correctly. 


Validating the Log Provider 


You override the Validate method to make sure that the provider has been configured correctly and is ready for 
execution. Typically, a minimum level of validation is to make sure that the ConfigString is set correctly. 
Execution cannot continue until the log provider returns Success from the Validate method. 


The following code example shows an implementation of Validate that makes sure that the name of a 
connection manager name is specified, that the connection manager exists in the package, and that the 
connection manager returns a file name in the ConfigString property. 


public override DTSExecResult Validate(IDTSInfoEvents infoEvents) 


{ 
if (this.ConfigString.Length == @ || connections.Contains(ConfigString) == false) 


{ 


infoEvents.FireError(@, "MyTextLogProvider", "The ConnectionManager " + ConfigString + " specified 
in the ConfigString property cannot be found in the collection.", "", @); 
return DTSExecResult.Failure; 


} 


else 


{ 


string fileName = connections[ConfigString].AcquireConnection(null) as string; 


if (fileName == null || fileName.Length == @) 
{ 


infoEvents.FireError(@, "MyTextLogProvider", "The ConnectionManager " + ConfigString + 
specified in the ConfigString property cannot be found in the collection.", "", @); 


return DTSExecResult.Failure; 


} 


return DTSExecResult.Success; 


Public Overrides Function Validate(ByVal infoEvents As IDTSInfoEvents) As DTSExecResult 
If Me.ConfigString.Length = @ Or connections.Contains(ConfigString) = False Then 


infoEvents.FireError(@, "MyTextLogProvider", "The ConnectionManager " + ConfigString + " specified 
in the ConfigString property cannot be found in the collection.", "", @) 
Return DTSExecResult. Failure 
Else 
Dim fileName As String = connections(ConfigString) .AcquireConnectionCType(as string, Nothing) 


If fileName = Nothing Or fileName.Length = @ Then 
infoEvents.FireError(@, "MyTextLogProvider", "The ConnectionManager 


+ ConfigString + 
specified in the ConfigString property cannot be found in the collection.", "", 0) 
Return DTSExecResult. Failure 
End If 
End If 
Return DTSExecResult.Success 
End Function 


Persisting the Log Provider 


Ordinarily you do not have to implement custom persistence for a connection manager. Custom persistence is 
required only when the properties of an object use complex data types. For more information, see Developing 
Custom Objects for Integration Services. 


Logging with the Log Provider 


There are three run-time methods that must be overridden by all log providers: OpenLog, Log, and CloseLog. 





IMPORTANT 


During the validation and execution of a single package, the OpenLog and CloseLog methods are called more than one 
time. Make sure that your custom code does not cause earlier log entries to be overwritten by the next opening and 
closing of the log. If you have selected to log validation events in your test package, the first logged event that you 
should see is OnPreValidate; if instead the first logged event that you see is PackageStart, the initial validation events have 


been overwritten. 











Opening the Log 
Most log providers connect to an external data source, such as a file or database, to store the event information 
that is collected during package execution. As with any other object in the runtime, connecting to the external 


data source is typically accomplished by using connection manager objects. 


The OpenLog method is called at the start of package execution.Override this method to establish a connection 
to the external data source. 


The following sample code shows a log provider that opens a text file for writing during OpenLog. It opens the 
file by calling the AcquireConnection method of the connection manager that was specified in the ConfigString 


property. 


public override void OpenLog() 


{ 


if(!this.connections.Contains(this.ConfigString) ) 


throw new Exception("The ConnectionManager " + this.ConfigString + " does not exist in the 


Connections collection."); 


this.connectionManager = connections[ConfigString]; 
string filePath = this.connectionManager.AcquireConnection(null) as string; 


if(filePath == null || filePath.Length == @) 
throw new Exception("The ConnectionManager " + this.ConfigString + " is not a valid FILE 
ConnectionManager'" ) ; 


// Create a StreamWriter to append to. 
sw = new StreamWriter(filePath, true) ; 


sw.WriteLine("Open log" + System.DateTime.Now. ToShortTimeString()); 


Public Overrides Sub OpenLog() 
If Not Me.connections.Contains(Me.ConfigString) Then 


Throw New Exception("The ConnectionManager " + Me.ConfigString + " does not exist in the Connections 


collection.") 
End et 


Me.connectionManager = connections (ConfigString) 
Dim filePath As String = Me.connectionManager.AcquireConnectionCType(as string, Nothing) 


If filePath = Nothing Or filePath.Length = @ Then 


Throw New Exception("The ConnectionManager " + Me.ConfigString + " is not a valid FILE 


ConnectionManager" ) 
End If 


Create a StreamWriter to append to. 
sw = New StreamWriter(filePath, True) 


sw.WriteLine("Open log" + System.DateTime.Now. ToShortTimeString() ) 
End Sub 


Writing Log Entries 

The Log method is called every time that an object in the package raises an event by calling a Fire<event> 
method on one of the event interfaces. Each event is raised with information about its context and usually an 
explanatory message. However, not every call to the Log method includes information for every method 
parameter. For example, some standard events whose names are self-explanatory do not provide MessageText, 
and DataCode and DataBytes are intended for optional supplemental information. 


The following code example implements the Log method, and writes the events to the stream that was opened 
in the previous section. 


public override void Log(string logEntryName, string computerName, string operatorName, string sourceName, 
string sourceID, string executionID, string messageText, DateTime startTime, DateTime endTime, int dataCode, 
byte[] dataBytes) 


{ 
sw.Write(logEntryName + ","); 
sw.Write(computerName + ","); 
sw.Write(operatorName + ","); 
sw.Write(sourceName + ","); 
sw.Write(sourceID + ","); 
sw.Write(messageText + ","); 
sw.Write(dataBytes + ","); 
sw.WriteLine(""); 

} 


Public Overrides Sub Log(ByVal logEnTryName As String, ByVal computerName As String, ByVal operatorName As 

String, ByVal sourceName As String, ByVal sourceID As String, ByVal executionID As String, ByVal messageText 

As String, ByVal startTime As DateTime, ByVal endTime As DateTime, ByVal dataCode As Integer, ByVal 

dataBytes() As Byte) 
sw.Write(logEnTryName + ",") 
sw.Write(computerName + ",") 
sw.Write(operatorName + ) 
sw.Write(sourceName + ",") 
sw.Write(sourceID + ",") 
sw.Write(messageText + ",") 
sw.Write(dataBytes + ",") 
sw.WriteLine("") 

End Sub 


Closing the Log 


The CloseLog method is called at the end of package execution, after all the objects in the package have 
completed execution, or, when the package stops because of errors. 


The following code example demonstrates an implementation of the CloseLog method that closes the file 
stream that was opened during the OpenLog method. 


public override void CloseLog() 


ib 
if (sw != null) 
if 
sw.WriteLine("Close log" + System.DateTime.Now. ToShortTimeString()); 
sw.Close(); 
t 
t 


Public Overrides Sub CloseLog() 
If Not sw Is Nothing Then 
sw.WriteLine("Close log" + System.DateTime.Now. ToShortTimeString() ) 
sw.Close() 
End If 
End Sub 


See Also 


Creating a Custom Log Provider 
Developing a User Interface for a Custom Log Provider 


Developing a User Interface for a Custom Log 


Provider 
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Many Integration Services log providers have a custom user interface that implements IDtsLogProviderUI and 
replaces the Configuration text box in the Configure SSIS Logs dialog box with a filtered dropdown list of 
available connection managers. However, custom user interfaces for custom log providers are not implemented 
in SQL Server Integration Services. 


See Also 


Creating a Custom Log Provider 
Coding a Custom Log Provider 


Developing a Custom ForEach Enumerator 
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Integration Services uses foreach enumerators to iterate over the items in a collection and perform the same 
tasks for each element. Integration Services includes a variety of foreach enumerators that support the most 
commonly used collections, such as all the files in a folder, all the tables in a database, or all the elements of a list 
stored in a package variable. If the foreach enumerators and collections that are provided do not entirely meet 


your requirements, you can create a custom foreach enumerator. 


To create a custom foreach enumerator, you have to create a class that inherits from the ForEachEnumerator 
base class, apply the DtsForEachEnumeratorAttribute attribute to your new class, and override the important 
methods and properties of the base class, including the GetEnumerator method. 


In This Section 


This section describes how to create, configure, and code a custom foreach enumerator and its custom user 
interface. 


Creating a Custom Foreach Enumerator 


Describes how to create the classes for a custom foreach enumerator project. 


Coding a Custom Foreach Enumerator 
Describes how to implement a custom foreach enumerator by overriding the methods and properties of the 
base class. 


Developing a User Interface for a Custom ForEach Enumerator 
Describes how to implement the user interface class and the form that is used to configure the custom foreach 
enumerator. 


Related Topics 


Information Common to all Custom Objects 
For information that is common to all the type of custom objects that you can create in Integration Services, see 


the following topics: 


Developing Custom Objects for Integration Services 


Describes the basic steps in implementing all types of custom objects for Integration Services. 


Persisting Custom Objects 
Describes custom persistence and explains when it is necessary. 


Building, Deploying, and Debugging Custom Objects 

Describes the techniques for building, signing, deploying, and debugging custom objects. 

Information about Other Custom Objects 

For information on the other types of custom objects that you can create in Integration Services, see the 


following topics: 


Developing a Custom Task 
Discusses how to program custom tasks. 


Developing a Custom Connection Manager 
Discusses how to program custom connection managers. 


Developing a Custom Log Provider 
Discusses how to program custom log providers. 


Developing a Custom Data Flow Component 
Discusses how to program custom data flow sources, transformations, and destinations. 


Creating a Custom Foreach Enumerator 
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The steps involved in creating a custom foreach enumerator are similar to the steps for creating any other 
custom object for Integration Services: 


e Create a new class that inherits from the base class. For a foreach enumerator, the base class is 
ForEachEnumerator. 


e Apply the attribute that identifies the type of object to the class. For a foreach enumerator, the attribute is 
DtsForEachEnumeratorAttribute. 


e@ Override the implementation of the base class's methods and properties. For a foreach enumerator, the 
most important is the GetEnumerator method. 


@ Optionally, develop a custom user interface. For a foreach enumerator, this requires a class that 
implements the IDTSForEachEnumeratorUI interface. 


A custom enumerator is hosted by the ForEachLoop container. At run time, the ForEachLoop container calls the 
GetEnumerator method of the custom enumerator. The custom enumerator returns an object that implements 
the IEnumerable interface, such as an ArrayList. The ForEachLoop then iterates over each element in the 
collection, provides the value of the current element to the control flow through a user-defined variable, and 
executes the control flow in the container. 


Getting Started with a Custom ForEach Enumerator 


Creating Projects and Classes 


Because all managed foreach enumerators derive from the ForEachEnumerator base class, the first step when 
you create a custom foreach enumerator is to create a class library project in your preferred managed 
programming language and create a class that inherits from the base class. In this derived class you will 
override the methods and properties of the base class to implement your custom functionality. 


In the same solution, create a second class library project for the custom user interface. A separate assembly for 
the user interface is recommended for ease of deployment because it allows you to update and redeploy the 
foreach enumerator or its user interface independently. 


Configure both projects to sign the assemblies that will be generated at build time by using a strong name key 
file. 


Applying the DtsForEachEnumerator Attribute 


Apply the DtsForEachEnumeratorAttribute attribute to the class that you have created to identify it as a foreach 
enumerator. This attribute provides design-time information such as the name and description of the foreach 
enumerator. The Name property appears in the dropdown list of available enumerators on the Collection tab 
of the Foreach Loop Editor dialog box. 


Use the UlTypeName property to link the foreach enumerator to its custom user interface. To obtain the public 
key token that is required for this property, you an use sn.exe -t to display the public key token from the key 
pair (.snk) file that you intend to use to sign the user interface assembly. 


Imports System 
Imports Microsoft.SqlServer.Dts.Runtime 
Namespace Microsoft.Samples.SqlServer.Dts 

<DtsForEachEnumerator(DisplayName = "MyEnumerator", Description="A sample custom enumerator", 
UITypeName="FullyQualifiedTypeName, AssemblyName, Version=1.00.000.00,Culture=Neutral, PublickKeyToken= 
<publickeytoken>")> _ 

Public Class MyEnumerator 

Inherits ForEachEnumerator 

"Insert code here. 

End Class 

End Namespace 


using System; 
using Microsoft.SqlServer.Dts.Runtime; 
namespace Microsoft.Samples.SqlServer.Dts 


{ 


[DtsForEachEnumerator( DisplayName = "MyEnumerator", Description="A sample custom enumerator", 
UITypeName="FullyQualifiedTypeName, AssemblyName, Version=1.00.000.00,Culture=Neutral, PublickKeyToken= 
<publickeytoken>") ] 

public class MyEnumerator : ForEachEnumerator 


{ 


//Insert code here. 


Building, Deploying, and Debugging a Custom Enumerator 


The steps for building, deploying, and debugging a custom foreach enumerator in Integration Services are very 
similar to the steps required for other types of custom objects. For more information, see Building, Deploying, 
and Debugging Custom Objects. 


See Also 


Coding a Custom Foreach Enumerator 
Developing a User Interface for a Custom ForEach Enumerator 
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After you have created a class that inherits from the ForEachEnumerator base class, and applied the 
DtsForEachEnumeratorAttribute attribute to the class, you must override the implementation of the properties 
and methods of the base class to provide your custom functionality. 


For a working sample of a custom enumerator, see Developing a User Interface for a Custom ForEach 
Enumerator. 


Initializing the Enumerator 


You can override the InitializeForEachEnumerator method to cache references to the connection managers 
defined in the package, and to cache references to the events interface that you can use to raise errors, warnings, 
and informational messages. 


Validating the Enumerator 


You override the Validate method to verify that the enumerator is correctly configured. If the method returns 
Failure, the enumerator and the package that contains the enumerator will not be executed. The 
implementation of this method is specific to each enumerator, but if the enumerator relies on Variable or 
ConnectionManager objects, you should add code to verify that these objects exist in the collections that are 
provided to the method. 


The following code example demonstrates an implementation of Validate that checks for a variable specified in a 
property of the enumerator. 


private string variableNameValue; 


public string VariableName 

{ 
get{ return this.variableNameValue; } 
set{ this.variableNameValue = value; } 


public override DTSExecResult Validate(Connections connections, VariableDispenser variableDispenser, 
IDTSInfoEvents infoEvents, IDTSLogging log) 
{ 

if (!variableDispenser.Contains(this.variableNameValue) ) 

{ 

infoEvents.FireError(@, "MyEnumerator", "The Variable " + this.variableNameValue + " does not exist 
in the collection.", "", 0); 
return DTSExecResult. Failure; 


} 


return DTSExecResult.Success; 


Private variableNameValue As String 


Public Property VariableName() As String 
Get 
Return Me.variableNameValue 
End Get 
Set (ByVal Value As String) 
Me.variableNameValue = value 
End Set 
End Property 


Public Overrides Function Validate(ByVal connections As Connections, ByVal variableDispenser As 
VariableDispenser, ByVal infoEvents As IDTSInfoEvents, ByVal log As IDTSLogging) As DTSExecResult 

If Not variableDispenser.Contains(Me.variableNameValue) Then 

infoEvents.FireError(@, "MyEnumerator", "The Variable " + Me.variableNameValue + " does not exist in 
the collection.", "", @) 
Return DTSExecResult.Failure 

End kt 

Return DTSExecResult.Success 
End Function 


Returning the Collection 


During execution, the ForEachLoop container calls the GetEnumerator method of the custom enumerator. In this 
method, the enumerator creates and populates its collection of items, and then returns the collection. The 
ForEachLoop then iterates the items in the collection, and executes its control flow for each item in the collection. 


The following example shows an implementation of GetEnumerator that returns an array of random integers. 


public override object GetEnumerator() 


{ 
ArrayList numbers = new ArrayList(); 
Random randomNumber = new Random(DateTime.Now) ; 
for( int x=0; x < 100; x++ ) 
numbers.Add( randomNumber .Next()); 
return numbers; 
} 


Public Overrides Function GetEnumerator() As Object 
Dim numbers As ArrayList = New ArrayList() 


Dim randomNumber As Random = New Random(DateTime.Now) 
Dim x As Integer 
For x =@To 10@- 1 Step x+1 
numbers .Add(randomNumber .Next() ) 


Next 


Return numbers 
End Function 


See Also 


Creating a Custom Foreach Enumerator 
Developing a User Interface for a Custom ForEach Enumerator 


Developing a User Interface for a Custom ForEach 
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After you have overridden the implementation of the properties and methods of the base class to provide your 
custom functionality, you may want to create a custom user interface for your Foreach enumerator. If you do not 
create a custom user interface, users can only configure the new custom Foreach enumerator by using the 
Properties window. 


In a custom user interface project or assembly, you create a class that implements ForEachEnumeratorUI. This 
class derives from System.Windows.Forms.UserControl, which is typically used to create a composite control to 
host other Windows Forms controls. The control that you create is displayed in the Enumerator configuration 
area of the Collection tab of the Foreach Loop Editor. 





IMPORTANT 


After signing and building your custom user interface and installing it in the global assembly cache as described in 
Building, Deploying, and Debugging Custom Objects, remember to provide the fully qualified name of this class in the 
UlTypeName property of the DtsForEachEnumeratorAttribute. 





Coding the User Interface Control Class 


Initializing the User Interface 

You override the Initialize method to cache references to the host object, and to the collections of connection 
managers and variables defined in the package. 

Setting Properties on the User Interface Control 


The UserControl class, from which the user interface class is derived, is intended for use as a composite control 
to host other Windows Forms controls. Because this class hosts other controls, you can design your custom user 
interface by dragging and dropping controls, arranging them, setting their properties, and responding at run 
time to their events as in any Windows Forms application. 


Saving Settings 


You override the SaveSettings method to copy the values selected by the user from the controls to the 
properties of the enumerator when the user closes the editor. 


See Also 


Creating a Custom Foreach Enumerator 


Coding a Custom Foreach Enumerator 
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The data flow task consists of components that connect to a variety of data sources and then transform and 
route that data at high speed. Microsoft SQL Server Integration Services provides an extensible object model 
that lets developers create custom sources, transformations, and destinations that you can use in SQL Server 
Data Tools (SSDT) and in deployed packages. This section contains topics that will guide you in developing 
custom data flow components. 


In This Section 


Creating a Custom Data Flow Component 
Describes the initial steps in creating a custom data flow component. 


Design-time Methods of a Data Flow Component 
Describes the design-time methods to implement in a custom data flow component. 


Run-time Methods of a Data Flow Component 
Describes the run-time methods to implement in a custom data flow component. 


Execution Plan and Buffer Allocation 
Describes the data flow execution plan and the allocation of data buffers. 


Working with Data Types in the Data Flow 
Explains how the data flow maps Integration Services data types to .NET Framework managed data types. 


Validating a Data Flow Component 
Explains the methods used to validate component configuration and to reconfigure component metadata. 


Implementing External Metadata 
Explains how to use external metadata columns for data validation. 


Raising and Defining Events in a Data Flow Component 
Explains how to raise predefined and custom events. 


Logging and Defining Log Entries in a Data Flow Component 
Explains how to create and write to custom log entries. 


Using Error Outputs in a Data Flow Component 
Explains how to redirect error rows to an alternative output. 


Upgrading the Version of a Data Flow Component 
Explains how to update saved component metadata when a new version of your component is first used. 


Developing a User Interface for a Data Flow Component 
Explains how to implement a custom editor for a component. 


Developing Specific Types of Data Flow Components 
Contains information about developing the three types of data flow components: sources, transformations, and 
destinations. 


Reference 


Microsoft.SqlServer.Dts.Pipeline 
Contains the classes and interfaces used to create custom data flow components. 


Microsoft.SqlServer.Dts.Pipeline.Wrapper 
Contains the classes and interfaces that make up the data flow task object model, and is used to create custom 
data flow components or build a data flow task. 


Microsoft.SqlServer.Dts.Pipeline.Design 
Contains the classes and interfaces used to create the user interface for data flow components. 


Integration Services Error and Message Reference 
Lists the predefined Integration Services error codes with their symbolic names and descriptions. 


Related Sections 


Information Common to All Custom Objects 
For information that is common to all the type of custom objects that you can create in Integration Services, see 


the following topics: 


Developing Custom Objects for Integration Services 
Describes the basic steps in implementing all types of custom objects for Integration Services. 


Persisting Custom Objects 
Describes custom persistence and explains when it is necessary. 


Building, Deploying, and Debugging Custom Objects 
Describes the techniques for building, signing, deploying, and debugging custom objects. 


Information about Other Custom Objects 


For information on the other types of custom objects that you can create in Integration Services, see the 
following topics: 


Developing a Custom Task 
Discusses how to program custom tasks. 


Developing a Custom Connection Manager 
Discusses how to program custom connection managers. 


Developing a Custom Log Provider 
Discusses how to program custom log providers. 


Developing a Custom ForEach Enumerator 
Discusses how to program custom enumerators. 


See Also 


Extending the Data Flow with the Script Component 
Comparing Scripting Solutions and Custom Objects 
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In Microsoft SQL Server Integration Services, the data flow task exposes an object model that lets developers 
create custom data flow components-sources, transformations, and destinations-by using the Microsoft .NET 
Framework and managed code. 


A data flow task consists of components that contain an IDTSComponentMetaData100 interface and a collection 
of IDTSPath100 objects that define the movement of data between components. 


NOTE 


When you create a custom provider, you need to update the ProviderDescriptors.xml file with the metadata column 
values. 











Design Time and Run Time 


Before execution, the data flow task is said to be in a design-time state, as it undergoes incremental changes. 
Changes may include the addition or removal of components, the addition or removal of the path objects that 
connect components, and changes to the metadata of the components. When metadata changes occur, the 
component can monitor and react to the changes. For example, a component can disallow certain changes or to 
make additional changes in response to a change. At design time, the designer interacts with a component 
through the design-time IDTSDesigntimeComponent100 interface. 


At execution time, the data flow task examines the sequence of components, prepares an execution plan, and 
manages a pool of worker threads that execute the work plan. Although each worker thread performs some 
work that is internal to the data flow task, the principal task of the worker thread is to call the methods of the 
component through the run-time IDTSRuntimeComponent1 00 interface. 


Creating a Component 


To create a data flow component, you derive a class from the PipelineComponent base class, apply the 
DtsPipelineComponentAttribute class, and then override the appropriate methods of the base class. The 
PipelineComponent implements the IDTSDesigntimeComponent100 and IDTSRuntimeComponent100 
interfaces, and exposes their methods for you to override in your component. 


Depending on the objects used by your component, your project will require references to some or all of the 
following assemblies: 


FEATURE ASSEMBLY TO REFERENCE NAMESPACE TO IMPORT 
Data flow Microsoft.SqlServerPipelineHost Microsoft.SqlServerDts.Pipeline 
Data flow wrapper Microsoft.SqlServerDTSPipelineWrap Microsoft.SqlServerDts.Pipeline.Wrapp 


er 


Runtime Microsoft.SQLServerManagedDTS Microsoft.SqlServerDts.Runtime 


FEATURE ASSEMBLY TO REFERENCE NAMESPACE TO IMPORT 


Runtime wrapper Microsoft.SqlServerDTSRuntimeWrap Microsoft.SqlServerDts.Runtime.Wrapp 
er 


The following code example shows a simple component that derives from the base class, and applies the 
DtsPipelineComponentAttribute. You need to add a reference to the Microsoft.SqlServer.DTSPipelineWrap 
assembly. 


using System; 
using Microsoft.SqlServer.Dts.Pipeline; 
using Microsoft.SqlServer.Dts.Pipeline.Wrapper; 


namespace Microsoft.Samples.SqlServer.Dts 


{ 
[DtsPipelineComponent(DisplayName = "SampleComponent", ComponentType = ComponentType.Transform ) ] 
public class BasicComponent: PipelineComponent 
{ 
// TODO: Override the base class methods. 
t 
} 


Imports Microsoft.SqlServer.Dts.Pipeline 
Imports Microsoft.SqlServer.Dts.Pipeline.Wrapper 


<DtsPipelineComponent (DisplayName:="SampleComponent", ComponentType:=ComponentType.Transform)> _ 
Public Class BasicComponent 


Inherits PipelineComponent 
" TODO: Override the base class methods. 


End Class 


See Also 


Developing a User Interface for a Data Flow Component 
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Before execution, the data flow task is said to be in a design-time state, as it undergoes incremental changes. 
Changes may include the addition or removal of components, the addition or removal of the path objects that 
connect components, and changes to the metadata of the components. When metadata changes occur, the 
component can monitor and react to the changes. For example, a component can disallow certain changes or 
make additional changes in response to a change. At design time, the designer interacts with a component 
through the design-time IDTSDesigntimeComponent100 interface. 


Design-Time Implementation 


The design-time interface of a component is described by the IDTSDesigntimeComponent100 interface. 
Although you do not explicitly implement this interface, a familiarity with the methods defined in this interface 
will help you understand which methods of the PipelineComponent base class correspond to the design-time 
instance of a component. 


When a component is loaded in the SQL Server Data Tools (SSDT), the design-time instance of the component is 
instantiated and the methods of the IDTSDesigntimeComponent100 interface are called as the component is 
edited. The implementation of the base class lets you override only those methods that your component 
requires. In many cases, you may override these methods to prevent inappropriate edits to a component. For 
example, to prevent users from adding an output to a component, override the InsertOutput method. Otherwise, 
when the implementation of this method by the base class is called, it adds an output to the component. 


Regardless of the purpose or functionality of your component, you should override the 
ProvideComponentProperties, Validate, and ReinitializeMetaData methods. For more information about Validate 
and ReinitializeMetaData, see Validating a Data Flow Component. 


ProvideComponentProperties Method 


The initialization of a component occurs in the ProvideComponentProperties method. This method is called by 
SSIS Designer when a component is added to the data flow task, and is similar to a class constructor. 
Component developers should create and initialize their inputs, outputs, and custom properties during this 
method call. The ProvideComponentProperties method differs from a constructor because it is not called every 
time that the design-time instance or run-time instance of the component is instantiated. 


The base class implementation of the method adds an input and an output to the component and assigns the ID 
of the input to the Synchronous!InputID property. However, in SQL Server, the input and output objects added by 
the base class are not named. Packages that contain a component with input or output objects whose Name 
property is not set will not successfully load. Therefore, when you use the base implementation, you must assign 
values explicitly to the Name property of the default input and output. 


public override void ProvideComponentProperties() 
{ 

/// TODO: Reset the component. 

/// TODO: Add custom properties. 

/// TODO: Add input objects. 

/// TODO: Add output objects. 


Public Overrides Sub ProvideComponentProperties() 
" TODO: Reset the component. 
" TODO: Add custom properties. 
" TODO: Add input objects. 
" TODO: Add output objects. 
End Sub 


Creating Custom Properties 


The call to the ProvideComponentProperties method is where component developers should add custom 
properties (IDTSCustomProperty100) to the component. Custom properties do not have a data type property. 
The data type of a custom property is set by the data type of the value that you assign to its Value property. 
However, after you have assigned an initial value to the custom property, you cannot assign a value with a 
different data type. 


NOTE 
The IDTSCustomProperty100 interface has limited support for property values of type Object. The only object that you 


can store as the value of a custom property is an array of simple types such as strings or integers. 











You can indicate that your custom property supports property expressions by setting the value of its 
ExpressionType property to CPET_NOTIFY from the DISCustomPropertyExpressionType enumeration, as 
shown in the following example. You do not have to add any code to handle or to validate the property 
expression entered by the user. You can set a default value for the property, validate its value, and read and use 
its value normally. 


IDTSCustomProperty10@ myCustomProperty; 


myCustomProperty.ExpressionType = DTSCustomPropertyExpressionType.CPET_NOTIFY; 


Dim myCustomProperty As IDTSCustomProperty100 


myCustomProperty.ExpressionType = DTSCustomPropertyExpressionType.CPET_NOTIFY 


You can limit users to selecting a custom property value from an enumeration by using the TypeConverter 
property, as shown in the following example, which assumes that you have defined a public enumeration named 
MyValidValues. 


IDTSCustomProperty10@ customProperty = outputColumn.CustomPropertyCollection.New() ; 
customProperty.Name = "My Custom Property"; 

// This line associates the type with the custom property. 

customProperty. TypeConverter = typeof(MyValidValues) .AssemblyQualifiedName; 

// Now you can use the enumeration values directly. 

customProperty.Value = MyValidValues.ValueOne; 


Dim customProperty As IDTSCustomProperty10@ = outputColumn.CustomPropertyCollection.New 
customProperty.Name = "My Custom Property” 

" This line associates the type with the custom property. 
customProperty.TypeConverter = GetType(MyValidValues) .AssemblyQualifiedName 


Now you can use the enumeration values directly. 
customProperty.Value = MyValidValues.ValueOne 


For more information, see "Generalized Type Conversion" and "Implementing a Type Converter" in the MSDN 
Library. 


You can specify a custom editor dialog box for the value of your custom property by using the UlTypeEditor 
property, as shown in the following example. First, you must create a custom type editor that inherits from 
System.Drawing.Design.UITypeEditor, if you cannot locate an existing UI type editor class that fits your 
needs. 


public class MyCustomTypeEditor : UITypeEditor 
{ 


Public Class MyCustomTypeEditor 
Inherits UITypeEditor 


End Class 


Next, specify this class as the value of the UlTypeEditor property of your custom property. 


IDTSCustomProperty10@ customProperty = outputColumn.CustomPropertyCollection.New() ; 
customProperty.Name = "My Custom Property"; 

// This line associates the editor with the custom property. 
customProperty.UITypeEditor = typeof(MyCustomTypeEditor) .AssemblyQualifiedName; 


Dim customProperty As IDTSCustomProperty10@ = outputColumn.CustomPropertyCollection.New 
customProperty.Name = "My Custom Property” 


This line associates the editor with the custom property. 
customProperty.UITypeEditor = GetType(MyCustomTypeEditor) .AssemblyQualifiedName 


For more information, see "Implementing a UI Type Editor" in the MSDN Library. 


See Also 
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At run time, the data flow task examines the sequence of components, prepares an execution plan, and manages 
a pool of worker threads that execute the work plan. The task loads rows of data from sources, processes them 
through transformations, then saves them to destinations. 


Sequence of Method Execution 


During the execution of a data flow component, a subset of the methods in the PipelineComponent base class is 
called. The methods, and the sequence in which they are called, are always the same, with the exception of the 
PrimeOutput and Process|Input methods. These two methods are called based on the existence and 
configuration of a component's IDTSInput100 and IDTSOutput100 objects. 


The following list shows the methods in the order in which they are called during component execution. Note 
that PrimeOutput, when called, is always called before ProcessInput. 


e AcquireConnections 
e Validate 

e@ ReleaseConnections 
e PrepareForExecute 

e AcquireConnections 
e PreExecute 

e@ PrimeOutput 

e Processinput 

e PostExecute 

e ReleaseConnections 
e Cleanup 


PrimeOutput Method 


The PrimeOutput method is called when a component has at least one output, attached to a downstream 
component through an IDTSPath100 object, and the SynchronousInputID property of the output is zero. The 
PrimeOutput method is called for source components and for transformations with asynchronous outputs. 
Unlike the ProcessInput method described below, the PrimeOutput method is only called once for each 
component that requires it. 


ProcessInput Method 


The ProcessInput method is called for components that have at least one input attached to an upstream 
component by an IDTSPath100 object. The Processinput method is called for destination components and for 
transformations with synchronous outputs. ProcessInput is called repeatedly until there are no more rows to 
process from upstream components. 


Working with Inputs and Outputs 


At run time, data flow components perform the following tasks: 

e Source components add rows. 

e Transformation components with synchronous outputs receive rows provided by source components. 
e Transformation components with asynchronous outputs receive rows and add rows. 

e Destination components receive rows and then load them into a destination. 


During execution, the data flow task allocates PipelineBuffer objects that contain all the columns defined in the 
output column collections of a sequence of components. For example, if each of four components in a data flow 
sequence adds one output column to its output column collection,the buffer that is provided to each component 
contains four columns, one for each output column per component. Because of this behavior, a component 
sometimes receives buffers that contain columns it does not use. 


Since the buffers received by your component may contain columns that the component will not use, you must 
locate the columns that you want to use in your component's input and output column collections in the buffer 
provided to the component by the data flow task. You do this by using the FindColumnByLineagelD method of 
the BufferManager property. For performance reasons, this task is ordinarily performed during the PreExecute 

method, rather than in PrimeOutput or Processinput. 


PreExecute is called before the PrimeOutput and Processinput methods, and is the first opportunity for a 
component to perform this work after the Buffer Manager becomes available to the component. During this 
method, the component should locate its columns in the buffers and store this information internally so the 
columns can be used in either the PrimeOutput or Processinput methods. 


The following code example demonstrates how a transformation component with a synchronous output locates 
its input columns in the buffer during PreExecute. 


private int []bufferColumnIndex; 

public override void PreExecute() 

{ 
IDTSInput10@ input = ComponentMetaData.InputCollection[@]; 
bufferColumnIndex = new int[input.InputColumnCollection.Count]; 


for( int x=0; x < input.InputColumnCollection.Count; x++) 


{ 
IDTSInputColumnie@ column = input. InputColumnCollection[x]; 


bufferColumnIndex[x] = BufferManager.FindColumnByLineageID( input.Buffer, column.LineageID) ; 


Dim bufferColumnIndex As Integer() 
Public Overrides Sub PreExecute() 
Dim input As IDTSInput1@@ = ComponentMetaData.InputCollection(@) 
ReDim bufferColumnIndex(input.InputColumnCollection. Count) 
For x As Integer = @ To input. InputColumnCollection. Count 


Dim column As IDTSInputColumn1ee@ = input. InputColumnCollection(x) 
bufferColumnIndex(x) = BufferManager.FindColumnByLineageID(input.Buffer, column.LineageID) 


Next 


End Sub 


Adding Rows 


Components supply rows to downstream components by adding rows to PipelineBuffer objects. The data flow 
task provides an array of output buffers - one for each IDTSOutput100 object that is connected to a downstream 
component - as a parameter to the PrimeOutput method. Source components and transformation components 
with asynchronous outputs add rows to the buffers and call the SetEndOfRowset method when they are finished 
adding rows. The data flow task manages the output buffers that it supplies to components and, as a buffer 
becomes full, automatically moves the rows in the buffer to the next component. The PrimeOutput method is 
called one time per component, unlike the ProcessInput method, which is called repeatedly. 


The following code example demonstrates how a component adds rows to its output buffers during the 
PrimeOutput method, then calls the SetEndOfRowset method. 


public override void PrimeOutput( int outputs, int []outputIDs,PipelineBuffer []buffers) 
{ 


for( int x=; x < outputs; x++ ) 


{ 
IDTSOutput19e@ output = ComponentMetaData.OutputCollection.GetObjectByID( outputIDs[x]); 
PipelineBuffer buffer = buffers[x]; 
// TODO: Add rows to the output buffer. 
t 
foreach( PipelineBuffer buffer in buffers ) 
{ 
/// Notify the data flow task that no more rows are coming. 
buffer.SetEndOfRowset(); 
t 


public overrides sub PrimeOutput( outputs as Integer , outputIDs() as Integer ,buffers() as PipelineBuffer 
buffers) 


For x As Integer = @ To outputs.MaxValue 


Dim output As IDTSOutput1@@ = ComponentMetaData.OutputCollection.GetObjectByID(outputIDs(x) ) 
Dim buffer As PipelineBuffer = buffers(x) 


" TODO: Add rows to the output buffer. 
Next 
For Each buffer As PipelineBuffer In buffers 


Notify the data flow task that no more rows are coming. 
buffer. SetEndOfRowset () 


Next 


End Sub 


For more information about developing components that add rows to output buffers, see Developing a Custom 
Source Component and Developing a Custom Transformation Component with Asynchronous Outputs. 


Receiving Rows 


Components receive rows from upstream components in PipelineBuffer objects. The data flow task provides a 
PipelineBuffer object that contains the rows added to the data flow by upstream components as a parameter to 
the ProcessInput method. This input buffer can be used to examine and modify the rows and columns in the 
buffer, but cannot be used to add or remove rows. The Processinput method is called repeatedly until there are 
no more available buffers. The last time it is called, the EndOfRowset property is true. You can iterate over the 
collection of rows in the buffer by using the NextRow method, which advances the buffer to the next row. This 
method returns false when the buffer is on the last row in the collection. You do not have to check the 
EndOfRowset property unless you have to perform an additional action after the last rows of data have been 
processed. 


The following text shows the correct pattern for using the NextRow method and the EndOfRowset property: 


while (buffer.NextRow()) 


// Do something with each row. 


if (buffer.EndOfRowset) 


// Optionally, do something after all rows have been processed. 


The following code example demonstrates how a component processes the rows in input buffers during the 
ProcessInput method. 


public override void ProcessInput( int inputID, PipelineBuffer buffer ) 


{ 
{ 
IDTSInput10@ input = ComponentMetaData.InputCollection.GetObjectByID(inputID) ; 
while( buffer.NextRow()) 
{ 
// TODO: Examine the columns in the current row. 

t 

} 


Public Overrides Sub ProcessInput(ByVal inputID As Integer, ByVal buffer As PipelineBuffer) 


Dim input As IDTSInput10@ = ComponentMetaData.InputCollection.GetObjectByID(inputID) 
While buffer.NextRow() = True 


TODO: Examine the columns in the current row. 
End While 


End Sub 


For more information about developing components that receive rows in input buffers, see Developing a 
Custom Destination Component and Developing a Custom Transformation Component with Synchronous 
Outputs. 


See Also 
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Before execution, the data flow task examines its components and generates an execution plan for each 
sequence of components. This section provides details about the execution plan, how to view the plan, and how 
input and output buffers are allocated based on the execution plan. 


Understanding the Execution Plan 


An execution plan contains source threads and work threads, and each thread contains work lists that specify 
output work lists for source threads or input and output work lists for work threads. The source threads in an 
execution plan represent the source components in the data flow and are identified in the execution plan by 
SourceThreadn, where nis the zero-based number of the source thread. 


Each source thread creates a buffer, sets a listener, and calls the PrimeOutput method on the source component. 
This is where execution starts and data originates, as the source component starts adding rows to the output 
buffers that are provided to it by the data flow task. After the source threads are running, the balance of work is 
distributed among work threads. 


A work thread may contain both input and output work lists and is identified in the execution plan as 
WorkThreadn, where nis the zero-based number of the work thread. These threads contain output work lists 
when the graph contains a component with asynchronous outputs. 


The following sample execution plan represents a data flow that contains a source component connected to a 
transformation with an asynchronous output connected to a destination component. In this example, 
WorkThreadO contains an output work list because the transformation component has an asynchronous output. 


SourceThread@ 
Influences: 72 158 
Output Work List 
CreatePrimeBuffer of type 1 for output id 10 
SetBufferListener: "WorkThread@" for input ID 73 
CallPrimeOutput on component "OLE DB Source" (1) 
End Output Work List 
This thread drives ® distributors 
End SourceThread@ 
WorkThread@ 
Influences: 72 158 
Input Work list, input ID 73 
CallProcessInput on input ID 73 on component "Sort" (72) for view type 2 
End Input Work list for input 73 
Output Work List 
CreatePrimeBuffer of type 3 for output id 74 
SetBufferListener: "WorkThreadi" for input ID 171with internal handoff 
CallPrimeOutput on component "Sort" (72) 
End Output Work List 
This thread drives @ distributors 
End WorkThread@ 
WorkThread1 
Influences: 158 
Input Work list, input ID 171 
CallProcessInput on input ID 171 on component "OLE DB Destination" (158) for view type 4 
End Input Work list for input 171 
Output Work List 
End Output Work List 
This thread drives ® distributors 
End WorkThread1 


NOTE 


The execution plan is generated every time a package is executed, and can be captured by adding a log provider to the 


package, enabling logging, and selecting the PipelineExecutionPlan event. 





Understanding Buffer Allocation 


Based on the execution plan, the data flow task creates buffers that contain the columns defined in the outputs 
of the data flow components. The buffer is reused as the data flows through the sequence of components, until a 
component with asynchronous outputs is encountered. Then, a new buffer is created, which contains the output 
columns of the asynchronous output and the output columns of downstream components. 


During execution, components have access to the buffer in the current source or work thread. The buffer is 
either an input buffer, provided by the ProcessInput method, or an output buffer, provided by the PrimeOutput 
method. The Mode property of the PipelineBuffer also identifies each buffer as an input or output buffer. 


Transformation components with asynchronous outputs receive the existing input buffer from the Process|nput 
method, and receive the new output buffer from the PrimeOutput method. A transformation component with 
asynchronous outputs is the only type of data flow component that receives both an input and an output buffer. 


Because the buffer provided to a component is likely to contain more columns than the component has in its 
input or output column collections, component developers can call the FindColumnByLineagelD method to 
locate a column in the buffer by specifying its LineagelD. 


Working with Data Types in the Data Flow 
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When developing a custom data flow component in Integration Services, you work constantly with data types, 
copying data into and out of data flow buffers and transforming values. The information in this topic helps you 
to choose the correct Integration Services data types, and to use the correct methods when working with them. 


Inserting Data into the Data Flow 


The PipelineBuffer class provides a series of Set methods for copying data into buffer columns, and a 
corresponding series of Get methods for retrieving data from buffer columns. The following tables show you 
which method to use with each Integration Services data type. 

Set Methods to use with Data Types 


The following table lists the data type in the first column, and then lists the corresponding Set and Get methods. 


DATA TYPE SET METHOD GET METHOD 
DT_BOOL SetBoolean GetBoolean 
DT_BYTES SetBytes GetBytes 
DIcy SetDecimal GetDecimal 
DT_DATE SetDateTime GetDateTime 
DT_DBDATE SetDate GetDate 
DT_DBTIME SetTime GetTime 
DT_DBTIME2 SetTime GetTime 
DT_DBTIMESTAMP SetDateTime GetDateTime 
DT_DBTIMESTAMP2 SetDateTime GetDateTime 
DT_DBTIMESTAMPOFFSET SetDateTimeOffset GetDateTimeOffset 
DT_DECIMAL SetDecimal GetDecimal 
DT_FILETIME SetDateTime GetDateTime 
DT_GUID SetGuid GetGuid 
DT_I1 SetSByte GetSByte 
DT_l2 SetInt16 GetInt16 


DATA TYPE 


DT_l4 


DT_|8 


DT_IMAGE 


DT_NTEXT 


DT_NULL 


DT_NUMERIC 


DT_R4 


DT_R8& 


DT_STR 


DT_TEXT 


DT_UI1 


DT_UI2 


DT_UI4 


DT_UI8 


DT_WSTR 


SET METHOD 


SetInt32 


SetInt64 


AdadBlobData or AddBlobData 


AdadBlobData or AddBlobData 


SetNull 


SetDecimal 


SetSingle 


SetDouble 


SetString 


AddBlobData or AddBlobData 


SetByte 


SetUInt16 


SetUInt32 


SetUInt64 


SetString 


Data Types to Use with the Set Methods 


SET METHOD 


AdadBlobData or AddBlobData 


SetBoolean 


SetByte 


SetBytes 


SetDate 


SetDateTime 


SetDateTimeOffset 


SetDecimal 


DATA TYPE 


GET METHOD 


GetInt32 


GetInt64 


GetBlobData 


GetBlobData 


There is no Get method that is 
applicable to this data type. 


GetDecimal 


GetSingle 


GetDouble 


GetString 


GetBlobData 


GetByte 


GetUInt16 


GetUInt32 


GetUInt64 


GetString 


DT_IMAGE, DT_NTEXT, or DT_TEXT 


DT_BOOL 


DT_UI1 


DT_BYTES 


DT_DBDATE 


DT_DATE, DT_DBTIMESTAMP, DT_DBTIMESTAMP2, or 


DT_FILETIME 


DT_DBTIMESTAMPOFFSET 


DT_CY, DT_DECIMAL, or DT_.NUMERIC 


SET METHOD DATA TYPE 


SetDouble DT_R8 

SetGuid DT_GUID 

SetInt16 DT_I2 

SetInt32 DT_l4 

SetInt64 DT_I8 

SetNull DT_NULL 

SetSByte DT_I1 

SetSingle DT_R4 

SetString DT_STR or DT_WSTR 
SetTime DT_DBTIME or DT_DBTIME2 
SetUInt16 DT_UI2 

SetUInt32 DT_UI4 

SetUInt64 DT_UI8& 


Mapping Data Types in the Data Flow 


While moving data from sources through transformations to destinations, a data flow component must 
sometimes convert data types between the SQL Server Integration Services types defined in the DataType 
enumeration and the managed data types of the Microsoft NET Framework defined in the System namespace. 
In addition, a component must sometimes convert one Integration Services data type to another before that 
type can be converted to a managed type. 


NOTE 


The mapping files in XML format that are installed by default to C:\Program Files\Microsoft SQL 
Server\130\DTS\MappingFiles are not related to the data type mapping discussed in this topic. These files map data types 
from one database version or system to another (for example, from SQL Server to Oracle), and are used only by the SQL 
Server Import and Export Wizard. For more information on these mapping files, see SQL Server Import and Export 
Wizard. 





Mapping between Integration Services and Managed Data Types 


The BufferlypeToDataRecordType and the DataRecordTypeToBufferlype methods map Integration Services data 
types to managed data types. 


Caution 

Developers should use these methods of the PipelineComponent class with caution, and may want to code data 
type mapping methods of their own that are more suited to the unique needs of their custom components. The 
existing methods do not consider numeric precision or scale, or other properties closely related to the data type 
itself. Microsoft may modify or remove these methods, or modify the mappings that they perform, in a future 





version of Integration Services. 


The following table lists how the BufferTypeToDataRecordType and the DataRecordTypeloBufferlype methods 
map various Integration Services data types to managed data types. 


INTEGRATION SERVICES DATA TYPE MAPS TO THIS MANAGED DATA TYPE 
DT_WSTR System.String 
DT_BYTES Array of System.Byte 
DT_DBTIMESTAMP System.DateTime 
DT_DBTIMESTAMP2 System.DateTime 
DT_DBTIMESTAMPOFFSET System.DateTimeOffset 
DT_DBDATE System.DateTime 
DT_DBTIME System.TimeSpan 
DT_DBTIME2 System.TimeSpan 
DT_DATE System.DateTime 
DT_FILETIME System.DateTime 
DT_NUMERIC System.Decimal 
DT_GUID System.Guid 

DT_I1 System.SByte 

DT_l2 System.Int16 

DT_|l4 System.Int32 

DT_I8 System.Int64 
DT_BOOL System.Boolean 
DT_R4 System.Single 

DT_R8 System.Double 
DT_UI1 System.Byte 

DT_Ul2 System.UInt16 
DT_UI4 System.UInt32 


DT_UI8 System.UInt64 


Mapping Integration Services Data Types to Fit Managed Data Types 


Sometimes a data flow component must also convert one Integration Services data type to another before that 
type can be converted to a managed type. The Conver tBufferDataTypeToFitManaged method class maps 
Integration Services data types to other Integration Services data types that can then be mapped to managed 
data types by using the BufferlypeToDataRecordType method. 


Caution 

Developers should use these methods of the PipelineComponent class with caution, and may want to code data 
type mapping methods of their own that are more suited to the unique needs of their custom components. The 
existing methods do not consider numeric precision or scale, or other properties closely related to the data type 
itself. Microsoft may modify or remove these methods, or modify the mappings that they perform, in a future 
version of Integration Services. 


The following table lists how the ConvertBufferDataTypeloFitManaged method maps Integration Services data 
types to other Integration Services data types. 


ORIGINAL INTEGRATION SERVICES DATA TYPE MAPS TO THIS INTEGRATION SERVICES DATA TYPE 
DT_DECIMAL DT_NUMERIC 

DT_CY DT_NUMERIC 

DT_DATE DT_DBTIMESTAMP 

DT_DBDATE DT_DBTIMESTAMP 

DT_FILETIME DT_DBTIMESTAMP 


DT_DBTIMESTAMP2 


DT_DBTIMESTAMP 





DT_DBTIME DT_DBTIME2 
DT_BOOL DT_l4 
DT_TEXT DT_WSTR 
DT_NTEXT DT_WSTR 
DT_STR DT_WSTR 
DT_IMAGE DT_BYTES 
NOTE 


The ConvertBufferDataTypeToFitManaged method does not return a value for the DT_DBTIMESTAMPOFFSET data type, 
and a UnsupportedBufferDataTypeException occurs. You must convert the DT_DBTIMESTAMPOFFSET data type to one of 
the Integration Services date/time data types that can be mapped to a managed data type. For a list of Integration 
Services date/time data types that can be mapped to a managed data types, see the table in the previous section, 
"Mapping between Integration Services and Managed Data Types." For information about converting data types, see 
Integration Services Data Types. 





See Also 
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The Validate method of the PipelineComponent base class is provided to prevent execution of a component that 
is not configured correctly. Use this method to verify that a component has the expected number of input and 
output objects, that the custom properties of the component have acceptable values, and that any connections, if 
required, are specified. Use this method also to verify that the columns in the input and output collections have 
the correct data types and that the DISUsagelype of each column is set appropriately for the component. The 
base class implementation assists in the validation process by checking the input column collection of the 
component and ensuring that each column in the collection refers to a column in the IDTSOutputCollection100 
of the upstream component. 


Validate Method 


The Validate method is called repeatedly when a component Is edited in SSIS Designer. You can provide 
feedback to the designer and to users of the component through the DTSValidationStatus enumeration return 
value, and by posting warnings and errors. The DISValidationStatus enumeration contains three values that 
indicate various stages of failure, and a fourth, VS_ISVALID, that indicates whether the component is correctly 
configured and ready to execute. 


The VS_NEEDSNEWMETADAIA value indicates that an error exists in the ComponentMetaData, and that the 
component can repair the errors. If a component encounters a metadata error that it can repair, it should not fix 
the error in the Validate method, and ComponentMetaData should not be modified during validation. Instead, 
the Validate method should return only VS_NEEDSNEWMETADATA, and the component should repair the error 
in a call to the ReinitializeMetaData method, as described later in this section. 


The VS_ISBROKEN value indicates that the component has an error that can be rectified by editing the 
component in the designer. The error is typically caused by a custom property or a required connection that is 
not specified or is set incorrectly. 


The final error value is VS_ISCORRUPT, which indicates that the component has discovered errors that should 
only occur if the ComponentMetaData property has been modified directly, either by editing the package XML 
or by using the object model. For example, this kind of error occurs when a component has added only a single 
input, but validation discovers that more than one input exists in the ComponentMetaData. Errors that generate 
this return value can only be repaired by resetting the component by using the Reset button in the Advanced 
Editor dialog box. 


Besides returning error values, components provide feedback by posting warnings or errors during validation. 
The FireWarning and FireError methods provide this mechanism. When these methods are called, these events 
are posted in the Error List window of SQL Server Data Tools (SSDT). Component developers can then provide 
direct feedback to users on the errors that have occurred, and if appropriate, how to correct them. 


The following code example shows an overridden implementation of Validate. 


public override DTSValidationStatus Validate() 


if 

bool pbCancel = false; 

// Validate that there is one input. 

if (ComponentMetaData.InputCollection.Count != 1) 

{ 

ComponentMetaData.FireError(@, ComponentMetaData.Name, “Incorrect number of inputs.", "", @, out 
pbCancel); 

return DTSValidationStatus.VS_ISCORRUPT ; 

t 


// Validate that the UserName custom property is set. 
if (ComponentMetaData.CustomPropertyCollection[ "UserName"].Value == null || 
( (string) ComponentMetaData.CustomPropertyCollection["UserName"].Value).Length == @) 
{ 
ComponentMetaData.FireError(@, ComponentMetaData.Name, "The UserName property must be set.", "", 0, 
out pbCancel); 
return DTSValidationStatus.VS_ISBROKEN; 


// Validate that there is one output. 
if (ComponentMetaData.OutputCollection.Count != 1) 


{ 
ComponentMetaData.FireError(@, ComponentMetaData.Name, “Incorrect number of outputs.", "", @, out 
pbCancel); 
return DTSValidationStatus.VS_ISCORRUPT ; 
} 


// Let the base class verify that the input column reflects the output 
// of the upstream component. 
return base.Validate(); 


Public Overrides Function Validate() As DTSValidationStatus 


Dim pbCancel As Boolean = False 
" Validate that there is one input. 
If Not (ComponentMetaData.InputCollection.Count = 1) Then 
ComponentMetaData.FireError(@, ComponentMetaData.Name, "Incorrect number of inputs.", "", @, pbCancel) 
Return DTSValidationStatus.VS_ISCORRUPT 
End If 


" Validate that the UserName custom property is set. 
If ComponentMetaData.CustomPropertyCollection("UserName").Value Is Nothing OrElse 
CType(ComponentMetaData.CustomPropertyCollection("UserName").Value, String).Length = @ Then 
ComponentMetaData.FireError(@, ComponentMetaData.Name, "The UserName property must be set.", "", @, 
pbCancel) 
Return DTSValidationStatus.VS_ISBROKEN 
End If 
" Validate that there is one output. 
If Not (ComponentMetaData.OutputCollection.Count = 1) Then 
ComponentMetaData.FireError(@, ComponentMetaData.Name, "Incorrect number of outputs.", "", @, pbCancel) 
Return DTSValidationStatus.VS_ISCORRUPT 
End If 


" Let the base class verify that the input column reflects the output 


of the upstream component. 
Return MyBase.Validate 


End Function 


‘ Pa 





ReinitializeMetaData Method 


The ReinitializeMetaData method is called by SSIS Designer whenever you edit a component that returns 
VS_NEEDSNEWMETADAIA from its Validate method. Components should contain code that detects and corrects 


the problems identified by the component during validation. 


The following example shows a component that detects problems during validation and fixes these errors in the 


ReinitializeMetaData method. 


private bool areInputColumnsValid = true; 

public override DTSValidationStatus Validate() 

{ 
IDTSInput10@ input = ComponentMetaData.InputCollection[@]; 
IDTSVirtualInput1@@ vInput = input.GetVirtualInput(); 


bool Cancel = false; 
foreach (IDTSInputColumn1e@ column in input.InputColumnCollection) 
if 
try 
{ 
IDTSVirtualInputColumniee vColumn = 
vInput.VirtualInputColumnCollection.GetVirtualInputColumnByLineageID(column.LineageID) ; 
} 


catch 


{ 


ComponentMetaData.FireError(@, ComponentMetaData.Name, "The input column " + 
column.IdentificationString + " does not match a column in the upstream component.", "", @, out Cancel); 

areInputColumnsValid = false; 

return DTSValidationStatus.VS_NEEDSNEWMETADATA; 


} 
} 
return DTSValidationStatus.VS_ ISVALID; 
t 
public override void ReinitializeMetaData() 
{ 


if (!areInputColumnsValid) 

{ 
IDTSInput10@ input = ComponentMetaData.InputCollection[@]; 
IDTSVirtualInput10@ vInput = input.GetVirtualInput(); 


foreach (IDTSInputColumn1@@ column in input. InputColumnCollection) 
ib 
IDTSVirtualInputColumniee vColumn = 
vInput.VirtualInputColumnCollection.GetVirtualInputColumnByLineageID(column.LineageID) ; 


if (vColumn == null) 
input. InputColumnCollection.RemoveObjectByID(column. ID) ; 
} 


areInputColumnsValid = true; 


Private areInputColumnsValid As Boolean = True 


Public Overrides Function Validate() As DTSValidationStatus 
Dim input As IDTSInput10@ = ComponentMetaData. InputCollection(@) 
Dim vInput As IDTSVirtualInput10@ = input.GetVirtualInput 
Dim Cancel As Boolean = False 
For Each column As IDTSInputColumni@e@ In input. InputColumnCollection 
Try 
Dim vColumn As IDTSVirtualInputColumn1@e = 


vInput.VirtualInputColumnCollection.GetVirtualInputColumnByLineageID(column.LineageID) 


Catch 
ComponentMetaData.FireError(@, ComponentMetaData.Name, "The input column " + 


column.IdentificationString + " does not match a column in the upstream component.” 


areInputColumnsValid = False 
Return DTSValidationStatus.VS_NEEDSNEWMETADATA 
End Try 
Next 
Return DTSValidationStatus.VS_ISVALID 
End Function 


Public Overrides Sub ReinitializeMetaData() 
If Not areInputColumnsValid Then 
Dim input As IDTSInput10@ = ComponentMetaData. InputCollection(@) 
Dim vInput As IDTSVirtualInput10@ = input.GetVirtualInput 
For Each column As IDTSInputColumn10e@ In input. InputColumnCollection 
Dim vColumn As IDTSVirtualInputColumn1ee = 


vInput.VirtualInputColumnCollection.GetVirtualInputColumnByLineageID(column.LineageID) 


If vColumn Is Nothing Then 
input. InputColumnCollection.RemoveObjectByID(column. ID) 
End If 
Next 
areInputColumnsValid = True 
End If 
End Sub 


» ®, Cancel) 
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When a component is disconnected from its data source, you can validate the columns in the input and output 
column collections against the columns at its external data source by using the 
IDTSExternalMetadataColumnCollection100 interface. This interface lets you maintain a snapshot of the columns 
at the external data source and map these columns to the columns in the input and output column collection of 
the component. 


Implementing external metadata columns adds a layer of overhead and complexity to component development, 
because you must maintain and validate against an additional column collection, but the ability to avoid 
expensive round trips to the server for validation may make this development work worthwhile. 


Populating External Metadata Columns 


External metadata columns are typically added to the collection when the corresponding input or output column 
is created. New columns are created by calling the New method. The properties of the column are then set to 
match the external data source. 


The external metadata column is mapped to the corresponding input or output column by assigning the ID of 
the external metadata column to the ExternalMetadataColumnID property of the input or output column. This 
lets you locate the external metadata column easily for a specific input or output column by using the 
GetObjectByID method of the collection. 


The following example shows how to create an external metadata column and then map the column to an 
output column by setting the ExternalMetadataColumnID property. 


public void CreateExternalMetaDataColumn(IDTSOutput10@ output, int outputColumnID ) 

{ 
IDTSOutputColumn1@@ oColumn = output.OutputColumnCollection.GetObjectByID(outputColumnID) ; 
IDTSExternalMetadataColumn1e@@ eColumn = output.ExternalMetadataColumnCollection.New(); 


eColumn.DataType = oColumn.DataType; 
eColumn.Precision = oColumn.Precision; 
eColumn.Scale = oColumn.Scale; 
eColumn.Length = oColumn.Length; 
eColumn.CodePage = oColumn.CodePage; 


oColumn.ExternalMetadataColumnID = eColumn.ID; 


Public Sub CreateExternalMetaDataColumn(ByVal output As IDTSOutput10@, ByVal outputColumnID As Integer) 
Dim oColumn As IDTSOutputColumn1@@ = output.OutputColumnCollection.GetObjectByID(outputColumnID) 

Dim eColumn As IDTSExternalMetadataColumni0e@ = output.ExternalMetadataColumnCollection.New 
eColumn.DataType = oColumn.DataType 

eColumn.Precision = oColumn.Precision 

eColumn.Scale = oColumn.Scale 

eColumn.Length = oColumn.Length 

eColumn.CodePage = oColumn.CodePage 

oColumn.ExternalMetadataColumnID = eColumn.ID 

End Sub 


Validating with External Metadata Columns 


Validation requires additional steps for components that maintain an external metadata column collection, 
because you must validate against an additional collection of columns. Validation can be divided into connected 
validation or disconnected validation. 


Connected Validation 


When a component is connected to an external data source, the columns in the input or output collections are 
verified directly against the external data source. Additionally, the columns in the external metadata collection 
must be validated. This is required because the external metadata collection can be modified by using the 
Advanced Editor in SQL Server Data Tools (SSDT), and changes made to the collection are not detectable. 
Therefore, when connected, components must make sure that the columns in the external metadata column 


collection continue to reflect the columns at the external data source. 


You may choose to hide the external metadata collection in the Advanced Editor by setting the IsUsed 
property of the collection to false. However this also hides the Column Mapping tab of the editor, which lets 
users map columns from the input or output collection to the columns in the external metadata column 
collection. Setting this property to false does not prevent developers from programmatically modifying the 
collection, but it does provide a level of protection for the external metadata column collection of a component 
that is used exclusively in SQL Server Data Tools (SSDT). 


Disconnected Validation 


When a component is disconnected from an external data source, validation is simplified because the columns 
in the input or output collection are verified directly against the columns in the external metadata collection and 
not against the external source. A component should perform disconnected validation when the connection to 
its external data source has not been established, or when the ValidateExternalMetadata property is false. 


The following code example demonstrates an implementation of a component that performs validation against 
its external metadata column collection. 


public override DTSValidationStatus Validate() 


{ 
if( this.isConnected && ComponentMetaData.ValidateExternalMetaData ) 
{ 
// TODO: Perform connected validation. 
} 
else 
it 
// TODO: Perform disconnected validation. 
} 
} 


Public Overrides Function Validate() As DTSValidationStatus 
If Me.isConnected AndAlso ComponentMetaData.ValidateExternalMetaData Then 
" TODO: Perform connected validation. 
Else 
" TODO: Perform disconnected validation. 
End IF 
End Function 


See Also 
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Component developers can raise a subset of the events defined in the IDTSComponentEvents interface by 
calling the methods exposed on the ComponentMetaData property. You can also define custom events by using 
the Eventinfos collection, and raise them during execution by using the FireCustomEvent method. This section 
describes how to create and raise an event, and provides guidelines on when you should raise events at design 
time. 


Raising Events 


Components raise events by using the Fire<X> methods of the |DTSComponentMetaData100 interface. You 
can raise events during component design and execution. Typically, during component design, the FireError and 
FireWarning methods are called during validation. These events display messages in the Error List pane of SQL 
Server Data Tools (SSDT) and provide feedback to users of the component when a component is incorrectly 
configured. 


Components can also raise events at any point during execution. Events allow component developers to provide 
feedback to users of the component as it executes. Calling the FireError method during execution is likely to fail 
the package. 


Defining and Raising Custom Events 


Defining a Custom Event 


Custom events are created by calling the Add method of the Eventinfos collection. This collection is set by the 
data flow task and provided as a property to the component developer through the PipelineComponent base 
class. This class contains custom events defined by the data flow task and custom events defined by the 
component during the RegisterEvents method. 


The custom events of a component are not persisted in the package XML. Therefore, the RegisterEvents method 
is called during both design and execution to allow the component to define the events it raises. 


The a/lowEventHandlers parameter of the Add method specifies whether the component allows 
DtsEventHandler objects to be created for the event. Note that DtsEventHandlers are synchronous. Therefore the 
component does not resume execution until an DtsEventHandler attached to the custom event has finished 
executing. If the a//owEventHandlers parameter is true, each parameter of the event is automatically made 
available to any DtsEventHandler objects through variables that are created and populated automatically by the 
SQL Server Integration Services runtime. 


Raising a Custom Event 


Components raise custom events by calling the FireCustomEvent method, and providing the name, text, and 
parameters of the event. If the a//owEventHandlers parameter is true, any DtsEventHandlers that are created for 
the custom event are executed by the SSIS run-time engine. 


Custom Event Sample 


The following code example shows a component that defines a custom event during the RegisterEvents method, 
and then raises the event at run time by calling the FireCustomEvent method. 


public override void RegisterEvents() 
{ 

string [] parameterNames = new string[2]{"RowCount", "StartTime"}; 

ushort [] parameterTypes = new ushort[2]{ DtsConvert.VarTypeFromTypeCode(TypeCode.Int32), 
DtsConvert.VarTypeFromTypeCode(TypeCode.DateTime) }; 

string [] parameterDescriptions = new string[2]{"The number of rows to sort.", "The start time of the 
Sort operation."}; 

EventInfos.Add("StartingSort","Fires when the component begins sorting the rows.",false,ref 
parameterNames, ref parameterTypes, ref parameterDescriptions) ; 


} 
public override void ProcessInput(int inputID, PipelineBuffer buffer) 
{ 
while (buffer.NextRow()) 
it 
// Process buffer rows. 
} 


IDTSEventInfo10@ eventInfo = EventInfos["StartingSort"]; 

object []Jarguments = new object[2]{buffer.RowCount, DateTime.Now }; 

ComponentMetaData.FireCustomEvent("StartingSort", "Beginning sort operation.", ref arguments, 
ComponentMetaData.Name, ref FireSortEventAgain) ; 


} 


Public Overrides Sub RegisterEvents() 

Dim parameterNames As String() = New String(2) {"RowCount", "StartTime"} 

Dim parameterTypes As System.UInt16() = New System.UInt16(2) 
{DtsConvert.VarTypeFromTypeCode(TypeCode.Int32), DtsConvert.VarTypeFromTypeCode(TypeCode.DateTime) } 

Dim parameterDescriptions As String() = New String(2) {"The number of rows to sort.", "The start time of 
the Sort operation."} 

EventInfos.Add("StartingSort", "Fires when the component begins sorting the rows.", False, parameterNames, 
parameterTypes, parameterDescriptions) 
End Sub 


Public Overrides Sub ProcessInput(ByVal inputID As Integer, ByVal buffer As PipelineBuffer) 
While buffer.NextRow 
End While 
Dim eventInfo As IDTSEventInfo100 = EventInfos("StartingSort" ) 
Dim arguments As Object() = New Object(2) {buffer.RowCount, DateTime.Now} 
ComponentMetaData.FireCustomEvent("StartingSort", _ 
"Beginning sort operation.", arguments, _ 
ComponentMetaData.Name, FireSortEventAgain) 
End Sub 


See Also 


Integration Services (SSIS) Event Handlers 
Add an Event Handler to a Package 
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Custom data flow components can post messages to an existing log entry by using the PostLogMessage 
method of the IDTSComponentMetaData100 interface. They can also present information to the user by using 
the Firelnformation method or similar methods of the IDTSComponentMetaData100 interface. However, this 
approach incurs the overhead of raising and handling additional events, and forces the user to sift through 
verbose informational messages for the messages that may be of interest to them. You can use a custom log 
entry as described below to provide distinctly labeled custom log information to users of your component. 


Registering and Using a Custom Log Entry 


Registering a Custom Log Entry 


To register a custom log entry for use by your component, override the RegisterLogEntries method of the 
PipelineComponent base class. The following example registers a custom log entry and provides a name and 
description. 


using Microsoft.SqlServer.Dts.Runtime; 


private const string MyLogEntryName = "My Custom Component Log Entry"; 


private const string MyLogEntryDescription = "Log entry from My Custom Component "; 


public override void RegisterLogEntries() 


{ 
this.LogEntryInfos.Add(MyLogEntryName, 
MyLogEntryDescription, 
Microsoft.SqlServer.Dts.Runtime.Wrapper.DTSLogEntryFrequency.DTSLEF_CONSISTENT) ; 


Imports Microsoft.SqlServer.Dts.Runtime 


Private Const MyLogEntryName As String = "My Custom Component Log Entry” 
Private Const MyLogEntryDescription As String = “Log entry from My Custom Component " 


Public Overrides Sub RegisterLogEntries() 
Me.LogEntryInfos.Add(MyLogEntryName, _ 
MyLogEntryDescription, _ 
Microsoft.SqlServer.Dts.Runtime.Wrapper.DTSLogEntryFrequency.DTSLEF_CONSISTENT) 
End Sub 


The DTSLogEntryFrequency enumeration provides a hint to the runtime about how frequently the event will be 
logged: 

e DTSLEF_OCCASIONAL: Event is logged only sometimes, not during every execution. 

e DTSLEF_CONSISTENT: Event is logged a constant number of times during every execution. 


e DTSLEF_PROPORTIONAL: Event is logged a number of times proportional to the amount of work 
completed. 


The example above uses DISLEF_CONSISTENT because the component expects to log an entry once per 
execution. 


After registering the custom log entry and adding an instance of your custom component to the data flow 
designer surface, the Logging dialog box in the designer displays a new log entry with the name "My Custom 
Component Log Entry" in the list of available log entries. 


Logging to a Custom Log Entry 


After registering the custom log entry, the component can now log custom messages. The example below writes 
a custom log entry during the PreExecute method that contains the text of a SQL statement used by the 
component. 


public override void PreExecute() 
{ 
DateTime now = DateTime.Now; 
byte[] additionalData = null; 
this .ComponentMetaData.PostLogMessage(MyLogEntryName, 
this.ComponentMetaData.Name, 
"Command Sent was: " + myCommand.CommandText, 
now, now, 9, ref additionalData) ; 


Public Overrides Sub PreExecute() 
Dim now As DateTime = DateTime.Now 
Dim additionalData As Byte() = Nothing 
Me.ComponentMetaData.PostLogMessage(MyLogEntryName, _ 
Me.ComponentMetaData.Name, _ 
"Command Sent was: " + myCommand.CommandText, _ 
now, now, 9, additionalData) 
End Sub 


Now when the user executes the package, after selecting the "My Custom Component Log Entry" in the 
Logging dialog box, the log will contain an entry clearly labeled as "User::;My Custom Component Log Entry." 
This new log entry contains the text of the SQL statement, the timestamp, and any additional data logged by the 
developer. 


See Also 
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Special IDTSOutput100 objects called error outputs can be added to components to let the component redirect 
rows that it cannot process during execution. The problems a component may encounter are generally 
categorized as errors or truncations, and are specific to each component. Components that provide error 
outputs give users of the component the flexibility to handle error conditions by filtering error rows out of the 
result set, by failing the component when a problem occurs, or by ignoring errors and continuing. 


To implement and support error outputs in a component, you must first set the UsesDispositions property of the 
component to true. Then you must add an output to the component that has its IsErrorOut property set to true. 
Finally, the component must contain code that redirects rows to the error output when errors or truncations 
occur. This topic covers these three steps and explains the differences between synchronous and asynchronous 
error outputs. 


Creating an Error Output 


You create an error output by calling the New method of the OutputCollection, and then setting the IsErrorOut 
property of the new output to true. If the output is asynchronous, nothing else must be done to the output. If 
the output is synchronous, and there is another output that is synchronous to the same input, you must also set 
the ExclusionGroup and Synchronous!nputID properties. Both properties should have the same values as the 
other output that is synchronous to the same input. If these properties are not set to a non-zero value, the rows 
provided by the input are sent to both outputs that are synchronous to the input. 


When a component encounters an error or truncation during execution, it proceeds based on the settings of the 
ErrorRowDisposition and TruncationRowDisposition properties of the input or output, or input or output 
column, where the error occurred. The value of these properties should be set by default to RD_NotUsed. When 
the error output of the component is connected to a downstream component, this property is set by the user of 
the component and lets the user control how the component handles the error or truncation. 


Populating Error Columns 


When an error output is created, the data flow task automatically adds two columns to the output column 
collection. These columns are used by components to specify the ID of the column that caused the error or 
truncation, and to provide the component-specific error code. These columns are generated automatically, but 
the values contained in the columns must be set by the component. 


The method used to set the values of these columns depends on whether the error output is synchronous or 
asynchronous. Components with synchronous outputs call the DirectErrorRow method, discussed in more detail 
in the next section, and provide the error code and error column values as parameters. Components with 
asynchronous outputs have two choices for setting the values of these columns. They can either call the 
SetErrorlnfo method of the output buffer and supply the values, or locate the error columns in the buffer by 
using FindColumnByLineagelD and set the values for the columns directly. However, because the names of the 
columns may have been changed, or their location in the output column collection may have been modified, the 
latter method may not be reliable. The SetErrorinfo method automatically sets the values in these error columns 
without having to locate them manually. 


If you need to obtain the error description that corresponds to a specific error code, you can use the 
GetErrorDescription method of the IDTSComponentMetaData1 00 interface, available through the component's 


ComponentMetaData property. 


The following code examples show a component that has an input and two outputs, including an error output. 
The first example shows how to create an error output that is synchronous to the input. The second example 


shows how to create an error output that is asynchronous. 


public override void ProvideComponentProperties() 
{ 
// Specify that the component has an error output. 
ComponentMetaData.UsesDispositions = true; 
// Create the input. 
IDTSInput10@ input = ComponentMetaData.InputCollection.New() ; 
input.Name = "Input"; 
input.ErrorRowDisposition = DTSRowDisposition.RD_NotUsed; 
input.ErrorOrTruncationOperation = "A string describing the possible error or truncation that may occur 


during execution."; 


// Create the default output. 

IDTSOutput190e@ output = ComponentMetaData.OutputCollection.New(); 
output.Name = "Output"; 

output.SynchronousInputID = input.ID; 

output.ExclusionGroup = 1; 


// Create the error output. 

IDTSOutput19@ errorOutput = ComponentMetaData.OutputCollection.New(); 
errorOutput.IsErrorOut = true; 

errorOutput.Name = “ErrorOutput"; 

errorOutput.SynchronousInputID = input.ID; 

errorOutput.ExclusionGroup = 1; 


Public Overrides Sub ProvideComponentProperties() 


" Specify that the component has an error output. 
ComponentMetaData.UsesDispositions = True 


W 


Dim input As IDTSInput1@@ = ComponentMetaData.InputCollection.New 


" Create the input. 

input.Name = "Input" 

input.ErrorRowDisposition = DTSRowDisposition.RD_NotUsed 

input.ErrorOrTruncationOperation = "A string describing the possible error or truncation that may occur 


during execution." 


" Create the default output. 

Dim output As IDTSOutput10@ = ComponentMetaData.OutputCollection.New 
output.Name = "Output" 

output.SynchronousInputID = input.ID 

output.ExclusionGroup = 1 

" Create the error output. 

Dim errorOutput As IDTSOutput100 = ComponentMetaData.OutputCollection.New 
errorOutput.IsErrorOut = True 

errorOutput.Name = "ErrorOutput" 

errorOutput.SynchronousInputID = input.ID 

errorOutput.ExclusionGroup = 1 


End Sub 


The following code example creates an error output that is asynchronous. 


public override void ProvideComponentProperties() 


{ 


// Specify that the component has an error output. 
ComponentMetaData.UsesDispositions = true; 


// Create the input. 

IDTSInput10@ input = ComponentMetaData.InputCollection.New(); 

input.Name = "Input"; 

input.ErrorRowDisposition = DTSRowDisposition.RD_NotUsed; 

input.ErrorOrTruncationOperation = "A string describing the possible error or truncation that may occur 
during execution."; 


// Create the default output. 
IDTSOutput19e@ output = ComponentMetaData.OutputCollection.New(); 
output.Name = "Output"; 


// Create the error output. 

IDTSOutput10@ errorOutput = ComponentMetaData.OutputCollection.New() ; 
errorOutput.Name = “ErrorOutput"; 

errorOutput.IsErrorOut = true; 


Public Overrides Sub ProvideComponentProperties() 


" Specify that the component has an error output. 
ComponentMetaData.UsesDispositions = True 


Create the input. 
Dim input As IDTSInput1@@ = ComponentMetaData.InputCollection.New 


" Create the default output. 

input.Name = "Input" 

input.ErrorRowDisposition = DTSRowDisposition.RD_NotUsed 

input.ErrorOrTruncationOperation = "A string describing the possible error or truncation that may occur 
during execution." 


Create the error output. 

Dim output As IDTSOutput10@ = ComponentMetaData.OutputCollection.New 
output.Name = "Output" 

Dim errorOutput As IDTSOutput10@ = ComponentMetaData.OutputCollection.New 
errorOutput.Name = "ErrorOutput" 

errorOutput.IsErrorOut = True 


End Sub 


Redirecting a Row to an Error Output 


After adding an error output to a component, you must provide code that handles the error or truncation 
conditions specific to the component and redirects the error or truncation rows to the error output. You can do 
this in two ways, depending on whether the error output is synchronous or asynchronous. 


Redirecting a Row with Synchronous Outputs 

Rows are sent to synchronous outputs by calling the DirectErrorRow method of the PipelineBuffer class. The 
method call includes as parameters the ID of the error output, the component-defined error code, and the index 
of the column that the component was unable to process. 


The following code example demonstrates how to direct a row in a buffer to a synchronous error output using 
the DirectErrorRow method. 


public override void ProcessInput(int inputID, PipelineBuffer buffer) 


{ 
IDTSInput10@ input = ComponentMetaData.InputCollection.GetObjectByID(inputID) ; 
// This code sample assumes the component has two outputs, one the default, 
// the other the error output. If the errorOutputIndex returned from GetErrorOutputInfo 
// is ®, then the default output is the second output in the collection. 
int defaultOutputID = -1; 
int errorOutputID = -1; 
int errorOutputIndex = -1; 
GetErrorOutputInfo(ref errorOutputID, ref errorOutputIndex) ; 
if (errorOutputIndex == @) 
defaultOutputID = ComponentMetaData.OutputCollection[1].1D; 
else 
defaultOutputID = ComponentMetaData.OutputCollection[@].1ID; 
while (buffer.NextRow() ) 
{ 
try 
{ 
// TODO: Implement code to process the columns in the buffer row. 
// Ideally, your code should detect potential exceptions before they occur, rather 
// than having a generic try/catch block such as this. 
// However, because the error or truncation implementation is specific to each component, 
// this sample focuses on actually directing the row, and not a single error or truncation. 
// Unless an exception occurs, direct the row to the default 
buffer.DirectRow(defaultOutputID) ; 
} 
catch 
{ 
// Yes, has the user specified to redirect the row? 
if (input.ErrorRowDisposition == DTSRowDisposition.RD_RedirectRow) 
ib 
// Yes, direct the row to the error output. 
// TODO: Add code to include the errorColumnIndex. 
buffer.DirectErrorRow(errorOutputID, @, errorColumnIndex) ; 
} 
else if (input.ErrorRowDisposition == DTSRowDisposition.RD FailComponent | | 
input.ErrorRowDisposition == DTSRowDisposition.RD_NotUsed) 
{ 
// No, the user specified to fail the component, or the error row disposition was not 
set. 


throw new Exception("An error occurred, and the DTSRowDisposition is either not set, or 
is set to fail component."); 


1; 

else 

{ 
// No, the user specified to ignore the failure so 
// direct the row to the default output. 
buffer.DirectRow(defaultOutputID) ; 

} 
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Public Overrides Sub ProcessInput(ByVal inputID As Integer, ByVal buffer As PipelineBuffer) 
Dim input As IDTSInput10@ = ComponentMetaData.InputCollection.GetObjectByID(inputID) 


" This code sample assumes the component has two outputs, one the default, 

" the other the error output. If the errorOutputIndex returned from GetErrorOutputInfo 
"is @, then the default output is the second output in the collection. 

Dim defaultOutputID As Integer = -1 

Dim errorOutputID As Integer = -1 

Dim errorOutputIndex As Integer = -1 


GetErrorOutputInfo(errorOutputID, errorOutputIndex) 


If errorOutputIndex = @ Then 

defaultOutputID = ComponentMetaData.OutputCollection(1).ID 
Else 

defaultOutputID = ComponentMetaData.OutputCollection(@).ID 
End If 


While buffer.NextRow 
Try 
" TODO: Implement code to process the columns in the buffer row. 


Ideally, your code should detect potential exceptions before they occur, rather 

than having a generic try/catch block such as this. 

" However, because the error or truncation implementation is specific to each component, 
this sample focuses on actually directing the row, and not a single error or truncation. 


" Unless an exception occurs, direct the row to the default 
buffer .DirectRow(defaultOutputID) 
Catch 
"Yes, has the user specified to redirect the row? 
If input.ErrorRowDisposition = DTSRowDisposition.RD_RedirectRow Then 
" Yes, direct the row to the error output. 
" TODO: Add code to include the errorColumnIndex. 
buffer.DirectErrorRow(errorOutputID, @, errorColumnIndex) 
Else 
If input.ErrorRowDisposition = DTSRowDisposition.RD_FailComponent OrElse input.ErrorRowDisposition 
= DTSRowDisposition.RD_NotUsed Then 
"No, the user specified to fail the component, or the error row disposition was not set. 
Throw New Exception("An error occurred, and the DTSRowDisposition is either not set, or is set to 
fail component.") 
Else 
" No, the user specified to ignore the failure so 
" direct the row to the default output. 
buffer .DirectRow(defaultOutputID) 
End If 
End If 
End Try 
End While 
End Sub 


Redirecting a Row with Asynchronous Outputs 


Instead of directing rows to an output, as is done with synchronous error outputs, components with 
asynchronous outputs send a row to an error output by explicitly adding a row to the output PipelineBuffer. 
Implementing a component that uses asynchronous error outputs requires adding columns to the error output 
that are provided to downstream components, and caching the output buffer for the error output that is 
provided to the component during the PrimeOutput method. The details of implementing a component with 
asynchronous outputs are covered in detail in the topic Developing a Custom Transformation Component with 
Asynchronous Outputs. If columns are not explicitly added to the error output, the buffer row that is added to 


the output buffer contains only the two error columns. 


To send a row to an asynchronous error output, you must add a row to the error output buffer. Sometimes, a 
row may have already been added to the non-error output buffer and you must remove this row by using the 


RemoveRow method. Next you set the output buffer columns values, and finally, you call the SetErrorinfo 
method to provide the component-specific error code and the error column value. 


The following example demonstrates how to use an error output for a component with asynchronous outputs. 
When the simulated error occurs, the component adds a row to the error output buffer, copies the values that 
were previously added to the non-error output buffer to the error output buffer, removes the row that was 
added to the non-error output buffer, and, finally, sets the error code and error column values by calling the 
SetErrorInfo method. 


int []columnIndex; 
int errorOutputID = -1; 
int errorOutputIndex = -1; 


public override void PreExecute() 


{ 
IDTSOutput1ee defaultOutput = null; 


this.GetErrorOutputInfo(ref errorOutputID, ref errorOutputIndex) ; 
foreach (IDTSOutput10@ output in ComponentMetaData.OutputCollection) 


{ 
if (output.ID != errorOutputID) 


defaultOutput = output; 


columnIndex = new int[defaultOutput.OutputColumnCollection. Count]; 


for(int col =® ; col < defaultOutput.OutputColumnCollection.Count; col++) 


{ 
IDTSOutputColumn1e@e@ column = defaultOutput.OutputColumnCollection[col]; 


columnIndex[col] = BufferManager.FindColumnByLineageID(defaultOutput.Buffer, column.LineageID) ; 


public override void PrimeOutput(int outputs, int[] outputIDs, PipelineBuffer[] buffers) 
{ 


for( int x=@; x < outputs; x++ ) 


{ 
if (outputIDs[x] == errorOutputID) 
this.errorBuffer = buffers[x]; 
else 
this.defaultBuffer = buffers[x]; 
} 


int rows = 10@; 


Random random = new Random(System.DateTime.Now.Millisecond) ; 


for (int row = @; row < rows; row++) 


{ 
try 


defaultBuffer.AddRow() ; 


for (int x = @; x < columnIndex.Length; x++) 
defaultBuffer[columnIndex[x]] = random.Next(); 


// Simulate an error. 
if ((row % 2) == @) 
throw new Exception("A simulated error."); 

} 
catch 
if 

// Add a row to the error buffer. 

errorBuffer.AddRow() ; 


// Get the values from the default buffer 


// and copy them to the error buffer. 
for (int x = @; x < columnIndex.Length; x++) 
errorBuffer[columnIndex[x]] = defaultBuffer[columnIndex[x]]; 


// Set the error information. 
errorBuffer.SetErrorInfo(errorOutputID, 1, 9); 


// Remove the row that was added to the default buffer. 
defaultBuffer.RemoveRow() ; 


if (defaultBuffer != null) 
defaultBuffer.SetEndOfRowset (); 


if (errorBuffer != null) 
errorBuffer. SetEndOfRowset(); 


Private columnIndex As Integer() 
Private errorOutputID As Integer = -1 
Private errorOutputIndex As Integer = -1 


Public Overrides Sub PreExecute() 

Dim defaultOutput As IDTSOutput1@@ = Nothing 

Me.GetErrorOutputInfo(errorOutputID, errorOutputIndex) 

For Each output As IDTSOutput10@ In ComponentMetaData.OutputCollection 
If Not (output.ID = errorOutputID) Then 

defaultOutput = output 

End If 

Next 

columnIndex = New Integer(defaultOutput.OutputColumnCollection.Count) {} 

Dim col As Integer = @ 

While col < defaultOutput.OutputColumnCollection.Count 
Dim column As IDTSOutputColumn1e@ = defaultOutput.OutputColumnCollection(col) 
columnIndex(col) = BufferManager.FindColumnByLineageID(defaultOutput.Buffer, column.LineageID) 
System.Math.Min(System. Threading. Interlocked.Increment(col),col-1) 

End While 

End Sub 


Public Overrides Sub PrimeOutput(ByVal outputs As Integer, ByVal outputIDs As Integer(), ByVal buffers As 
PipelineBuffer()) 
Dim x As Integer = @ 
While x < outputs 
If outputIDs(x) = errorOutputID Then 
Me.errorBuffer = buffers(x) 


Else 
Me.defaultBuffer = buffers(x) 
End If 
System.Math.Min(System. Threading. Interlocked.Increment(x),x-1) 
End While 


Dim rows As Integer = 100 
Dim random As Random = New Random(System.DateTime.Now.Millisecond) 
Dim row As Integer = 0 
While row < rows 
Try 
defaultBuffer.AddRow 
Dim x As Integer = @ 
While x < columnIndex.Length 
defaultBuffer(columnIndex(x)) = random.Next 
System.Math.Min(System. Threading. Interlocked.Increment(x),x-1) 
End While 
" Simulate an error. 
If (row Mod 2) = @ Then 
Throw New Exception("A simulated error.") 
End If 
Catch 


Add a row to the error buffer. 
errorBuffer . AddRow 
" Get the values from the default buffer 
"and copy them to the error buffer. 
Dim x As Integer = @ 
While x < columnIndex.Length 
errorBuffer(columnIndex(x)) = defaultBuffer(columnIndex(x) ) 
System.Math.Min(System. Threading. Interlocked.Increment(x),x-1) 
End While 
" Set the error information. 
errorBuffer.SetErrorInfo(errorOutputID, 1, @) 
" Remove the row that was added to the default buffer. 
defaultBuffer.RemoveRow 
End Try 
System.Math.Min(System. Threading. Interlocked. Increment (row), row-1) 
End While 
If Not (defaultBuffer Is Nothing) Then 
defaultBuffer.SetEndOfRowset 
End If 
If Not (errorBuffer Is Nothing) Then 
errorBuffer .SetEndOfRowset 
End If 
End Sub 


See Also 


Error Handling in Data 
Using Error Outputs 


Developing a User Interface for a Data Flow 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Component developers can provide a custom user interface for a component, which is displayed in SQL Server 
Data Tools (SSDT) when the component is edited. Implementing a custom user interface provides you with 
notification when the component is added to or deleted from a data flow task, and when help is requested for 
the component. 


If you do not provide a custom user interface for your component, users can still configure the component and 
its custom properties by using the Advanced Editor. You can ensure that the Advanced Editor allows users to edit 
custom property values appropriately by using the TypeConverter and UlTypeEditor properties of the 
IDTSCustomProperty100 when appropriate. For more information, see "Creating Custom Properties" in Design- 
time Methods of a Data Flow Component. 


Setting the UlTypeName Property 


To provide a custom user interface, the developer must set the UlTypeName property of the 
DtsPipelineComponentAttribute to the name of a class that implements the |DtsComponentUI interface. When 
this property is set by the component, SQL Server Integration Services loads and calls the custom user interface 
when the component is edited in SSIS Designer. 


The UlTypeName property is a comma-delimited string that identifies the fully qualified name of the type. The 
following list shows, in order, the elements that identify the type: 


e Type name 

e Assembly name 
e File version 

e Culture 


e Public key token 


The following code example shows a class that derives from the PipelineComponent base class and specifies the 
UlTypeName property. 


[DtsPipelineComponent ( 

DisplayName="SampleComponent", 
UITypeName="MyNamespace.MyComponentUIClassName ,MyAssemblyName, Version=1.0.0.0,Culture=neutral, PublickeyToken 
SO0COne 5 

ComponentType = ComponentType. Transform) ] 

public class SampleComponent : PipelineComponent 

{ 

//TODO: Implement the component here. 

t 


<DtsPipelineComponent (DisplayName="SampleComponent", _ 
UITypeName="MyNamespace.MyComponentUIClassName , MyAssemblyName, Version=1.0.0.0,Culture=neutral, PublickeyToken 
=abcd...", ComponentType=ComponentType.Transform)> _ 
Public Class SampleComponent 

Inherits PipelineComponent 

End Class 


Implementing the IDtsComponentUl Interface 


The IDtsComponentUI interface contains methods that SSIS Designer calls when a component is added, deleted, 
and edited. Component developers can provide code in their implementation of these methods to interact with 
users of the component. 


This class is typically implemented in an assembly separate from the component itself. Although use of a 
separate assembly is not required, this lets the developer build and deploy the component and the user interface 
independently of each other, and keeps the binary footprint of the component small. 


Implementing a custom user interface gives the component developer more control over the component as it is 
edited in SSIS Designer. For example, a component can add code to the New method, which is called when a 
component is initially added to a data flow task, and display a wizard that guides the user through the initial 
configuration of the component. 


After you have created a class that implements the |DtsComponentUI interface, you must add code to respond 
to user interaction with the component. The Initialize method provides the IDTSComponentMetaData1 00 
interface of the component, and is called before the New and Edit methods. This reference should be stored ina 
private member variable and used to modify the component's metadata thereafter. 


Modifying a Component and Persisting Changes 


The IDTSComponentMetaData100 interface is provided as a parameter to the Initialize method. This reference 
should be cached in a member variable by the user interface code, and then used to modify the component in 
response to user interaction with the user interface. 


Although you can modify the component directly through the IDTSComponentMetaData1 00 interface, it is 
better to create an instance of the CManagedComponentWrapper by using the Instantiate method. When you 
edit the component directly by using the interface, you bypass the component's validation safeguards. The 
advantage of using the design-time instance of the component through the CManagedComponentWrapper is 
that you ensure that the component has control over the changes made to it. 


The return value of the Edit method determines whether changes made to a component are persisted or 
discarded. When this method returns false, all changes are discarded; true persists the changes to the 
component and marks the package as needing to be saved. 


Using the Services of the SSIS Designer 


The IServiceProvider parameter of the Initialize method provides access to the following services of SSIS 


Designer: 
SERVICE DESCRIPTION 
IDtsClipboardService Used to determine whether the component was generated 
as part of a copy/paste or cut/paste operation. 
|DtsConnectionService Used to access existing connections or to create new 


connections in the package. 


SERVICE DESCRIPTION 


|ErrorCollectionService Used to capture events from data flow components when 
you need to capture all the errors and warnings raised by 
the component instead of receiving only the last error or 
warning. 


IDtsVariableService Used to access existing variables or to create new variables 
in the package. 


IDtsPipelineEnvironmentService Used by data flow components to access the parent Data 
Flow task and other components in the data flow. This 
feature could be used to develop a component like the 
Slowly Changing Dimension Wizard that creates and 
connects additional data flow components as needed. 


These services provide component developers the ability to access and create objects in the package in which 
the component is loaded. 


Sample 


The following code example shows the integration of a custom user interface class that implements the 
|IDtsComponentUl interface, and a Windows form that serves as the editor for a component. 


Custom User Interface Class 

The following code shows the class that implements the IDtsComponentUI interface. The Edit method creates 
the component editor and then displays the form. The return value of the form determines whether changes to 
the component are persisted. 


using System; 

using System.Windows. Forms; 

using Microsoft.SqlServer.Dts.Runtime; 

using Microsoft.SqlServer.Dts.Pipeline.Design; 
using Microsoft.SqlServer.Dts.Pipeline.Wrapper; 


namespace Microsoft.Samples.SqlServer.Dts 


{ 
public class SampleComponentUI : IDtsComponentUI 
{ 
IDTSComponentMetaData1ee md; 
IServiceProvider sp; 
public void Help(System.Windows.Forms.IWin32Window parentWindow) 
{ 
} 
public void New(System.Windows.Forms.IWin32Window parentWindow) 
{ 
} 
public void Delete(System.Windows.Forms.IWin32Window parentWindow) 
{ 
i; 
public bool Edit(System.Windows.Forms.IWin32Window parentWindow, Variables vars, Connections cons) 
{ 
// Create and display the form for the user interface. 
SampleComponentUIForm componentEditor = new SampleComponentUIForm(cons, vars, md); 
DialogResult result = componentEditor.ShowDialog(parentWindow) ; 
if (result == DialogResult.OK) 
return true; 
return false; 
} 
public void Initialize(IDTSComponentMetaData10@ dtsComponentMetadata, IServiceProvider 
serviceProvider) 
tb 
// Store the component metadata. 
this.md = dtsComponentMetadata; 
} 
} 


Imports System 

Imports System.Windows.Forms 

Imports Microsoft.SqlServer.Dts.Runtime 

Imports Microsoft.SqlServer.Dts.Pipeline.Design 
Imports Microsoft.SqlServer.Dts.Pipeline.Wrapper 


Namespace Microsoft.Samples.SqlServer.Dts 


Public Class SampleComponentUI 
Implements IDtsComponentUL 
Private md As IDTSComponentMetaData1ee 
Private sp As IServiceProvider 


Public Sub Help(ByVal parentWindow As System.Windows.Forms. IWin32Window) 
End Sub 


Public Sub New(ByVal parentWindow As System.Windows.Forms.IWin32Window) 
End Sub 


Public Sub Delete(ByVal parentWindow As System.Windows. Forms. IWin32Window) 
End Sub 


Public Function Edit(ByVal parentWindow As System.Windows.Forms.IWin32Window, ByVal vars As Variables, 
ByVal cons As Connections) As Boolean 
" Create and display the form for the user interface. 
Dim componentEditor As SampleComponentUIForm = New SampleComponentUIForm(cons, vars, md) 
Dim result As DialogResult = componentEditor.ShowDialog(parentWindow) 
If result = DialogResult.OK Then 
Return True 
End If 
Return False 
End Function 


Public Sub Initialize(ByVal dtsComponentMetadata As IDTSComponentMetaData1@@, ByVal serviceProvider As 


IServiceProvider) 
Me.md = dtsComponentMetadata 
End Sub 
End Class 


End Namespace 


Custom Editor 


The following code shows the implementation of the Windows form that is shown during the call to the Edit 
method. 


using System; 

using System.Drawing; 

using System.Collections; 
using System.ComponentModel ; 
using System.Windows. Forms; 
using System.Data; 


using Microsoft.SqlServer.Dts.Pipeline.Wrapper; 
using Microsoft.SqlServer.Dts.Runtime; 


namespace Microsoft.Samples.SqlServer.Dts 


{ 
public partial class SampleComponentUIForm : System.Windows.Forms.Form 
{ 
private Connections connections; 
private Variables variables; 
private IDTSComponentMetaData10@ metaData; 
private CManagedComponentWrapper designTimeInstance; 
private System.ComponentModel.IContainer components = null; 
public SampleComponentUIForm( Connections cons, Variables vars, IDTSComponentMetaData10@ md) 
{ 
variables = vars; 
connections = cons; 
metaData = md; 
yr 
private void btnOk_Click(object sender, System.EventArgs e) 
{ 
if (designTimeInstance == null) 
designTimeInstance = metaData.Instantiate(); 
designTimeInstance.SetComponentProperty( "CustomProperty", txtCustomPropertyValue. Text) ; 
this.Close(); 
} 
private void btnCancel_Click(object sender, System.EventArgs e) 
{ 
this.Close(); 
J 
} 


Imports System 

Imports System.Drawing 

Imports System.Collections 

Imports System.ComponentModel 

Imports System.Windows.Forms 

Imports System.Data 

Imports Microsoft.SqlServer.Dts.Pipeline.Wrapper 
Imports Microsoft.SqlServer.Dts.Runtime 


Namespace Microsoft.Samples.SqlServer.Dts 


Public Partial Class SampleComponentUIForm 
Inherits System.Windows.Forms.Form 
Private connections As Connections 
Private variables As Variables 
Private metaData As IDTSComponentMetaData10o 
Private designTimeInstance As CManagedComponentWrapper 
Private components As System.ComponentModel.IContainer = Nothing 


Public Sub New(ByVal cons As Connections, ByVal vars As Variables, ByVal md As IDTSComponentMetaData100) 
variables = vars 
connections = cons 
metaData = md 

End Sub 


Private Sub btnOk_Click(ByVal sender As Object, ByVal e As System.EventArgs) 
If designTimeInstance Is Nothing Then 
designTimeInstance = metaData.Instantiate 
End If 
designTimeInstance.SetComponentProperty("CustomProperty", txtCustomPropertyValue. Text) 
Me.Close 
End Sub 


Private Sub btnCancel_Click(ByVal sender As Object, ByVal e As System.EventArgs) 
Me.Close 
End Sub 
End Class 


End Namespace 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Packages that were created with an older version of your component may contain metadata that is no longer 
valid, such as custom properties whose usage has been modified in newer versions of the component. You can 
override the PerformUpgrade method of the PipelineComponent base class to update the metadata previously 
saved in older packages to reflect the current properties of your component. 





NOTE 


When you recompile a custom component for a new version of Integration Services, you do not have to change the value 
of the CurrentVersion property if the component's properties have not changed. 





Example 


The following sample contains code from version 2.0 of a fictitious data flow component. The new version 
number is defined in the CurrentVersion property of the DtsPipelineComponentAttribute. The component has a 
property that defines how numeric values that exceed a threshold are to be handled. In version 1.0 of the 
fictitious component, this property was named RaiseErrorOnInvalidValue and accepted a Boolean value of true 
or false. In version 2.0 of the fictitious component, the property has been renamed to InvalidValueHandling and 


accepts one of four possible values from a custom enumeration. 
The overridden PerformUpgrade method in the following sample performs the following actions: 
e Gets the current version of the component. 


e Gets the value of the old custom property. 


Removes the old property from the custom property collection. 


Sets the value of the new custom property based on the value of the old property, if possible. 


Sets the version metadata to the current version of the component. 








NOTE 


The data flow engine passes its own version number into the PerformUpgrade method in the pipelineVersion parameter. 
This parameter is not useful in version 1.0 of Integration Services, but may become useful in subsequent versions. 











The sample code uses only the two enumeration values that map directly to the prior Boolean values for the 
custom property. Users can select the other available enumeration values through the component's custom user 
interface, in the Advanced Editor, or programmatically. For information on displaying enumeration values for a 
custom property in the Advanced Editor, see "Creating Custom Properties" in Design-time Methods of a Data 
Flow Component. 


Imports Microsoft.SqlServer.Dts.Pipeline 
Imports Microsoft.SqlServer.Dts.Pipeline.Wrapper 


<DtsPipelineComponent (ComponentType:=ComponentType. Transform, CurrentVersion:=2)> _ 
Public Class PerformUpgrade 

Inherits PipelineComponent 

" Define the set of possible values for the new custom property. 
Private Enum InvalidValueHandling 

Ignore 

FireInformation 

FireWarning 

FireError 
End Enum 


Public Overloads Overrides Sub PerformUpgrade(ByVal pipelineVersion As Integer) 
" Obtain the current component version from the attribute. 

Dim componentAttribute As DtsPipelineComponentAttribute = _ 
CType(Attribute.GetCustomAttribute(Me.GetType, _ 
GetType(DtsPipelineComponentAttribute), False), _ 
DtsPipelineComponentAttribute) 

Dim currentVersion As Integer = componentAttribute.CurrentVersion 


If the component version saved in the package is less than 


the current version, Version 2, perform the upgrade. 
If ComponentMetaData.Version < currentVersion Then 


" Get the current value of the old custom property, RaiseErrorOnInvalidValue, 
"and then remove the property from the custom property collection. 
Dim oldValue As Boolean = False 
Try 
Dim oldProperty As IDTSCustomProperty10@ = _ 
ComponentMetaData.CustomPropertyCollection("RaiseErrorOnInvalidValue" ) 
oldValue = CType(oldProperty.Value, Boolean) 
ComponentMetaData.CustomPropertyCollection.RemoveObjectByIndex("RaiseErrorOnInvalidValue" ) 
Catch ex As Exception 
" If the old custom property is not available, ignore the error. 
End Try 


Set the value of the new custom property, InvalidValueHandling, 
"by using the appropriate enumeration value. 
Dim newProperty As IDTSCustomProperty10@ = _ 
ComponentMetaData.CustomPropertyCollection("InvalidValueHandling" ) 
If oldValue = True Then 
newProperty.Value = InvalidValueHandling.FireError 
Else 
newProperty.Value = InvalidValueHandling. Ignore 


End If 


End If 


Update the saved component version metadata to the current version. 
ComponentMetaData.Version = currentVersion 


End Sub 


End Class 


using System; 
using Microsoft.SqlServer.Dts.Pipeline; 
using Microsoft.SqlServer.Dts.Pipeline.Wrapper; 


[DtsPipelineComponent(ComponentType = ComponentType.Transform, CurrentVersion = 2)] 
public class PerformUpgradeCs : 
PipelineComponent 


// Define the set of possible values for the new custom property. 


private enum InvalidValueHandling 
{ 

Ignore, 

FireInformation, 

FireWarning, 

FireError 


}3 


public override void PerformUpgrade(int pipelineVersion) 


af 


// Obtain the current component version from the attribute. 
DtsPipelineComponentAttribute componentAttribute = 
(DtsPipelineComponentAttribute)Attribute.GetCustomAttribute(this.GetType(), 
typeof (DtsPipelineComponentAttribute), false); 
int currentVersion = componentAttribute.CurrentVersion; 


// If the component version saved in the package is less than 
// the current version, Version 2, perform the upgrade. 
if (ComponentMetaData.Version < currentVersion) 


// Get the current value of the old custom property, RaiseErrorOnInvalidValue, 
// and then remove the property from the custom property collection. 
{ 
bool oldValue = false; 
try 
{ 
IDTSCustomProperty100 oldProperty = 
ComponentMetaData.CustomPropertyCollection["RaiseErrorOnInvalidValue" ] ; 
oldValue = (bool)oldProperty.Value; 
ComponentMetaData.CustomPropertyCollection.RemoveObjectByIndex("RaiseErrorOnInvalidValue") ; 


} 


catch (Exception ex) 


il 


// If the old custom property is not available, ignore the error. 


// Set the value of the new custom property, InvalidValueHandling, 

// by using the appropriate enumeration value. 

IDTSCustomProperty1@@ newProperty = 
ComponentMetaData.CustomPropertyCollection["InvalidValueHandling" ]; 

if (oldValue == true) 


{ 
newProperty.Value = InvalidValueHandling.FireError; 
} 
else 
il 
newProperty.Value = InvalidValueHandling.Ignore; 
t 
} 


// Update the saved component version metadata to the current version. 
ComponentMetaData.Version = currentVersion; 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Microsoft SQL Server Integration Services gives developers the ability to write custom destination components 
that can connect to and store data in any custom data source. Custom destination components are useful when 
you need to connect to data sources that cannot be accessed by using one of the existing source components 
included with Integration Services. 


Destination components have one or more inputs and zero outputs. At design time, they create and configure 
connections and read column metadata from the external data source. During execution, they connect to their 
external data source and add rows that are received from the components upstream in the data flow to the 
external data source. If the external data source exists prior to execution of the component, the destination 
component must also ensure that the data types of the columns that the component receives match the data 
types of the columns at the external data source. 


This section discusses the details of how to develop destination components, and provides code examples to 
clarify important concepts. For a general overview of data flow component development, see Developing a 
Custom Data Flow Component. 


Design Time 


Implementing the design-time functionality of a destination component involves specifying a connection to an 
external data source and validating that the component has been correctly configured. By definition, a 
destination component has one input and possibly one error output. 


Creating the Component 


Destination components connect to external data sources by using ConnectionManager objects defined in a 
package. The destination component indicates its requirement for a connection manager to the SSIS Designer, 
and to users of the component, by adding an element to the RuntimeConnectionCollection collection of the 
ComponentMetaData. This collection serves two purposes: first, it advertises the need for a connection manager 
to SSIS Designer; then, after the user has selected or created a connection manager, it holds a reference to the 
connection manager in the package that is being used by the component. When an IDTSRuntimeConnection100 
is added to the collection, the Advanced Editor displays the Connection Properties tab, to prompt the user 
to select or create a connection in the package for use by the component. 


The following code sample shows an implementation of ProvideComponentProperties that adds an input, and 
then adds a IDTSRuntimeConnection100 object to the RuntimeConnectionCollection. 


using System; 

using Microsoft.SqlServer.Dts.Pipeline; 

using Microsoft.SqlServer.Dts.Pipeline.Wrapper; 
using Microsoft.SqlServer.Dts.Runtime; 


namespace Microsoft.Samples.SqlServer.Dts 
{ 
[DtsPipelineComponent(DisplayName = "Destination Component", ComponentType 
=ComponentType.DestinationAdapter) ] 
public class DestinationComponent : PipelineComponent 
{ 
public override void ProvideComponentProperties() 
{ 
// Reset the component. 
base.RemoveAllInputsOutputsAndCustomProperties() ; 
ComponentMetaData.RuntimeConnectionCollection.RemoveA11() ; 


IDTSInput10@ input = ComponentMetaData.InputCollection.New() ; 
input.Name = "Input"; 


IDTSRuntimeConnection10@ connection = ComponentMetaData.RuntimeConnectionCollection.New(); 
connection.Name = "ADO.net"; 


Imports System 

Imports System.Data 

Imports System.Data.SqlClient 

Imports Microsoft.SqlServer.Dts.Pipeline 

Imports Microsoft.SqlServer.Dts.Pipeline.Wrapper 
Imports Microsoft.SqlServer.Dts.Runtime 


Namespace Microsoft.Samples.SqlServer.Dts 


<DtsPipelineComponent (DisplayName:="Destination Component", 
ComponentType: =ComponentType.DestinationAdapter)> _ 
Public Class DestinationComponent 
Inherits PipelineComponent 


Public Overrides Sub ProvideComponentProperties() 


" Reset the component. 
Me.RemoveAllInputsOutputsAndCustomProperties() 


ComponentMetaData.RuntimeConnectionCollection.RemoveA11() 


Dim input As IDTSInput1@@ = ComponentMetaData.InputCollection.New() 
input.Name = "Input" 


Dim connection As IDTSRuntimeConnection10@ = ComponentMetaData.RuntimeConnectionCollection.New() 
connection.Name = "ADO.net" 


End Sub 
End Class 
End Namespace 
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Connecting to an External Data Source 


After a connection is added to the RuntimeConnectionCollection, you override the AcquireConnections method 
to establish a connection to the external data source. This method Is called at design time and at run time. The 
component must establish a connection to the connection manager specified by the run-time connection, and 
subsequently, to the external data source. Once established, the component should cache the connection 
internally and release it when ReleaseConnections is called. Developers override this method, and release the 


connection established by the component during AcquireConnections. Both of these methods, 
ReleaseConnections and AcquireConnections, are called at design time and at run time. 


The following code example shows a component that connects to an ADO.NET connection in the 
AcquireConnections method, and then closes the connection in ReleaseConnections. 


using Microsoft.SqlServer.Dts.Runtime.Wrapper ; 
private SqlConnection sqlConnection; 


public override void AcquireConnections(object transaction) 
{ 
if (ComponentMetaData.RuntimeConnectionCollection[@].ConnectionManager != null) 
{ 
ConnectionManager cm = 
Microsoft.SqlServer.Dts.Runtime.DtsConvert.GetWrapper (ComponentMetaData.RuntimeConnectionCollection[@].Conne 
ctionManager) ; 
ConnectionManagerAdoNet cmado = cm.InnerObject as ConnectionManagerAdoNet ; 


if (cmado == null) 


throw new Exception("The ConnectionManager " + cm.Name + " is not an ADO.NET connection."); 


sqlcConnection = cmado.AcquireConnection(transaction) as SqlConnection; 
sqlConnection.Open(); 


} 
} 
public override void ReleaseConnections() 
{ 
if (sqlConnection != null && sqlConnection.State != ConnectionState.Closed) 
sqlcConnection.Close(); 
} 


Imports Microsoft.SqlServer.Dts.Runtime.Wrapper 
Private sqlConnection As SqlConnection 
Public Overrides Sub AcquireConnections(ByVal transaction As Object) 
If IsNothing(ComponentMetaData.RuntimeConnectionCollection(@).ConnectionManager) = False Then 
Dim cm As ConnectionManager = 
DtsConvert.GetWrapper (ComponentMetaData.RuntimeConnectionCollection(@) .ConnectionManager ) 
Dim cmado As ConnectionManagerAdoNet = CType(cm.InnerObject, ConnectionManagerAdoNet ) 
If IsNothing(cmado) Then 


Throw New Exception("The ConnectionManager " + cm.Name + 
End If 


is not an ADO.NET connection.") 
sqlConnection = CType(cmado.AcquireConnection(transaction), SqlConnection) 
sqlConnection.Open() 


End If 
End Sub 


Public Overrides Sub ReleaseConnections() 
If IsNothing(sqlConnection) = False And sqlConnection.State <> ConnectionState.Closed Then 
sqlConnection.Close() 


End If 


End Sub 


Validating the Component 


Destination component developers should perform validation as described in Component Validation. In 
addition, they should verify that the data type properties of the columns defined in the component's input 
column collection match the columns at the external data source. At times, verifying the input columns against 
the external data source can be impossible or undesirable, such as when the component or the SSIS Designer is 
in a disconnected state, or when round trips to the server are not acceptable. In these situations, the columns in 
the input column collection can still be validated by using the ExternalMetadataColumnCollection of the input 


object. 


This collection exists on both input and output objects and must be populated by the component developer 
from the columns at the external data source. This collection can be used to validate the input columns when the 
SSIS Designer is offline, when the component is disconnected, or when the ValidateExternal Metadata property is 


false. 


The following sample code adds an external metadata column based on an existing input column. 


private void AddExternalMetaDataColumn(IDTSInput1@@ input, IDTSInputColumn1e@e@ inputColumn) 
{ 
// Set the properties of the external metadata column. 
IDTSExternalMetadataColumn10@ externalColumn = input.ExternalMetadataColumnCollection.New(); 
externalColumn.Name = inputColumn.Name; 
externalColumn.Precision = inputColumn.Precision; 
externalColumn.Length = inputColumn.Length; 
externalColumn.DataType = inputColumn.DataType; 
externalColumn.Scale = inputColumn.Scale; 


// Map the external column to the input column. 
inputColumn.ExternalMetadataColumnID = externalColumn.ID; 


Private Sub AddExternalMetaDataColumn(ByVal input As IDTSInput10@, ByVal inputColumn As IDTSInputColumn1@e) 


" Set the properties of the external metadata column. 

Dim externalColumn As IDTSExternalMetadataColumn10@ = input.ExternalMetadataColumnCollection.New() 
externalColumn.Name = inputColumn.Name 

externalColumn.Precision = inputColumn.Precision 

externalColumn.Length = inputColumn.Length 

externalColumn.DataType = inputColumn.DataType 

externalColumn.Scale = inputColumn.Scale 


"Map the external column to the input column. 
inputColumn.ExternalMetadataColumnID = externalColumn.ID 


End Sub 
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Run Time 


During execution, the destination component receives a call to the Processinput method each time a full 
PipelineBuffer is available from the upstream component. This method is called repeatedly until there are no 
more buffers available and the EndOfRowset property is true. During this method, destination components read 
columns and rows in the buffer, and add them to the external data source. 


Locating Columns in the Buffer 

The input buffer for a component contains all the columns defined in the output column collections of the 
components upstream from the component in the data flow. For example, if a source component provides three 
columns in its output, and the next component adds an additional output column, the buffer provided to the 
destination component contains four columns, even if the destination component will write only two columns. 


The order of the columns in the input buffer is not defined by the index of the column in the input column 
collection of the destination component. Columns can be reliably located in a buffer row only by using the 
FindColumnByLineagelD method of the BufferManager. This method locates the column that has the specified 
lineage ID in the specified buffer, and returns its location in the row. The indexes of the input columns are 
typically located during the PreExecute method, and cached by the developer for use later during Process!Input. 


The following code example finds the location of the input columns in the buffer during PreExecute and stores 
them in an array. The array is subsequently used during Processinput to read the values of the columns in the 


buffer. 

int[] cols; 

public override void PreExecute() 

{ 
IDTSInput10@ input = ComponentMetaData.InputCollection[@]; 
cols = new int[input.InputColumnCollection.Count]; 
for (int x = 0; x < input.InputColumnCollection.Count; x++) 
{ 


cols[x] = BufferManager.FindColumnByLineageID(input.Buffer, 
input. InputColumnCollection[x].LineageID) ; 


} 


Private cols As Integer() 
Public Overrides Sub PreExecute() 
Dim input As IDTSInput1@@ = ComponentMetaData.InputCollection(@) 
ReDim cols(input.InputColumnCollection. Count) 
For x As Integer = @ To input. InputColumnCollection. Count 
cols(x) = BufferManager.FindColumnByLineageID(input.Buffer, 
input. InputColumnCollection(x).LineageID) 


Next x 


End Sub 


Processing Rows 
Once the input columns have been located in the buffer, they can be read and written to the external data source. 
While the destination component writes rows to the external data source, you may want to update the "Rows 


read" or "BLOB bytes read" performance counters by calling the IncrementPipelinePerfCounter method. For 
more information, see Performance Counters. 


The following example shows a component that reads rows from the buffer provided in ProcessInput. The 
indexes of the columns in the buffer were located during PreExecute in the preceding code example. 


public override void ProcessInput(int inputID, PipelineBuffer buffer) 


{ 
while (buffer.NextRow()) 
{ 
foreach (int col in cols) 
{ 
if (!buffer.IsNull(col)) 
{ 
// TODO: Read the column data. 
} 
} 
} 
} 


Public Overrides Sub ProcessInput(ByVal inputID As Integer, ByVal buffer As PipelineBuffer) 
While (buffer.NextRow()) 
For Each col As Integer In cols 
If buffer.IsNull(col) = False Then 


"TODO: Read the column data. 
End If 


Next col 


End While 
End Sub 


Sample 


The following sample shows a simple destination component that uses a File connection manager to save 


binary data from the data flow into files. This sample does not demonstrate all the methods and functionality 


discussed in this topic. It demonstrates the important methods that every custom destination component must 


override, but does not contain code for design-time validation. 


using System; 

using System.I0; 

using Microsoft.SqlServer.Dts.Pipeline; 

using Microsoft.SqlServer.Dts.Pipeline.Wrapper; 


namespace BlobDst 


{ 


[DtsPipelineComponent(DisplayName = "BLOB Extractor Destination", Description = "Writes values of BLOB 


columns to files") ] 
public class BlobDst : PipelineComponent 
{ 
string m_DestDir; 
int m_FileNameColumnIndex = -1; 
int m_BlobColumnIndex = -1; 


public override void ProvideComponentProperties() 


ik 
IDTSInput10@ input = ComponentMetaData.InputCollection.New(); 


input.Name = "BLOB Extractor Destination Input"; 
input.HasSideEffects = true; 


IDTSRuntimeConnection10@ conn = ComponentMetaData.RuntimeConnectionCollection.New(); 
conn.Name = "FileConnection"; 


public override void AcquireConnections(object transaction) 


IDTSRuntimeConnection10@ conn = ComponentMetaData.RuntimeConnectionCollection[@]; 
m_DestDir = (string)conn.ConnectionManager.AcquireConnection(nul1) ; 


if (m_DestDir.Length > @ && m_DestDir[m_DestDir.Length - 1] != '\\') 
m_DestDir += "\\"5 


public override IDTSInputColumn1@@ SetUsageType(int inputID, IDTSVirtualInput10@ virtualInput, int 
lineageID, DTSUsageType usageType) 


if 
IDTSInputColumnie@ inputColumn = base.SetUsageType(inputID, virtualInput, lineageID, usageType) ; 


IDTSCustomProperty10@ custProp; 


custProp = inputColumn.CustomPropertyCollection.New(); 
custProp.Name = "IsFileName"; 
custProp.Value = (object)false; 


custProp = inputColumn.CustomPropertyCollection.New(); 
custProp.Name = "IsBLOB"; 
custProp.Value = (object)false; 


return inputColumn; 


public override void PreExecute() 


{ 
IDTSInput10@ input = ComponentMetaData.InputCollection[@]; 


IDTSInputColumnCollection10e inputColumns = input. InputColumnCollection; 
IDTSCustomProperty1@@ custProp; 


foreach (IDTSInputColumn1e@@ column in inputColumns) 


{ 
custProp = column.CustomPropertyCollection["IsFileName" ] ; 
if ((bool)custProp.Value == true) 
{ 
m_FileNameColumnIndex = (int)BufferManager .FindColumnByLineageID(input.Buffer, column.LineageID) ; 
} 
custProp = column.CustomPropertyCollection["IsBLOB" ]; 
if ((bool)custProp.Value == true) 
{ 
m_BlobColumnIndex = (int)BufferManager.FindColumnByLineageID(input.Buffer, column.LineageID) ; 
} 
} 
} 
public override void ProcessInput(int inputID, PipelineBuffer buffer) 
it 
while (buffer.NextRow()) 
{ 


string strFileName = buffer.GetString(m_FileNameColumnIndex) ; 
int blobLength = (int)buffer.GetBlobLength(m_BlobColumnIndex) ; 
byte[] blobData = buffer.GetBlobData(m_BlobColumnIndex, @, blobLength) ; 


strFileName = TranslateFileName(strFileName) ; 


// Make sure directory exists before creating file. 
FileInfo fi = new FileInfo(strFileName) ; 
if (!fi.Directory.Exists) 

fi.Directory.Create(); 


// Write the data to the file. 

FileStream fs = new FileStream(strFileName, FileMode.Create, FileAccess.Write, FileShare.None) ; 
fs.Write(blobData, @, blobLength); 

fs.Close(); 


private string TranslateFileName(string fileName) 


it 
if (fileName.Length > 2 && fileName[1] == ':') 
return m_DestDir + fileName.Substring(3, fileName.Length - 3); 
else 
return m_DestDir + fileName; 
} 
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Imports System 

Imports System.IO 

Imports Microsoft.SqlServer.Dts.Pipeline 

Imports Microsoft.SqlServer.Dts.Pipeline.Wrapper 
Namespace BlobDst 


<DtsPipelineComponent (DisplayName="BLOB Extractor Destination", Description="Writes values of BLOB columns 
to files")> _ 
Public Class BlobDst 
Inherits PipelineComponent 
Private m_DestDir As String 
Private m_FileNameColumnIndex As Integer = -1 
Private m_BlobColumnIndex As Integer = -1 


Public Overrides Sub ProvideComponentProperties() 
Dim input As IDTSInput1@@ = ComponentMetaData. InputCollection.New 
input.Name = "BLOB Extractor Destination Input" 
input.HasSideEffects = True 
Dim conn As IDTSRuntimeConnectioni@e = ComponentMetaData.RuntimeConnectionCollection.New 
conn.Name = "FileConnection" 
End Sub 


Public Overrides Sub AcquireConnections(ByVal transaction As Object) 
Dim conn As IDTSRuntimeConnection10@ = ComponentMetaData.RuntimeConnectionCollection(@) 
m_DestDir = CType(conn.ConnectionManager.AcquireConnection(Nothing), String) 
If m_DestDir.Length > @ AndAlso Not (m_DestDir(m_DestDir.Length - 1) = "\"C) Then 
m_DestDir += "\" 
End If 
End Sub 


Public Overrides Function SetUsageType(ByVal inputID As Integer, ByVal virtualInput As 
IDTSVirtualInput10@, ByVal lineageID As Integer, ByVal usageType As DTSUsageType) As IDTSInputColumn1ee 
Dim inputColumn As IDTSInputColumn1e@ = MyBase.SetUsageType(inputID, virtualInput, lineageID, 
usageType) 
Dim custProp As IDTSCustomProperty10e 
custProp = inputColumn.CustomPropertyCollection.New 
custProp.Name = "“IsFileName" 
custProp.Value = CType(False, Object) 
custProp = inputColumn.CustomPropertyCollection.New 
custProp.Name = "IsBLOB" 
custProp.Value = CType(False, Object) 
Return inputColumn 
End Function 


Public Overrides Sub PreExecute() 
Dim input As IDTSInput10@ = ComponentMetaData. InputCollection(@) 
Dim inputColumns As IDTSInputColumnCollection10® = input. InputColumnCollection 
Dim custProp As IDTSCustomProperty10e 
For Each column As IDTSInputColumni@e@ In inputColumns 
custProp = column.CustomPropertyCollection("IsFileName" ) 
If CType(custProp.Value, Boolean) = True Then 
m_FileNameColumnIndex = CType(BufferManager.FindColumnByLineageID(input.Buffer, column.LineageID) , 
Integer) 
End If 
custProp = column.CustomPropertyCollection("IsBLOB" ) 
If CType(custProp.Value, Boolean) = True Then 


m_BlobColumnIndex = CType(ButterManager .FindColumnByLineageID(input.Butter, column.LineageID), 
Integer) 
End If 
Next 
End Sub 


Public Overrides Sub ProcessInput(ByVal inputID As Integer, ByVal buffer As PipelineBuffer) 
While buffer.NextRow 
Dim strFileName As String = buffer.GetString(m_FileNameColumnIndex) 
Dim blobLength As Integer = CType(buffer.GetBlobLength(m_BlobColumnIndex), Integer) 
Dim blobData As Byte() = buffer.GetBlobData(m_BlobColumnIndex, @, blobLength) 
strFileName = TranslateFileName(strFileName) 
Dim fi As FileInfo = New FileInfo(strFileName) 
" Make sure directory exists before creating file. 
If Not fi.Directory.Exists Then 
#i.Directory.Create 
End If 
" Write the data to the file. 
Dim fs As FileStream = New FileStream(strFileName, FileMode.Create, FileAccess.Write, FileShare.None) 
fs.Write(blobData, @, blobLength) 
fs.Close 
End While 
End Sub 


Private Function TranslateFileName(ByVal fileName As String) As String 
If fileName.Length > 2 AndAlso fileName(1) = ":"C Then 
Return m_DestDir + fileName.Substring(3, fileName.Length - 3) 
Else 
Return m_DestDir + fileName 
End If 
End Function 
End Class 
End Namespace 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


SQL Server Integration Services gives developers the ability to write source components that can connect to 
custom data sources and supply data from those sources to other components in a data flow task. The ability to 
create custom sources is valuable when you must connect to data sources that cannot be accessed by using one 
of the existing Integration Services sources. 


Source components have one or more outputs and zero inputs. At design time, source components are used to 
create and configure connections, read column metadata from the external data source, and configure the 
source's output columns based on the external data source. During execution they connect to the external data 
source and add rows to an output buffer. The data flow task then provides this buffer of data rows to 
downstream components. 


For a general overview of data flow component development, see Developing a Custom Data Flow Component. 


Design Time 


Implementing the design-time functionality of a source component involves specifying a connection to an 
external data source, adding and configuring output columns that reflect the data source, and validating that the 
component is ready to execute. By definition, a source component has zero inputs and one or more 
asynchronous outputs. 


Creating the Component 


Source components connect to external data sources by using ConnectionManager objects defined in a package. 
They indicate their requirement for a connection manager by adding an element to the 
RuntimeConnectionCollection collection of the ComponentMetaData property. This collection serves two 
purposes-to hold references to connection managers in the package used by the component, and to advertise 
the need for a connection manager to the designer. When an IDTSRuntimeConnection100 has been added to the 
collection, the Advanced Editor displays the Connection Properties tab, which lets users select or create a 
connection in the package. 


The following code example shows an implementation of ProvideComponentProperties that adds an output, 
and adds a IDTSRuntimeConnection100 object to the RuntimeConnectionCollection. 


using 
using 
using 
using 
using 
using 
using 
using 
using 


System; 

System.Collections; 

System.Data; 

System.Data.SqlClient; 

System.Data.OleDb; 
Microsoft.SqlServer.Dts.Runtime; 
Microsoft.SqlServer.Dts.Runtime.Wrapper; 
Microsoft.SqlServer.Dts.Pipeline; 
Microsoft.SqlServer.Dts.Pipeline.Wrapper; 


namespace Microsoft.Samples.SqlServer.Dts 


{ 


[DtsPipelineComponent(DisplayName = "MySourceComponent",ComponentType = ComponentType.SourceAdapter) ] 


public class MyComponent : PipelineComponent 


{ 


public override void ProvideComponentProperties() 

{ 
// Reset the component. 
base.RemoveAllInputsOutputsAndCustomProperties() ; 
ComponentMetaData.RuntimeConnectionCollection.RemoveA11() ; 


IDTSOutput19e@ output = ComponentMetaData.OutputCollection.New(); 
output.Name = "Output"; 


IDTSRuntimeConnection10@ connection = ComponentMetaData.RuntimeConnectionCollection.New(); 
connection.Name = "ADO.NET"3 


Imports System.Data 


Imports System.Data.SqlClient 


Imports Microsoft.SqlServer.Dts.Runtime 


Imports Microsoft.SqlServer.Dts.Runtime.Wrapper 


Imports Microsoft.SqlServer.Dts.Pipeline 


Imports Microsoft.SqlServer.Dts.Pipeline.Wrapper 


<DtsPipelineComponent (DisplayName:="MySourceComponent", ComponentType:=ComponentType.SourceAdapter)> _ 


Public Class MySourceComponent 


Inherits PipelineComponent 


Public Overrides Sub ProvideComponentProperties() 


Allow for resetting the component. 
RemoveAllInputsOutputsAndCustomProperties( ) 
ComponentMetaData.RuntimeConnectionCollection.RemoveA11() 


Dim output As IDTSOutput10@ = ComponentMetaData.OutputCollection.New() 
output.Name = "Output" 


Dim connection As IDTSRuntimeConnection10@ = ComponentMetaData.RuntimeConnectionCollection.New() 
connection.Name = "ADO.NET" 


End Sub 
End Class 


Connecting to an External Data Source 


After a connection has been added to the RuntimeConnectionCollection, you override the AcquireConnections 


method to establish a connection to the external data source. This method is called during both design and 


execution time. The component should establish a connection to the connection manager specified by the run- 


time connection, and subsequently, to the external data source. 


After the connection is established, it should be cached internally by the component and released when the 


ReleaseConnections method is called. The ReleaseConnections method is called at design and execution time, 


like the AcquireConnections method. Developers override this method, and release the connection established 
by the component during AcquireConnections. 


The following code example shows a component that connects to an ADO.NET connection in the 
AcquireConnections method and closes the connection in the ReleaseConnections method. 


private SqlConnection sqlConnection; 


public override void AcquireConnections(object transaction) 
{ 
if (ComponentMetaData.RuntimeConnectionCollection[@].ConnectionManager != null) 
{ 
ConnectionManager cm = 
Microsoft.SqlServer.Dts.Runtime.DtsConvert.GetWrapper (ComponentMetaData.RuntimeConnectionCollection[@].Conne 
ctionManager) ; 
ConnectionManagerAdoNet cmado = cm.InnerObject as ConnectionManagerAdoNet ; 


if (cmado == null) 
throw new Exception("The ConnectionManager " + cm.Name + " is not an ADO.NET connection."); 


sqlConnection = cmado.AcquireConnection(transaction) as SqlConnection; 
sqlConnection.Open(); 


t 
t 
public override void ReleaseConnections() 
{ 
if (sqlConnection != null && sqlConnection.State != ConnectionState.Closed) 
sqlConnection.Close(); 
t 


Private sqlConnection As SqlConnection 
Public Overrides Sub AcquireConnections(ByVal transaction As Object) 
If Not IsNothing(ComponentMetaData.RuntimeConnectionCollection(@).ConnectionManager) Then 


Dim cm As ConnectionManager = 
Microsoft.SqlServer.Dts.Runtime.DtsConvert.GetWrapper (ComponentMetaData.RuntimeConnectionCollection(@).Conne 
ctionManager ) 

Dim cmado As ConnectionManagerAdoNet = CType(cm.InnerObject, ConnectionManagerAdoNet ) 


If IsNothing(cmado) Then 
Throw New Exception("The ConnectionManager 
End If 


+ cm.Name + " is not an ADO.NET connection.") 


sqlConnection = CType(cmado.AcquireConnection(transaction), SqlConnection) 
sqlConnection.Open() 


End If 
End Sub 


Public Overrides Sub ReleaseConnections() 
If Not IsNothing(sqlConnection) And sqlConnection.State <> ConnectionState.Closed Then 
sqlConnection.Close() 


End If 


End Sub 


Creating and Configuring Output Columns 


The output columns of a source component reflect the columns from the external data source that the 
component adds to the data flow during execution. At design time, you add output columns after the 


component has been configured to connect to an external data source. The design-time method that a 
component uses to add the columns to its output collection can vary based on the needs of the component, 
although they should not be added during Validate or AcquireConnections. For example, a component that 
contains a SQL statement in a custom property that controls the data set for the component may add its output 
columns during the SetComponentProperty method. The component checks to see whether it has a cached 
connection, and, if it does, connects to the data source and generates its output columns. 


After an output column has been created, set its data type properties by calling the SetDataTypeProperties 
method. This method is necessary because the DataType, Length, Precision, and CodePage properties are read- 
only and each property is dependent on the settings of the other. This method enforces the need for these 
values to be set consistently, and the data flow task validates that they are set correctly. 


The DataType of the column determines the values that are set for the other properties. The following table 
shows the requirements on the dependent properties for each DataType. The data types not listed have their 
dependent properties set to zero. 


DATATYPE LENGTH SCALE PRECISION CODEPAGE 
DT_DECIMAL 0 Greater than 0 and 0 0 
less than or equal to 
28. 
DT_CY 0 0 0 0 
DT_NUMERIC 0 Greater than 0 and Greater than or equal 0 
less than or equal to to 1 and less than or 
28, and less than equal to 38. 
Precision. 
DT_BYTES Greater than 0. 0 0 0 
DT_STR Greater than 0 and 0 0 Not 0, and a valid 
less than 8000. code page. 
DT_WSTR Greater than 0 and 0 0 0 
less than 4000. 


Because the restrictions on the data type properties are based on the data type of the output column, you must 
choose the correct SSIS data type when you work with managed types. The base class provides three helper 
methods, Conver tBufferDataTypeToFitManaged, BufferlypeToDataRecordType, and 
DataRecordTypeToBufferType, to assist managed component developers in selecting an SSIS data type given a 
managed type. These methods convert managed data types to SSIS data types, and vice versa. 


The following code example shows how the output column collection of a component is populated based on the 
schema of a table. The helper methods of the base class are used to set the data type of the column, and the 
dependent properties are set based on the data type. 


SqlCommand sqlCommand; 


private void CreateColumnsFromDataTable() 
{ 
// Get the output. 
IDTSOutput19e@ output = ComponentMetaData.OutputCollection[@]; 


// Start clean, and remove the columns from both collections. 
output .OutputColumnCollection.RemoveAl1(); 
output. ExternalMetadataColumnCollection.RemoveA11(); 


this.sqlCommand = sqlConnection.CreateCommand() ; 

this.sqlCommand.CommandType = CommandType. Text; 

this.sqlCommand.CommandText = (string)ComponentMetaData.CustomPropertyCollection["SqlStatement"].Value; 
SqlDataReader schemaReader = this.sqlCommand.ExecuteReader (CommandBehavior.SchemaOnly) ; 

DataTable dataTable = schemaReader.GetSchemaTable(); 


// Walk the columns in the schema, 
// and for each data column create an output column and an external metadata column. 
foreach (DataRow row in dataTable.Rows) 
{ 
IDTSOutputColumn1@e@ outColumn = output.OutputColumnCollection.New(); 
IDTSExternalMetadataColumn10@ exColumn = output.ExternalMetadataColumnCollection.New() ; 


// Set column data type properties. 

bool isLong = false; 

DataType dt = DataRecordTypeToBufferType( (Type)row[ "DataType"]) ; 
dt = ConvertBufferDataTypeToFitManaged(dt, ref isLong); 

int length = @; 

int precision = (short)row["NumericPrecision" ]; 

int scale = (short)row["NumericScale"]; 

int codepage = dataTable.Locale.TextInfo.ANSICodePage; 


switch (dt) 
{ 
// The length cannot be zero, and the code page property must contain a valid code page. 
case DataType.DT_STR: 
case DataType.DT_TEXT: 
length = precision; 
precision = @; 
scale = Q; 
break; 


case DataType.DT_WSTR: 
length = precision; 
codepage = @; 
scale = Q; 
precision = @; 
break; 


case DataType.DT_BYTES: 
precision = @; 
scale = Q; 
codepage = @; 
break; 


case DataType.DT_NUMERIC: 
length = @; 
codepage = @; 


if (precision > 38) 
precision = 38; 


if (scale > 6) 
scale = 6; 
break; 


case DataType.DT_DECIMAL: 
length = @; 
precision = @; 
codepage = @; 
break; 


default: 
length = @; 
precision = @; 
codepage = @; 
scale = Q; 
break; 


// Set the properties of the output column. 
outColumn.Name = (string)row["ColumnName" ] ; 
outColumn.SetDataTypeProperties(dt, length, precision, scale, codepage) ; 
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Private sqlCommand As SqlCommand 
Private Sub CreateColumnsFromDataTable() 


" Get the output. 

Dim output As IDTSOutput1@@ = ComponentMetaData.OutputCollection(@) 
" Start clean, and remove the columns from both collections. 
output .OutputColumnCollection.RemoveAl1() 

output. ExternalMetadataColumnCollection.RemoveA11() 


Me.sqlCommand = sqlConnection.CreateCommand() 
Me.sqlCommand.CommandType = CommandType. Text 
Me.sqlCommand.CommandText = CStr(ComponentMetaData.CustomPropertyCollection("SqlStatement").Value) 


Dim schemaReader As SqlDataReader = Me.sqlCommand.ExecuteReader (CommandBehavior .SchemaOnly) 
Dim dataTable As DataTable = schemaReader.GetSchemaTable() 


Walk the columns in the schema, 


and for each data column create an output column and an external metadata column. 
For Each row As DataRow In dataTable.Rows 


Dim outColumn As IDTSOutputColumn1e@ = output.OutputColumnCollection.New() 

Dim exColumn As IDTSExternalMetadataColumn1@@ = output.ExternalMetadataColumnCollection.New() 
" Set column data type properties. 

Dim isLong As Boolean = False 

Dim dt As DataType = DataRecordTypeToBufferType(CType(row("DataType"), Type)) 
dt = ConvertBufferDataTypeToFitManaged(dt, isLong) 

Dim length As Integer = @ 

Dim precision As Integer = CType(row("NumericPrecision"), Short) 

Dim scale As Integer = CType(row("NumericScale"), Short) 

Dim codepage As Integer = dataTable.Locale. TextInfo.ANSICodePage 


Select Case dt 
" The length cannot be zero, and the code page property must contain a valid code page. 
Case DataType.DT_STR 
Case DataType.DT_TEXT 
length = precision 
precision = @ 
scale = @ 


Case DataType.DT_WSTR 
length = precision 
codepage = @ 
scale = @ 
precision = @ 


Case DataType.DT_BYTES 
precision = @ 
scale = @ 
codepage = @ 


Case DataType.DT_NUMERIC 
length = @ 
codepage = @ 


If precision > 38 Then 
precision = 38 
End If 


If scale > 6 Then 
scale = 6 
End If 


Case DataType.DT_DECIMAL 
length = @ 
precision = @ 
codepage = @ 


Case Else 
length = @ 
precision = @ 
codepage = @ 
scale = @ 
End Select 


Set the properties of the output column. 
outColumn.Name = CStr(row("ColumnName”" ) ) 
outColumn.SetDataTypeProperties(dt, length, precision, scale, codepage) 
Next 
End Sub 


Validating the Component 


You should validate a source component and verify that the columns defined in its output column collections 
match the columns at the external data source. Sometimes, verifying the output columns against the external 
data source can be impossible, such as in a disconnected state, or when it is preferable to avoid lengthy round 
trips to the server. In these situations, the columns in the output can still be validated by using the 
ExternalMetadataColumnCollection of the output object. For more information, see Validating a Data Flow 
Component. 


This collection exists on both input and output objects and you can populate it with the columns from the 
external data source. You can use this collection to validate the output columns when SSIS Designer is offline, 
when the component is disconnected, or when the ValidateExternal Metadata property is false. The collection 
should be first populated at the same time that the output columns are created. Adding external metadata 
columns to the collection is relatively easy because the external metadata column should initially match the 
output column. The data type properties of the column should have already been set correctly, and the 
properties can be copied directly to the IDTSExternalMetadataColumn100 object. 


The following sample code adds an external metadata column that is based on a newly created output column. It 
assumes that the output column has already been created. 


private void CreateExternalMetaDataColumn(IDTSOutput1ee output, IDTSOutputColumn1ee@ outputColumn) 
{ 


// Set the properties of the external metadata column. 

IDTSExternalMetadataColumn10@ externalColumn = output.ExternalMetadataColumnCollection.New() ; 
externalColumn.Name = outputColumn.Name; 

externalColumn.Precision = outputColumn.Precision; 

externalColumn.Length = outputColumn.Length; 

externalColumn.DataType = outputColumn.DataType; 

externalColumn.Scale = outputColumn.Scale; 


// Map the external column to the output column. 
outputColumn.ExternalMetadataColumnID = externalColumn.1ID; 


Private Sub CreateExternalMetaDataColumn(ByVal output As IDTSOutput10@, ByVal outputColumn As 
IDTSOutputColumn1ee) 


" Set the properties of the external metadata column. 

Dim externalColumn As IDTSExternalMetadataColumn10@ = output.ExternalMetadataColumnCollection.New() 
externalColumn.Name = outputColumn.Name 

externalColumn.Precision = outputColumn.Precision 

externalColumn.Length = outputColumn.Length 

externalColumn.DataType = outputColumn.DataType 

externalColumn.Scale = outputColumn.Scale 


" Map the external column to the output column. 
outputColumn.ExternalMetadataColumnID = externalColumn.ID 


End Sub 
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Run Time 


During execution, components add rows to output buffers that are created by the data flow task and provided to 
the component in PrimeOutput. Called once for source components, the method receives an output buffer for 
each IDTSOutput100 of the component that is connected to a downstream component. 


Locating Columns in the Buffer 


The output buffer for a component contains the columns defined by the component and any columns added to 
the output of a downstream component. For example, if a source component provides three columns in its 
output, and the next component adds a fourth output column, the output buffer provided for use by the source 


component contains these four columns. 


The order of the columns in a buffer row is not defined by the index of the output column in the output column 
collection. An output column can only be accurately located in a buffer row by using the 
FindColumnByLineagelD method of the BufferManager. This method locates the column with the specified 
lineage ID in the specified buffer, and returns its location in the row. The indexes of the output columns are 
typically located in the PreExecute method, and stored for use during PrimeOutput. 


The following code example finds the location of the output columns in the output buffer during a call to 
PreExecute, and stores them in an internal structure. The name of the column is also stored in the structure and 


is used in the code example for the PrimeOutput method in the next section of this topic. 


ArrayList columnInformation; 


private struct ColumnInfo 


ib 
public int BufferColumnIndex; 
public string ColumnName; 
t 
public override void PreExecute() 
{ 
this.columnInformation = new ArrayList(); 
IDTSOutput19e@ output = ComponentMetaData.OutputCollection[9@]; 
foreach (IDTSOutputColumn1@@ col in output.OutputColumnCollection) 
{ 
ColumnInfo ci = new ColumnInfo(); 
ci.BufferColumnIndex = BufferManager.FindColumnByLineageID(output.Buffer, col.LineageID) ; 
ci.ColumnName = col.Name; 
columnInformation.Add(ci); 
} 
i; 


Public Overrides Sub PreExecute() 


Me.columnInformation = New ArrayList() 
Dim output As IDTSOutput10@ = ComponentMetaData.OutputCollection(@) 


For Each col As IDTSOutputColumn1@@ In output.OutputColumnCollection 


Dim ci As ColumnInfo = New ColumnInfo() 
ci.BufferColumnIndex = BufferManager.FindColumnByLineageID(output.Buffer, col.LineageID) 
ci.ColumnName = col.Name 
columnInformation.Add(ci) 
Next 
End Sub 


Processing Rows 


Rows are added to the output buffer by calling the AddRow method, which creates a new buffer row with empty 
values in its columns. The component then assigns values to the individual columns. The output buffers 
provided to a component are created and monitored by the data flow task. As they become full, the rows in the 
buffer are moved to the next component. There is no way to determine when a batch of rows has been sent to 
the next component because the movement of rows by the data flow task is transparent to the component 
developer, and the RowCount property is always zero on output buffers. When a source component is finished 
adding rows to its output buffer, it notifies the data flow task by calling the SetEndOfRowset method of the 
PipelineBuffer, and the remaining rows in the buffer are passed to the next component. 


While the source component reads rows from the external data source, you may want to update the "Rows read" 
or "BLOB bytes read" performance counters by calling the IncrementPipelinePerfCounter method. For more 
information, see Performance Counters. 


The following code example shows a component that adds rows to an output buffer in PrimeOutput. The 
indexes of the output columns in the buffer were located using PreExecute in the previous code example. 


public override void PrimeOutput(int outputs, int[] outputIDs, PipelineBuffer[] buffers) 
{ 

IDTSOutput190e@ output = ComponentMetaData.OutputCollection[9@]; 

PipelineBuffer buffer = buffers[Q]; 


SqlDataReader dataReader = sqlCommand.ExecuteReader() ; 
// Loop over the rows in the DataReader, 


// and add them to the output buffer. 
while (dataReader.Read()) 


{ 
// Add a row to the output buffer. 
buffer .AddRow() ; 
for (int x = @; x < columnInformation.Count; x++) 
{ 
ColumnInfo ci = (ColumnInfo)columnInformation[x]; 
int ordinal = dataReader.GetOrdinal(ci.ColumnName) ; 
if (dataReader.IsDBNull(ordinal) ) 
buffer.SetNull(ci.BufferColumnIndex) ; 
else 
{ 
buffer[ci.BufferColumnIndex] = dataReader[ci.ColumnName] ; 
} 
} 
} 


buffer.SetEndOfRowset(); 


Public Overrides Sub PrimeOutput(ByVal outputs As Integer, ByVal outputIDs As Integer(), ByVal buffers As 
PipelineBuffer() ) 


Dim output As IDTSOutput1@@ = ComponentMetaData.OutputCollection(@) 
Dim buffer As PipelineBuffer = buffers(@) 


Dim dataReader As SqlDataReader = sqlCommand.ExecuteReader() 


Loop over the rows in the DataReader, 
"and add them to the output buffer. 
While (dataReader.Read()) 


" Add a row to the output buffer. 
buffer .AddRow() 


For x As Integer = @ To columnInformation.Count 
Dim ci As ColumnInfo = CType(columnInformation(x), ColumnInfo) 
Dim ordinal As Integer = dataReader.GetOrdinal(ci.ColumnName) 
If (dataReader.IsDBNull(ordinal)) Then 
buffer.SetNull(ci.BufferColumniIndex) 
Else 


buffer(ci.BufferColumnIndex) = dataReader(ci.ColumnName) 


End If 
Next 


End While 


buffer. SetEndOfRowset () 
End Sub 


Sample 


The following sample shows a simple source component that uses a File connection manager to load the binary 
contents of files into the data flow. This sample does not demonstrate all the methods and functionality 
discussed in this topic. It demonstrates the important methods that every custom source component must 
override, but does not contain code for design-time validation. 


using System; 

using System.I0; 

using Microsoft.SqlServer.Dts.Pipeline; 

using Microsoft.SqlServer.Dts.Pipeline.Wrapper; 
using Microsoft.SqlServer.Dts.Runtime.Wrapper ; 


namespace BlobSrc 


{ 


[DtsPipelineComponent(DisplayName = "BLOB Inserter Source", Description = "Inserts files into the data 
flow as BLOBs") ] 
public class BlobSrc : PipelineComponent 
{ 
IDTSConnectionManager1@@ m_ConnMgr ; 
int m_FileNameColumnIndex = -1; 
int m_FileBlobColumnIndex = -1; 


public override void ProvideComponentProperties() 


{ 
IDTSOutput19e@ output = ComponentMetaData.OutputCollection.New(); 


output.Name = "BLOB File Inserter Output"; 


IDTSOutputColumn1@e@ column = output.OutputColumnCollection.New() ; 
column.Name = "FileName"; 
column.SetDataTypeProperties(DataType.DT_WSTR, 256, @, 0, 9); 


column = output.OutputColumnCollection.New() ; 
column.Name = "FileBLOB"; 
column.SetDataTypeProperties(DataType.DT_IMAGE, @, @, 9, @); 


IDTSRuntimeConnection10@ conn = ComponentMetaData.RuntimeConnectionCollection.New(); 
conn.Name = "FileConnection"; 


public override void AcquireConnections(object transaction) 


{ 


IDTSRuntimeConnection10@ conn = ComponentMetaData.RuntimeConnectionCollection[@]; 
m_ConnMgr = conn.ConnectionManager ; 


} 
public override void ReleaseConnections() 
{ 
m_ConnMgr = null; 
} 


public override void PreExecute() 


{ 
IDTSOutput10@ output = ComponentMetaData.OutputCollection[@]; 


m_FileNameColumnIndex = (int)BufferManager .FindColumnByLineageID(output.Buffer, 
output .OutputColumnCollection[@].LineageID) ; 
m_FileBlobColumnIndex = (int)BufferManager .FindColumnByLineageID(output.Buffer, 
output .OutputColumnCollection[1].LineageID) ; 
i 


public override void PrimeOutput(int outputs, int[] outputIDs, PipelineBuffer[] buffers) 
{ 


string strFileName = (string)m_ConnMgr.AcquireConnection(null) ; 


while (strFileName != null) 


buffers[@].AddRow(); 

buffers[Q].SetString(m_FileNameColumnIndex, strFileName) ; 

FileInfo fileInfo = new FileInfo(strFileName) ; 

byte[] fileData = new byte[fileInfo.Length]; 

FileStream fs = new FileStream(strFileName, FileMode.Open, FileAccess.Read, FileShare.Read) ; 
fs.Read(fileData, 9, fileData.Length) ; 


buffers[@].AddBlobData(m_FileBlobColumnIndex, fileData) ; 


strFileName = (string)m_ConnMgr.AcquireConnection(null) ; 


buffers[0].SetEndOfRowset() ; 


Imports System 

Imports System.IO 

Imports Microsoft.SqlServer.Dts.Pipeline 

Imports Microsoft.SqlServer.Dts.Pipeline.Wrapper 
Imports Microsoft.SqlServer.Dts.Runtime.Wrapper 
Namespace BlobSrc 


<DtsPipelineComponent (DisplayName="BLOB Inserter Source", Description="Inserts files into the data flow as 
BLOBs")> _ 
Public Class BlobSrc 
Inherits PipelineComponent 
Private m_ConnMgr As IDTSConnectionManager100 
-1 
-1 


Private m_FileNameColumnIndex As Integer 


Private m_FileBlobColumnIndex As Integer 


Public Overrides Sub ProvideComponentProperties() 
Dim output As IDTSOutput10@ = ComponentMetaData.OutputCollection.New 
output.Name = "BLOB File Inserter Output” 
Dim column As IDTSOutputColumn1e@ = output.OutputColumnCollection.New 
column.Name = "FileName" 
column.SetDataTypeProperties(DataType.DT_WSTR, 256, @, 0, @) 
column = output.OutputColumnCollection.New 
column.Name = "FileBLOB" 
column.SetDataTypeProperties(DataType.DT_IMAGE, @, 9, @, @) 
Dim conn As IDTSRuntimeConnection9@ = ComponentMetaData.RuntimeConnectionCollection.New 
conn.Name = "FileConnection" 

End Sub 


Public Overrides Sub AcquireConnections(ByVal transaction As Object) 
Dim conn As IDTSRuntimeConnection10@ = ComponentMetaData.RuntimeConnectionCollection(@) 
m_ConnMgr = conn.ConnectionManager 

End Sub 


Public Overrides Sub ReleaseConnections() 
m_ConnMgr = Nothing 
End Sub 


Public Overrides Sub PreExecute() 
Dim output As IDTSOutput10@ = ComponentMetaData.OutputCollection(@) 
m_FileNameColumnIndex = CType(BufferManager .FindColumnByLineageID(output .Buffer, 
output .OutputColumnCollection(@).LineageID), Integer) 
m_FileBlobColumnIndex = CType(BufferManager .FindColumnByLineageID(output .Buffer, 
output .OutputColumnCollection(1).LineageID), Integer) 
End Sub 


Public Overrides Sub PrimeOutput(ByVal outputs As Integer, ByVal outputIDs As Integer(), ByVal buffers 
As PipelineBuffer()) 
Dim strFileName As String = CType(m_ConnMgr.AcquireConnection(Nothing), String) 
While Not (strFileName Is Nothing) 
buffers(@) .AddRow 
buffers(@).SetString(m_FileNameColumnIndex, strFileName) 
Dim fileInfo As FileInfo = New FileInfo(strFileName) 
Dim fileData(fileInfo.Length) As Byte 
Dim fs As FileStream = New FileStream(strFileName, FileMode.Open, FileAccess.Read, FileShare.Read) 
fs.Read(fileData, @, fileData.Length) 
buffers(@).AddBlobData(m_FileBlobColumnIndex, fileData) 
strFileName = CType(m_ConnMgr.AcquireConnection(Nothing), String) 
End While 
buffers(@).SetEndOfRowset 
End Sub 
End Class 
End Namespace 


See Also 


Developing a Custom Destination Component 
Creating a Source with the Script Component 


Developing a Custom Transformation Component 


with Asynchronous Outputs 
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Applies to: @sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


You use a component with asynchronous outputs when a transform cannot output rows until the component 
has received all its input rows, or when the transformation does not produce exactly one output row for each 
row received as input. The Aggregate transformation, for example, cannot calculate a sum across rows until it 
has read all the rows. In contrast, you can use a component with synchronous outputs any time when you 
modify each row of data as it passes through. You can modify the data for each row in place, or you can create 
one or more new columns, each of which has a value for every one of the input rows. For more information 
about the difference between synchronous and asynchronous components, see Understanding Synchronous 
and Asynchronous Transformations. 


Transformation components with asynchronous outputs are unique because they act as both destination and 
source components. This kind of component receives rows from upstream components, and adds rows that are 


consumed by downstream components. No other data flow component performs both of these operations. 


The columns from upstream components that are available to a component with synchronous outputs are 
automatically available to components downstream from the component. Therefore, a component with 
synchronous outputs does not have to define any output columns to provide columns and rows to the next 
component. Components with asynchronous outputs, on the other hand, must define output columns and 
provide rows to downstream components. Therefore a component with asynchronous outputs has more tasks 
to perform during both design and execution time, and the component developer has more code to implement. 


SQL Server Integration Services contains several transformations with asynchronous outputs. For example, the 
Sort transformation requires all its rows before it can sort them, and achieves this by using asynchronous 
outputs. After it has received all its rows, it sorts them and adds them to its output. 


This section explains in detail how to develop transformations with asynchronous outputs. For more information 
about source component development, see Developing a Custom Source Component. 


Design Time 


Creating the Component 


The Synchronous!nputID property on the |IDTSOutput100 object identifies whether an output is synchronous or 
asynchronous. To create an asynchronous output, add the output to the component and set the 
SynchronousInputlD to zero. Setting this property also determines whether the data flow task allocates 
PipelineBuffer objects for both the input and output of the component, or whether a single buffer is allocated 
and shared between the two objects. 


The following sample code shows a component that creates an asynchronous output in its 
ProvideComponentProperties implementation. 


using Microsoft.SqlServer.Dts.Pipeline; 
using Microsoft.SqlServer.Dts.Pipeline.Wrapper; 
using Microsoft.SqlServer.Dts.Runtime; 


namespace Microsoft.Samples.SqlServer.Dts 


{ 
[DtsPipelineComponent(DisplayName = "AsyncComponent",ComponentType = ComponentType. Transform) ] 
public class AsyncComponent : PipelineComponent 
{ 
public override void ProvideComponentProperties() 
{ 
// Call the base class, which adds a synchronous input 
// and output. 
base.ProvideComponentProperties() ; 
// Make the output asynchronous. 
IDTSOutput19@ output = ComponentMetaData.OutputCollection[e@]; 
output.SynchronousInputID = @; 
} 
} 
i; 


Imports Microsoft.SqlServer.Dts.Pipeline 
Imports Microsoft.SqlServer.Dts.Pipeline.Wrapper 
Imports Microsoft.SqlServer.Dts.Runtime 


<DtsPipelineComponent (DisplayName:="AsyncComponent", ComponentType:=ComponentType.Transform)> _ 
Public Class AsyncComponent 
Inherits PipelineComponent 


Public Overrides Sub ProvideComponentProperties() 


" Call the base class, which adds a synchronous input 


and output. 
Me .ProvideComponentProperties() 


Make the output asynchronous. 
Dim output As IDTSOutput1@@ = ComponentMetaData.OutputCollection(@) 
output.SynchronousInputID = @ 


End Sub 


End Class 


Creating and Configuring Output Columns 


As mentioned earlier, an asynchronous component adds columns to its output column collection to provide 
columns to downstream components. There are several design-time methods to choose from, depending on the 
needs of the component. For example, if you want to pass all the columns from the upstream components to the 
downstream components, you would override the OnInputPathAttached method to add the columns, because 
this is the first method in which the input columns are available to the component. 


If the component creates output columns based on the columns selected for its input, override the 
SetUsagelype method to select the output columns and to indicate how they will be used. 


If a component with asynchronous outputs creates output columns based on the columns from upstream 
components, and the available upstream columns change, the component should update its output column 
collection. These changes should be detected by the component during Validate, and fixed during 


ReinitializeMetaData. 





NOTE 

When an output column is removed from the output column collection, downstream components in the data flow that 
reference the column are adversely affected. The output column must be repaired without removing and recreating the 
column to prevent breaking the downstream components. For example, if the data type of the column has changed, you 


must update the data type. 











The following code example shows a component that adds an output column to its output column collection for 
each column available from the upstream component. 


public override void OnInputPathAttached(int inputID) 


{ 
IDTSInput10@ input = ComponentMetaData. InputCollection.GetObjectByID(inputID) ; 


IDTSOutput10@ output = ComponentMetaData.OutputCollection[@]; 
IDTSVirtualInput10® vInput = input.GetVirtualInput(); 


foreach (IDTSVirtualInputColumnie@ vCol in vInput.VirtualInputColumnCollection) 


{ 
IDTSOutputColumn1@@ outCol = output.OutputColumnCollection.New(); 


outCol.Name = vCol.Name; 
outCol.SetDataTypeProperties(vCol.DataType, vCol.Length, vCol.Precision, vCol.Scale, vCol.CodePage) ; 


Public Overrides Sub OnInputPathAttached(ByVal inputID As Integer) 


Dim input As IDTSInput1@@ = ComponentMetaData.InputCollection.GetObjectByID(inputID) 
Dim output As IDTSOutput1@@ = ComponentMetaData.OutputCollection(@) 
Dim vInput As IDTSVirtualInput10e® = input.GetVirtualInput() 


For Each vCol As IDTSVirtualInputColumn1@0@ In vInput.VirtualInputColumnCollection 


Dim outCol As IDTSOutputColumn1e@ = output.OutputColumnCollection.New() 
outCol.Name = vCol.Name 
outCol.SetDataTypeProperties(vCol.DataType, vCol.Length, vCol.Precision, vCol.Scale, vCol.CodePage) 


Next 
End Sub 
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Run Time 


Components with asynchronous outputs also execute a different sequence of methods at run time than other 
types of components. First, they are the only components that receive a call to both the PrimeOutput and the 
ProcessInput methods. Components with asynchronous outputs also require access to all the incoming rows 
before they can start processing; therefore, they must cache the input rows internally until all rows have been 
read. Finally, unlike other components, components with asynchronous outputs receive both an input buffer and 


an output buffer. 


Understanding the Buffers 

The input buffer is received by the component during Processinput. This buffer contains the rows added to the 
buffer by upstream components. The buffer also contains the columns of the component's input, in addition to 
the columns that were provided in the output of an upstream component but were not added to the 


asynchronous component's input collection. 


The output buffer, which is provided to the component in PrimeOutput, does not initially contain rows. The 
component adds rows to this buffer and provides the buffer to downstream components when it is full. The 


output buffer contains the columns defined in the component's output column collection, in addition to any 
columns that other downstream components have added to their outputs. 


This is different behavior from that of components with synchronous outputs, which receive a single shared 
buffer. The shared buffer of a component with synchronous outputs contains both the input and output columns 
of the component, in addition to columns added to the outputs of upstream and downstream components. 


Processing Rows 

Caching Input Rows 

When you write a component with asynchronous outputs, you have three options for adding rows to the output 
buffer. You can add them as input rows are received, you can cache them until the component has received all 
the rows from the upstream component, or you can add them when it is appropriate to do so for the 
component. The method that you choose depends on the requirements of the component. For example, the Sort 
component requires that all the upstream rows be received before they can be sorted. Therefore, it waits until all 
rows have been read before adding rows to the output buffer. 


The rows that are received in the input buffer must be cached internally by the component until it is ready to 
process them. The incoming buffer rows can be cached in a data table, a multidimensional array, or any other 


internal structure. 


Adding Output Rows 

Whether you add rows to the output buffer as they are received or after receiving all of the rows, you do so by 
calling the AddRow method on the output buffer. After you have added the row, you set the values of each 
column in the new row. 


Because there are sometimes more columns in the output buffer than in the output column collection of the 
component, you must locate the index of the appropriate column in the buffer before you can set its value. The 
FindColumnByLineagelD method of the BufferManager property returns the index of the column in the buffer 
row with the specified lineage ID, which is then used to assign the value to the buffer column. 


The PreExecute method, which is called before the PrimeOutput method or the Processinput method, is the first 
method where the Buffer Manager property is available, and the first opportunity to locate the indexes of the 
columns in the input and output buffers. 


Sample 


The following sample shows a simple transformation component with asynchronous outputs that adds rows to 
the output buffer as they are received. This sample does not demonstrate all the methods and functionality 
discussed in this topic. It demonstrates the important methods that every custom transformation component 
with asynchronous outputs must override, but does not contain code for design-time validation. Also, the code 
in ProcessInput assumes that the output column collection has one column for each column in the input column 


collection. 


using System; 

using Microsoft.SqlServer.Dts.Pipeline; 

using Microsoft.SqlServer.Dts.Pipeline.Wrapper; 
using Microsoft.SqlServer.Dts.Runtime.Wrapper ; 


namespace Microsoft.Samples.SqlServer.Dts 
{ 
[DtsPipelineComponent(DisplayName = "AsynchronousOutput") ] 
public class AsynchronousOutput : PipelineComponent 
{ 
PipelineBuffer outputBuffer; 
int[] inputColumnBufferIndexes ; 
int[] outputColumnBufferIndexes ; 


public override void ProvideComponentProperties() 
if 


// Let the base class add the input and output objects. 
base.ProvideComponentProperties() ; 


// Name the input and output, and make the 
// output asynchronous. 
ComponentMetaData.InputCollection[@].Name = "Input"; 
ComponentMetaData.OutputCollection[@].Name = "AsyncOutput"; 
ComponentMetaData.OutputCollection[9@].SynchronousInputID = @; 
} 
public override void PreExecute() 
{ 
IDTSInput10@ input = ComponentMetaData.InputCollection[@]; 
IDTSOutput10@ output = ComponentMetaData.OutputCollection[@]; 


inputColumnBufferIndexes = new int[input.InputColumnCollection.Count] ; 
outputColumnBufferIndexes = new int[output.OutputColumnCollection. Count]; 


for (int col = @; col < input.InputColumnCollection.Count; col++) 
inputColumnBufferIndexes[col] = BufferManager .FindColumnByLineageID(input.Buffer, 
input. InputColumnCollection[col].LineageID) ; 


for (int col = @; col < output.OutputColumnCollection.Count; col++) 
outputColumnBufferIndexes[col] = BufferManager.FindColumnByLineageID(output. Buffer, 
output .OutputColumnCollection[col].LineageID) ; 


} 
public override void PrimeOutput(int outputs, int[] outputIDs, PipelineBuffer[] buffers) 
{ 
if (buffers.Length != @) 
outputBuffer = buffers[@]; 
t 
public override void ProcessInput(int inputID, PipelineBuffer buffer) 
{ 
// Advance the buffer to the next row. 
while (buffer.NextRow()) 
{ 
// Add a row to the output buffer. 
outputBuffer.AddRow() ; 
for (int x = @; x < inputColumnBufferIndexes.Length; x++) 
{ 
// Copy the data from the input buffer column to the output buffer column. 
outputBuffer [outputColumnBufferIndexes[x]] = buffer[inputColumnBufferIndexes[x] ]; 
} 
} 
if (buffer. EndOfRowset) 
{ 
// EndOfRowset on the input buffer is true. 
// Set EndOfRowset on the output buffer. 
outputBuffer .SetEndOfRowset () ; 
} 
} 


Imports System 

Imports Microsoft.SqlServer.Dts.Pipeline 

Imports Microsoft.SqlServer.Dts.Pipeline.Wrapper 
Imports Microsoft.SqlServer.Dts.Runtime.Wrapper 


Namespace Microsoft.Samples.SqlServer.Dts 


<DtsPipelineComponent (DisplayName:="AsynchronousOutput")> _ 
Public Class AsynchronousOutput 


Inherits PipelineComponent 


Private outputBuffer As PipelineBuffer 
Private inputColumnBufferIndexes As Integer() 
Private outputColumnBufferIndexes As Integer() 


Public Overrides Sub ProvideComponentProperties() 


" Let the base class add the input and output objects. 
Me.ProvideComponentProperties() 


" Name the input and output, and make the 
" output asynchronous. 
ComponentMetaData.InputCollection(@).Name = "Input" 
ComponentMetaData.OutputCollection(@).Name = "AsyncOutput" 
ComponentMetaData.OutputCollection(@).SynchronousInputID = @ 


End Sub 
Public Overrides Sub PreExecute() 


Dim input As IDTSInput1@@ = ComponentMetaData.InputCollection(@) 
Dim output As IDTSOutput1@@ = ComponentMetaData.OutputCollection(@) 


ReDim inputColumnBufferIndexes (input .InputColumnCollection. Count) 
ReDim outputColumnBufferIndexes (output .OutputColumnCollection.Count) 


For col As Integer = @ To input. InputColumnCollection. Count 
inputColumnBufferIndexes(col) = BufferManager .FindColumnByLineageID(input.Buffer, 
input. InputColumnCollection(col).LineageID) 
Next 


For col As Integer = @ To output.OutputColumnCollection.Count 
outputColumnBufferIndexes(col) = BufferManager.FindColumnByLineageID(output. Buffer, 
output .OutputColumnCollection(col).LineageID) 
Next 


End Sub 
Public Overrides Sub PrimeOutput(ByVal outputs As Integer, ByVal outputIDs As Integer(), ByVal 


buffers As PipelineBuffer() ) 


If buffers.Length <> @ Then 
outputBuffer = buffers(@) 
Ende it 


End Sub 
Public Overrides Sub ProcessInput(ByVal inputID As Integer, ByVal buffer As PipelineBuffer) 


" Advance the buffer to the next row. 
While (buffer .NextRow()) 


" Add a row to the output buffer. 
outputBuffer .AddRow( ) 
For x As Integer = @ To inputColumnBufferIndexes.Length 


" Copy the data from the input buffer column to the output buffer column. 
outputBuffer (outputColumnBufferIndexes(x)) = buffer(inputColumnBuffer Indexes (x) ) 


Next 
End While 


If buffer.EndOfRowset = True Then 
" EndOfRowset on the input buffer is true. 
" Set the end of row set on the output buffer. 
outputBuffer .SetEndOfRowset () 
End If 
End Sub 
End Class 
End Namespace 


See Also 


Developing a Custom Transformation Component with Synchronous Outputs 
Understanding Synchronous and Asynchronous Transformations 
Creating an Asynchronous Transformation with the Script Component 
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Transformation components with synchronous outputs receive rows from upstream components, and read or 
modify the values in the columns of these rows as they pass the rows to downstream components. They may 
also define additional output columns that are derived from the columns provided by upstream components, 
but they do not add rows to the data flow. For more information about the difference between synchronous and 
asynchronous components, see Understanding Synchronous and Asynchronous Transformations. 


This kind of component is suited for tasks where the data is modified inline as it is provided to the component 
and where the component does not have to see all the rows before processing them. It is the easiest component 
to develop because transformations with synchronous outputs typically do not connect to external data sources, 
manage external metadata columns, or add rows to output buffers. 


Creating a transformation component with synchronous outputs involves adding an IDTSInput100 that will 
contain the upstream columns selected for the component, and a |IDTSOutput100 object that may contain 
derived columns created by the component. It also includes implementing the design-time methods, and 
providing code that reads or modifies the columns in the incoming buffer rows during execution. 


This section provides the information that is required to implement a custom transformation component, and 
provides code examples to help you better understand the concepts. 


Design Time 


The design-time code for this component involves creating the inputs and outputs, adding any additional output 
columns that the component generates, and validating the configuration of the component. 


Creating the Component 


The inputs, outputs, and custom properties of the component are typically created during the 
ProvideComponentProperties method. There are two ways that you can add the input and the output of a 
transformation component with synchronous outputs. You can use the base class implementation of the method 
and then modify the default input and output that it creates, or you can explicitly add the input and output 
yourself. 


The following code example shows an implementation of ProvideComponentProperties that explicitly adds the 
input and output objects. The call to the base class that would accomplish the same thing is included in a 
comment. 


using Microsoft.SqlServer.Dts.Pipeline; 
using Microsoft.SqlServer.Dts.Pipeline.Wrapper; 
using Microsoft.SqlServer.Dts.Runtime; 


namespace Microsoft.Samples.SqlServer.Dts 


{ 


[DtsPipelineComponent(DisplayName = "SynchronousComponent", ComponentType = ComponentType. Transform) ] 
public class SyncComponent : PipelineComponent 


{ 


public override void ProvideComponentProperties() 


{ 
// Add the input. 


IDTSInput10@ input = ComponentMetaData.InputCollection.New() ; 
input.Name = "Input"; 


// Add the output. 

IDTSOutput10@ output = ComponentMetaData.OutputCollection.New(); 
output.Name = "Output"; 

output.SynchronousInputID = input.ID; 


// Alternatively, you can let the base class add the input and output 
// and set the SynchronousInputID of the output to the ID of the input. 
// base.ProvideComponentProperties(); 


Imports Microsoft.SqlServer.Dts.Pipeline 
Imports Microsoft.SqlServer.Dts.Pipeline.Wrapper 
Imports Microsoft.SqlServer.Dts.Runtime 


<DtsPipelineComponent (DisplayName:="SynchronousComponent", ComponentType:=ComponentType.Transform)> _ 
Public Class SyncComponent 
Inherits PipelineComponent 


Public Overrides Sub ProvideComponentProperties() 


" Add the input. 
Dim input As IDTSInput1@@ = ComponentMetaData.InputCollection.New() 
input.Name = "Input" 


" Add the output. 

Dim output As IDTSOutput10@ = ComponentMetaData.OutputCollection.New() 
output.Name = "Output" 

output.SynchronousInputID = Input.ID 


" Alternatively, you can let the base class add the input and output 
"and set the SynchronousInputID of the output to the ID of the input. 
" base.ProvideComponentProperties(); 


End Sub 


End Class 


Creating and Configuring Output Columns 


Although transformation components with synchronous outputs do not add rows to buffers, they may add extra 
output columns to their output. Typically, when a component adds an output column, the values for the new 
output column are derived at run time from the data that is contained in one or more of the columns provided 


to the component by an upstream component. 


After an output column has been created, its data type properties must be set. Setting the data type properties 
of an output column requires special handling and is performed by calling the SetDataTypeProperties method. 


This method is required because the DataType, Length, Precision, and CodePage properties are individually 


read-only, because each depends on the settings of the other. This method guarantees that the values of the 


properties are set consistently, and the data flow task validates that they are set correctly. 


The DataType of the column determines the values that are set for the other properties. The following table 


shows the requirements on the dependent properties for each DataType. The data types not listed have their 


dependent properties set to zero. 


DATATYPE LENGTH SCALE PRECISION CODEPAGE 
DT_DECIMAL 0 Greater than 0 and 0 0 

less than or equal to 

28. 
DT_CY 0 0 0 0 
DT_NUMERIC 0 Greater than 0 and Greater than or equal 0 

less than or equal to to 1 and less than or 

28, and less than equal to 38. 

Precision. 
DT_BYTES Greater than 0. 0 0 0 
DT_STR Greater than 0 and 0 0 Not 0, and a valid 

less than 8000. code page. 

DT_WSTR Greater than 0 and 0 0 0 


less than 4000. 


Because the restrictions on the data type properties are based on the data type of the output column, you must 
choose the correct Integration Services data type when you work with managed types. The base class provides 
three helper methods, Conver tBufferDataTypeToFitManaged, BufferlypeToDataRecordType, and 
DataRecordTypeToBufferType that assist managed component developers in selecting an SSIS data type given a 
managed type. These methods convert managed data types to SSIS data types, and vice versa. 


Run Time 


Generally, the implementation of the run-time part of the component is categorized into two tasks-locating the 
input and output columns of the component in the buffer, and reading or writing the values of these columns in 
the incoming buffer rows. 


Locating Columns in the Buffer 


The number of columns in the buffers that are provided to a component during execution will likely exceed the 
number of columns in the input or output collections of the component. This is because each buffer contains all 
the output columns defined in the components in a data flow. To ensure that the buffer columns are correctly 
matched to the columns of the input or output, component developers must use the FindColumnByLineagelD 
method of the BufferManager. This method locates a column in the specified buffer by its lineage ID. Typically 
columns are located during PreExecute because this is the first run-time method where the BufferManager 
property becomes available. 


The following code example shows a component that locates indexes of the columns in its input and output 
column collection during PreExecute. The column indexes are stored in an integer array, and can be accessed by 
the component during ProcessI|nput. 


int []inputColumns; 
int []outputColumns; 


public override void PreExecute() 


{ 
IDTSInput10@ input = ComponentMetaData.InputCollection[@]; 
IDTSOutput10@ output = ComponentMetaData.OutputCollection[@]; 


inputColumns = new int[input.InputColumnCollection.Count]; 
outputColumns = new int[output.OutputColumnCollection.Count]; 


for(int col=0; col < input.InputColumnCollection.Count; col++) 


it 
IDTSInputColumn1e@ inputColumn = input.InputColumnCollection[col]; 
inputColumns[col] = BufferManager.FindColumnByLineageID(input.Buffer, inputColumn.LineageID) ; 


for(int col=@; col < output.OutputColumnCollection.Count; col++) 


{ 
IDTSOutputColumn1e@e@ outputColumn = output.OutputColumnCollection[col]; 


outputColumns[col] = BufferManager.FindColumnByLineageID(input.Buffer, outputColumn.LineageID) ; 


Public Overrides Sub PreExecute() 


Dim input As IDTSInput1@@ = ComponentMetaData.InputCollection(@) 
Dim output As IDTSOutput1@@ = ComponentMetaData.OutputCollection(@) 


ReDim inputColumns (input. InputColumnCollection.Count) 
ReDim outputColumns(output.OutputColumnCollection.Count) 


For col As Integer = @ To input. InputColumnCollection. Count 


Dim inputColumn As IDTSInputColumn1@@ = input. InputColumnCollection(col) 
inputColumns(col) = BufferManager.FindColumnByLineageID(input.Buffer, inputColumn.LineageID) 
Next 


For col As Integer = @ To output.OutputColumnCollection.Count 


Dim outputColumn As IDTSOutputColumn1@@ = output.OutputColumnCollection(col) 
outputColumns(col) = BufferManager.FindColumnByLineageID(input.Buffer, outputColumn.LineageID) 
Next 


End Sub 


Processing Rows 


Components receive PipelineBuffer objects that contain rows and columns in the ProcessInput method. During 
this method the rows in the buffer are iterated, and the columns identified during PreExecute are read and 
modified. The method is called repeatedly by the data flow task until no more rows are provided from the 


upstream component. 


An individual column in the buffer is read or written by using the array indexer access method, or by using one 
of the Get or Set methods. The Get and Set methods are more efficient and should be used when the data type 
of the column in the buffer is known. 


The following code example shows an implementation of the ProcessInput method that processes incoming 


rows. 


public override void ProcessInput( int InputID, PipelineBuffer buffer) 


{ 
while( buffer.NextRow() ) 
{ 
for(int x=0; x < inputColumns.Length;x++) 
{ 
if(!buffer.IsNull(inputColumns[x])) 
{ 
object columnData = buffer[inputColumns[x]]; 
// TODO: Modify the column data. 
buffer[inputColumns[x]] = columnData; 
} 
t 
} 
t 


Public Overrides Sub ProcessInput(ByVal InputID As Integer, ByVal buffer As PipelineBuffer) 
While (buffer .NextRow()) 
For x As Integer = @ To inputColumns.Length 
if buffer.IsNull(inputColumns(x)) = false then 
Dim columnData As Object = buffer(inputColumns(x) ) 
" TODO: Modify the column data. 


buffer(inputColumns(x)) = columnData 


End If 
Next 


End While 
End Sub 


Sample 


The following sample shows a simple transformation component with synchronous outputs that converts the 
values of all string columns to uppercase. This sample does not demonstrate all the methods and functionality 
discussed in this topic. It demonstrates the important methods that every custom transformation component 

with synchronous outputs must override, but does not contain code for design-time validation. 


using System; 

using System.Collections; 

using Microsoft.SqlServer.Dts.Pipeline; 

using Microsoft.SqlServer.Dts.Pipeline.Wrapper; 
using Microsoft.SqlServer.Dts.Runtime.Wrapper; 


namespace Uppercase 


{ 
[DtsPipelineComponent(DisplayName = "Uppercase") ] 


public class Uppercase : PipelineComponent 


{ 


ArrayList m_ColumnIndexList = new ArrayList(); 


public override void ProvideComponentProperties() 


{ 
base.ProvideComponentProperties() ; 
ComponentMetaData.InputCollection[@].Name = "Uppercase Input"; 
ComponentMetaData.OutputCollection[@].Name = "Uppercase Output"; 
} 
public override void PreExecute() 
if 
IDTSInput10@ input = ComponentMetaData.InputCollection[@]; 
IDTSInputColumnCollection10e inputColumns = input. InputColumnCollection; 
foreach (IDTSInputColumn1e@@ column in inputColumns) 
{ 
if (column.DataType == DataType.DT_STR || column.DataType == DataType.DT_WSTR) 
{ 
m_ColumnIndexList.Add( (int) BufferManager .FindColumnByLineageID(input.Buffer, column.LineageID) ) ; 
i; 
t 
t 
public override void ProcessInput(int inputID, PipelineBuffer buffer) 
{ 
while (buffer.NextRow()) 
{ 
foreach (int columnIndex in m_ColumnIndexList) 
{ 
string str = buffer.GetString(columnIndex) ; 
buffer.SetString(columnIndex, str.ToUpper()); 
t 
t 
} 


Imports System 

Imports System.Collections 

Imports Microsoft.SqlServer.Dts.Pipeline 

Imports Microsoft.SqlServer.Dts.Pipeline.Wrapper 
Imports Microsoft.SqlServer.Dts.Runtime.Wrapper 
Namespace Uppercase 


<DtsPipelineComponent (DisplayName="Uppercase")> _ 
Public Class Uppercase 
Inherits PipelineComponent 
Private m_ColumnIndexList As ArrayList = New ArrayList 


Public Overrides Sub ProvideComponentProperties() 
MyBase. ProvideComponentProperties 
ComponentMetaData.InputCollection(@).Name = "Uppercase Input" 
ComponentMetaData.OutputCollection(@).Name = "Uppercase Output" 
End Sub 


Public Overrides Sub PreExecute() 
Dim input As IDTSInput10@ = ComponentMetaData. InputCollection(@) 
Dim inputColumns As IDTSInputColumnCollection10® = input.InputColumnCollection 
For Each column As IDTSInputColumni@e@ In inputColumns 
If column.DataType = DataType.DT_STR OrElse column.DataType = DataType.DT_WSTR Then 
m_ColumnIndexList .Add(CType(BufferManager .FindColumnByLineageID(input.Buffer, column.LineageID) , 
Integer) ) 
End If 
Next 
End Sub 


Public Overrides Sub ProcessInput(ByVal inputID As Integer, ByVal buffer As PipelineBuffer) 
While buffer.NextRow 
For Each columnIndex As Integer In m_ColumnIndexList 
Dim str As String = buffer.GetString(columnIndex) 
buffer.SetString(columnIndex, str.ToUpper) 
Next 
End While 
End Sub 
End Class 
End Namespace 


See Also 


Developing a Custom Transformation Component with Asynchronous Outputs 
Understanding Synchronous and Asynchronous Transformations 
Creating a Synchronous Transformation with the Script Component 
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A data flow component with multiple inputs may consume excessive memory if its multiple inputs produce data 
at uneven rates. When you develop a custom data flow component that supports two or more inputs, you can 
manage this memory pressure by using the following members in the Microsoft.SqlServer.Dts.Pipeline 
namespace: 


© The SupportsBackPressure property of the DtsPipelineComponentAttribute class. Set the value of this 
property to true if you want to implement the code that is necessary for your custom data flow 


component to manage data flowing at uneven rates. 


e The IsinputReady method of the PipelineComponent class. You must provide an implementation of this 
method if you set the SupportsBackPressure property to true. If you do not provide an implementation, 
the data flow engine raises an exception at run time. 


e The GetDependentinputs method of the PipelineComponent class. You must also provide an 
implementation of this method if you set the SupportsBackPressure property to true and your custom 
component supports more than two inputs. If you do not provide an implementation, the data flow 
engine raises an exception at run time if the user attaches more than two inputs. 


Together, these members enable you to develop a solution for memory pressure that is similar to the solution 
that Microsoft developed for the Merge and Merge Join transformations. 


Setting the SupportsBackPressure Property 


The first step in implementing better memory management for a custom data flow component that supports 
multiple inputs is to set the value of the SupportsBackPressure property to true in the 
DtsPipelineComponentAttribute. When the value of SupportsBackPressure is true, the data flow engine calls the 
IsInputReady method and, when there are more than two inputs, also calls the GetDependentinputs method at 
run time. 


Example 


In the following example, the implementation of the DtsPipelineComponentAttribute sets the value of 
SupportsBackPressure to true. 


[DtsPipelineComponent(ComponentType = ComponentType.Transform, 

DisplayName = "Shuffler", 

Description = "Shuffle the rows from input.”, 

SupportsBackPressure = true, 

LocalizationType = typeof(Localized), 

IconResource = "Microsoft.Samples.SqlServer.Dts.MIBPComponent.ico") 
] 
public class Shuffler : Microsoft.SqlServer.Dts.Pipeline.PipelineComponent 


{ 


} 


Implementing the IsinputReady Method 


When you set the value of the SupportsBackPressure property to true in the DtsPipelineComponentAttribute 
object, you must also provide an implementation for the IsInputReady method of the PipelineComponent class. 





NOTE 


Your implementation of the IsInputReady method should not call the implementations in the base class. The default 


implementation of this method in the base class simply raises a NotImplementedException. 











When you implement this method, you set the status of an element in the Boolean canProcess array for each of 
the component's inputs. (The inputs are identified by their ID values in the /nput/Ds array.) When you set the 
value of an element in the canProcess array to true for an input, the data flow engine calls the component's 
ProcessInput method and provides more data for the specified input. 


While more upstream data is available, the value of the canProcess array element for at least one input must 


always be true, or processing stops. 


The data flow engine calls the IsinoutReady method before sending each buffer of data to determine which 
inputs are waiting to receive more data. When the return value indicates that an input is blocked, the data flow 
engine temporarily caches additional buffers of data for that input instead of sending them to the component. 





NOTE 
You do not call the IsInputReady or GetDependentInputs methods in your own code. The data flow engine calls these 
methods, and the other methods of the PipelineComponent class that you override, when the data flow engine runs 


your component. 





Example 


In the following example, the implementation of the IsinputReady method indicates that an input is waiting to 
receive more data when the following conditions are true: 


e More upstream data is available for the input ( !inputEor ). 


e The component does not currently have data available to process for the input in the buffers that the 


component has already received ( inputBuffers[inputIndex].CurrentRow() == null ). 


If an input is waiting to receive more data, the data flow component indicates this by setting to true the value of 
the element in the canProcess array that corresponds to that input. 


Conversely, when the component still has data available to process for the input, the example suspends the 
processing of the input. The example does this by setting to false the value of the element in the canProcess 
array that corresponds to that input. 


public override void IsInputReady(int[] inputIDs, ref bool[] canProcess) 


for (int i = 0; i < inputIDs.Length; i++) 
{ 
int inputIndex = ComponentMetaData.InputCollection.GetObjectIndexByID(inputIDs[i]); 
canProcess[i] = (inputBuffers[inputIndex].CurrentRow() == null) 
&& !inputEOR[inputIndex]; 
t 
t 


The preceding example uses the Boolean inputEor array to indicate whether more upstream data is available 





for each input. Eor in the name of the array represents "end of rowset" and refers to the EndOfRowset property 
of data flow buffers. In a portion of the example that is not included here, the ProcessInput method checks the 
value of the EndOfRowset property for each buffer of data that it receives. When a value of true indicates that 
there is no more upstream data available for an input, the example sets the value of the inputeor array element 
for that input to true. This example of the IsinputReady method sets the value of the corresponding element in 
the canProcess array to false for an input when the value of the inputeor array element indicates that there is 
no more upstream data available for the input. 


Implementing the GetDependentInputs Method 


When your custom data flow component supports more than two inputs, you must also provide an 
implementation for the GetDependentInputs method of the PipelineComponent class. 


NOTE 


Your implementation of the GetDependentinputs method should not call the implementations in the base class. The 


default implementation of this method in the base class simply raises a NotI mplementedException. 











The data flow engine only calls the GetDependentinputs method when the user attaches more than two inputs 
to the component. When a component has only two inputs, and the IsinputReady method indicates that one 
input is blocked (canProcess = false), the data flow engine knows that the other input is waiting to receive more 
data. However, when there are more than two inputs, and the IsilnoputReady method indicates that one input is 
blocked, the additional code in the GetDependentinputs identifies which inputs are waiting to receive more data. 


NOTE 


You do not call the IsInputReady or GetDependentInputs methods in your own code. The data flow engine calls these 
methods, and the other methods of the PipelineComponent class that you override, when the data flow engine runs 
your component. 











Example 


For a specific input that is blocked, the following implementation of the GetDependentinputs method returns a 
collection of the inputs that are waiting to receive more data, and are therefore blocking the specified input. The 
component identifies the blocking inputs by checking for inputs other than the blocked input that do not 
currently have data available to process in the buffers that the component has already received ( 
inputBuffers[i].CurrentRow() == null ). The GetDependentinputs method then returns the collection of blocking 
inputs as a collection of input IDs. 


public override Collection<int> GetDependentInputs(int blockedInputID) 
{ 

Collection<int> currentDependencies = new Collection<int>(); 

for (int i = 0; i < ComponentMetaData.InputCollection.Count; i++) 


{ 
if (ComponentMetaData.InputCollection[i].ID != blockedInputID 
&& inputBuffers[i].CurrentRow() == null) 
{ 
currentDependencies .Add(ComponentMetaData. InputCollection[i].ID); 
} 
t 


return currentDependencies; 
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This section covers the specifics of developing source components, transformation components with 
synchronous outputs, transformation components with asynchronous outputs, and destination components. 


For information about component development in general, see Developing a Custom Data Flow Component. 


In This Section 


Developing a Custom Source Component 
Contains information on developing a component that accesses data from an external data source and supplies 
it to downstream components in the data flow. 


Developing a Custom Transformation Component with Synchronous Outputs 
Contains information on developing a transformation component whose outputs are synchronous to its inputs. 
These components do not add data to the data flow, but process data as it passes through. 


Developing a Custom Transformation Component with Asynchronous Outputs 
Contains information on developing a transformation component whose outputs are not synchronous to its 
inputs. These components receive data from upstream components, but also add data to the dataflow. 


Developing a Custom Destination Component 
Contains information on developing a component that receives rows from upstream components in the data 
flow and writes them to an external data source. 


Reference 


Microsoft.SqlServer.Dts.Pipeline 
Contains the classes and interfaces used to create custom data flow components. 


Microsoft.SqlServer.Dts.Pipeline.Wrapper 

Contains the unmanaged classes and interfaces of the data flow task. The developer uses these, and the 
managed Microsoft.SqlServer.Dts.Pipeline namespace, when building a data flow programmatically or creating 
custom data flow components. 


See Also 


Comparing Scripting Solutions and Custom Objects 
Developing Specific Types of Script Components 
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The ConnectionManager class represents physical connections to external data sources. The 
ConnectionManager class isolates the implementation details of the connection from the runtime. This enables 
the runtime to interact with each connection manager in a consistent and predictable manner. Connection 
managers contain a set of stock properties that all connections have in common, such as the Name, ID, 
Description, and ConnectionString. However, the ConnectionString and Name properties are ordinarily the only 
properties required to configure a connection manager. Unlike other programming paradigms, where 
connection classes expose methods such as Open or Connect to physically establish a connection to the data 
source, the run-time engine manages all the connections for the package while it runs. 


The Connections class is a collection of the connection managers that have been added to that package and are 
available for use at run time. You can add more connection managers to the collection by using the Add method 
of the collection, and supplying a string that indicates the connection manager type. The Add method returns the 
ConnectionManager instance that was added to the package. 


Intrinsic Properties 


The ConnectionManager class exposes a set of properties that are common to all connections. However, 
sometimes you need access to properties that are unique to the specific connection type. The Properties 
collection of the ConnectionManager class provides access to these properties. The properties can be retrieved 
from the collection using the indexer or the property name and the GetValue method, and the values are set 
using the SetValue method. The properties of the underlying connection object properties can also be set by 
acquiring an actual instance of the object and setting its properties directly. To get the underlying connection, 
use the InnerObject property of the connection manager. The following line of code shows a C# line that creates 
an ADO.NET connection manager that has the underlying class, ConnectionManagerAdoNetClass. 


ConnectionManagerAdoNetClass cmado = cm.InnerObject as ConnectionManagerAdoNet ; 


This casts the managed connection manager object to its underlying connection object. If you are using C++, the 
Querylnterface method of the ConnectionManager object is called and the interface of the underlying 
connection object is requested. 


The following table lists the connection managers included with Integration Services. and the string that is used 
in the package.Connections.Add("xxx") Statement. For a list of all connection managers, see Integration Services 
(SSIS) Connections. 


STRING CONNECTION MANAGER 

"OLEDB" Connection manager for OLE DB connections. 
"ODBC" Connection manager for ODBC connections. 

"ADO" Connection manager for ADO connections. 
"ADO.NET:SQL" Connection manager for ADO.NET (SQL data provider) 


connections. 


STRING 


"ADO.NET:OLEDB" 


"FLATFILE" 


"FILE" 


"MULTIFLATFILE" 


"MULTIFILE" 


"SQLMOBILE" 


"MSOLAP100" 


"FTP" 


“HTTP” 


"MSMQ" 


"SMTP" 


"WMI" 


CONNECTION MANAGER 


Connection manager for ADO.NET (OLE DB data provider) 
connections. 


Connection manager for flat file connections. 


Connection manager for file connections. 


Connection manager for multiple flat file connections. 


Connection manager for multiple file connections. 


Connection manager for SQL Server Compact connections. 


Connection manager for Analysis Services connections. 


Connection manager for FTP connections. 


Connection manager for HTTP connections. 


Connection manager for Message Queuing (also known as 
MSMQ) connections. 


Connection manager for SMTP connections. 


Connection manager for Microsoft Windows Management 
Instrumentation (WMI) connections. 


The following code example demonstrates adding an OLE DB and FILE connection to the Connections collection 


of a Package. The example then sets the ConnectionString, Name, and Description properties. 


using System; 
using Microsoft.SqlServer.Dts.Runtime; 


namespace Microsoft.SqlServer.Dts.Samples 
{ 
class Program 
{ 
static void Main(string[] args) 
{ 
// Create a package, and retrieve its connections. 
Package pkg = new Package(); 
Connections pkgConns = pkg.Connections; 


// Add an OLE DB connection to the package, using the 
// method defined in the AddConnection class. 
CreateConnection myOLEDBConn = new CreateConnection(); 
myOLEDBConn.CreateOLEDBConnection(pkg) ; 


// View the new connection in the package. 
Console.WriteLine("Connection description: {0@}", 
pkg.Connections["SSIS Connection Manager for OLE DB"].Description) ; 


// Add a second connection to the package. 
CreateConnection myFileConn = new CreateConnection(); 
myFileConn.CreateFileConnection(pkg) ; 


// View the second connection in the package. 
Console.WriteLine("Connection description: {0}", 
pkg.Connections["SSIS Connection Manager for Files"].Description) ; 


Console.WriteLine(); 
Console.WriteLine("Number of connections in package: {@}", pkg.Connections.Count) ; 


Console.Read(); 


} 
// <summary> 
// This class contains the definitions for multiple 
// connection managers. 
// </summary> 
public class CreateConnection 
{ 
// Private data. 
private ConnectionManager ConMgr; 


// Class definition for OLE DB Provider. 
public void CreateOLEDBConnection(Package p) 
it 
ConMgr = p.Connections.Add("OLEDB") ; 
ConMgr.ConnectionString = "Provider=SQLOLEDB.1;" + 
"Integrated Security=SSPI;Initial Catalog=AdventureWorks;" + 
"Data Source=(local);"; 
ConMgr.Name = "SSIS Connection Manager for OLE DB"; 


ConMgr.Description = "OLE DB connection to the AdventureWorks database."; 
} 
public void CreateFileConnection(Package p) 
it 


ConMgr = p.Connections.Add("File"); 

ConMgr.ConnectionString = @"\\<yourserver>\<yourfolder>\books. xml"; 
ConMgr.Name = "SSIS Connection Manager for Files"; 
ConMgr.Description = "Flat File connection"; 


Imports Microsoft.SqlServer.Dts.Runtime 
Module Module1 


Sub Main() 
" Create a package, and retrieve its connections. 

Dim pkg As New Package() 

Dim pkgConns As Connections = pkg.Connections 


" Add an OLE DB connection to the package, using the 
" method defined in the AddConnection class. 

Dim myOLEDBConn As New CreateConnection() 
myOLEDBConn.CreateOLEDBConnection(pkg) 

" View the new connection in the package. 
Console.WriteLine("Connection description: {0@}", 


pkg.Connections("SSIS Connection Manager for OLE DB") .Description) 
" Add a second connection to the package. 
Dim myFileConn As New CreateConnection() 
myFileConn.CreateFileConnection(pkg) 
" View the second connection in the package. 
Console.WriteLine("Connection description: {0}", 


pkg.Connections("SSIS Connection Manager for Files") .Description) 


Console.WriteLine() 
Console.WriteLine("Number of connections in package: {@}", pkg.Connections.Count) 


Console. Read() 
End Sub 
End Module 


" This class contains the definitions for multiple 
"connection managers. 


Public Class CreateConnection 


Private data. 
Private ConMgr As ConnectionManager 


" Class definition for OLE DB provider. 
Public Sub CreateOLEDBConnection(ByVal p As Package) 
ConMgr = p.Connections.Add("OLEDB") 
ConMgr.ConnectionString = "Provider=SQLOLEDB.1;" & _ 
"Integrated Security=SSPI;Initial Catalog=AdventureWorks;" & _ 
"Data Source=(local);" 
ConMgr.Name = "SSIS Connection Manager for OLE DB” 
ConMgr.Description = "OLE DB connection to the AdventureWorks database.” 
End Sub 


Public Sub CreateFileConnection(ByVal p As Package) 
ConMgr = p.Connections.Add("File") 
ConMgr.ConnectionString = "\\<yourserver>\<yourfolder>\books. xml" 
ConMgr.Name = "SSIS Connection Manager for Files" 
ConMgr.Description = "Flat File connection" 

End Sub 


End Class 


Sample Output: 


Connection description: OLE DB connection to the AdventureWorks database. 


Connection description: Flat File connection. 


Number of connections in package: 2 


External Resources 


Technical article, Connection Strings, on carlprothman.net. 


See Also 
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If you need to create packages dynamically, or to manage and execute Integration Services packages outside the 
development environment, you can manipulate packages programmatically. In this approach, you have a 
continuous range of options: 


e Load and execute an existing package without modification. 
e Load an existing package, reconfigure it (for example, for a different data source), and execute it. 


e@ Create a new package, add and configure components object by object and property by property, save it, 
and execute it. 


You can use the Integration Services object model to write code that creates, configures, and executes packages 
in any managed programming language. For example, you may want to create metadata-driven packages that 
configure their connections or their data sources, transformations, and destinations based on the selected data 
source and its tables and columns. 


This section describes and demonstrates how to create and configure a package programmatically line by line. 
At the less complex end of the range of package programming options, you can simply load and run an existing 
package without modification as described in Running and Managing Packages Programmatically. 


An intermediate option not described here is that of loading an existing package as a template, reconfiguring it 
(for example, for a different data source), and executing it. You can also use the information in this section to 
modify the existing objects in a package. 





NOTE 


When you use an existing package as a template and modify existing columns in the data flow, you may have to remove 
existing columns and call the ReinitializeMetaData method of affected components. 











In This Section 


Creating a Package Programmatically 
Describes how to create a package programmatically. 


Adding Tasks Programmatically 
Describes how to add tasks to the package. 


Connecting Tasks Programmatically 
Describes how to control execution of the containers and tasks in a package based on the result of the execution 
of a previous task or container. 


Adding Connections Programmatically 


Describes how to add connection managers to a package. 


Working with Variables Programmatically 
Describes how to add and use variables during package execution. 


Handling Events Programmatically 


Describes how to handle package and task events. 


Enabling Logging Programmatically 
Describes how to enable logging for a package or task, and how to apply custom filters to log events. 


Adding the Data Flow Task Programmatically 
Describes how to add and configure the Data Flow task and its components. 


Discovering Data Flow Components Programmatically 
Describes how to detect the components that are installed on the local computer. 


Adding Data Flow Components Programmatically 
Describes how to add a component to a data flow task. 


Connecting Data Flow Components Programmatically 
Describes how to connect two data flow components. 


Selecting Input Columns Programmatically 
Describes how to select input columns from those that are provided to a component by upstream components 
in the data flow. 


Saving a Package Programmatically 
Describes how to save a package programmatically. 


Reference 


Integration Services Error and Message Reference 
Lists the predefined Integration Services error codes with their symbolic names and descriptions. 


Related Sections 


Extending Packages with Scripting 
Discusses how to extend the control flow by using the Script task, and how to extend the data flow by using the 
Script component. 


Extending Packages with Custom Objects 
Discusses how to create program custom tasks, data flow components, and other package objects for use in 
multiple packages. 


Running and Managing Packages Programmatically 
Discusses how to enumerate, run, and manage packages and the folders in which they are stored. 


External Resources 


e Blog entry, Performance profiling your custom extensions, on blogs.msdn.com. 


See Also 
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The Package object is the top-level container for all other objects in an SSIS project solution. As the top-level 
container, the package is the first object created, and subsequent objects are added to it, and then executed 
within the context of the package. The package itself does not move or transform data. The package relies on the 
tasks it contains to perform the work. Tasks perform most of the work performed by a package, and define the 
functionality of a package. A package is created and executed with just three lines of code, but various tasks and 
ConnectionManager objects are added to give additional functionality to your package. This section discusses 
how to programmatically create a package. It does not provide information about how to create the tasks or the 
ConnectionManager. These are covered in later sections. 


Example 


To write code using the Visual Studio IDE, a reference to Microsoft.SqlServerManagedDTS.DLL is required in 
order to create a using statement ( Imports in Visual Basic .NET) to the Microsoft.SqlServerDts.Runtime. The 


following code sample demonstrates creating an empty package. 


using System; 
using Microsoft.SqlServer.Dts.Runtime; 


namespace Microsoft.SqlServer.Dts.Samples 


{ 


class Program 


{ 


static void Main(string[] args) 
ik 
Package package; 
package = new Package(); 
} 
} 
i 


Imports Microsoft.SqlServer.Dts.Runtime 
Module Module1 
Sub Main() 


Dim package As Package 
package = New Package 


End Sub 


End Module 


To compile and run the sample, press F5 in Visual Studio. To build the code using the C# compiler, csc.exe, at the 
command prompt to compile, use the following command and file references, replacing the <fi/lename> with 
the name of the .cs or .vb file, and giving it an <outputfilename> of your choice. 


csc /target:library /out: <outputfilename>.dll <filename>.cs /r:Microsoft.SqlServer.Managed 
DTS.dll" /r:System.dll 


To build the code using the Visual Basic .NET compiler, vbc.exe, at the command prompt to compile, use the 


following command and file references. 


vbc /target:library /out: <outputfilename>.dll <filename>.vb /r:Microsoft.SqlServer.Managed 
DTS.dll" /r:System.dll 


You can also create a package by loading an existing package that was saved on disk, in the file system, or to 
SQL Server. The difference is that the Application object is first created, and then the package object is filled by 
one of the Application's overloaded methods: LoadPackage for flat files, LoadFromSQLServer for packages 
saved to SQL Server, or LoadFromDtsServer for packages saved to the file system. The following example loads 
an existing package from disk, and then views several properties on the package. 


using System; 
using Microsoft.SqlServer.Dts.Runtime; 


namespace Microsoft.SqlServer.Dts.Samples 
{ 
class ApplicationTests 
( 
static void Main(string[] args) 
{ 
// The variable pkg points to the location of the 
// ExecuteProcess package sample that was installed with 
// the SSIS samples. 
string pkg = @"C:\Program Files\Microsoft SQL Server\100\Samples\Integration Services” + 
@"\Package Samples\ExecuteProcess Sample\ExecuteProcess\UsingExecuteProcess.dtsx"; 


Application app = new Application(); 
Package p = app.LoadPackage(pkg, null); 


// Now that the package is loaded, we can query on 

// its properties. 

int n = p.Configurations.Count; 

DtsProperty p2 = p.Properties["VersionGUID" ] ; 

DTSProtectionLevel pl = p.ProtectionLevel; 
Console.WriteLine("Number of configurations = " + n.ToString()); 
Console.WriteLine("VersionGUID = " + (string)p2.GetValue(p)); 
Console.WriteLine("ProtectionLevel = " + pl.ToString()); 
Console.Read(); 


Imports Microsoft.SqlServer.Dts.Runtime 
Module ApplicationTests 
Sub Main() 
" The variable pkg points to the location of the 
ExecuteProcess package sample that was installed with 
" the SSIS samples. 
Dim pkg As String = _ 
"C:\Program Files\Microsoft SQL Server\100\Samples\Integration Services” & _ 


"\Package Samples\ExecuteProcess Sample\ExecuteProcess\UsingExecuteProcess.dtsx" 


Dim app As Application = New Application() 
Dim p As Package = app.LoadPackage(pkg, Nothing) 


" Now that the package is loaded, we can query on 


its properties. 
Dim n As Integer = p.Configurations.Count 
Dim p2 As DtsProperty = p.Properties("VersionGUID" ) 
Dim pl As DTSProtectionLevel = p.ProtectionLevel 
Console.WriteLine("Number of configurations = " & n.ToString()) 
Console.WriteLine("VersionGUID = " & CType(p2.GetValue(p), String) ) 
Console.WriteLine("ProtectionLevel = " & pl.ToString()) 
Console. Read() 

End Sub 


End Module 


Sample Output: 
Number of configurations = 2 
VersionGUID = {@9016682-89B8-4406-AAC9-AF1E527FF50F } 


ProtectionLevel = DontSaveSensitive 


External Resources 


e Blog entry, API Sample - OleDB source and OleDB destination, on blogs.msdn.com. 


e Blog entry, EZAPI - Updated for SQL Server 2012, on blogs.msdn.com. 


See Also 
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Tasks can be added to the following types of objects in the run-time engine: 

e Package 

e Sequence 

e ForLoop 

e ForEachLoop 


e DtsEventHandler 


These classes are considered containers, and they all inherit the Executables property. Containers can contain a 
collection of tasks, which are executable objects processed by the runtime during execution of the container. The 
order of execution of the objects in the collection is determined any PrecedenceConstraint set on each task in 
the containers. Precedence constraints enable execution branching based on the success, failure, or completion 
of an Executable in the collection. 


Each container has an Executables collection that contains the individual Executable objects. Each executable task 
inherits and implements the Execute method and Validate method. These two methods are called by the run- 
time engine to process each Executable. 


To add a task to a package, you need a container with an Executables existing collection. Most of the time, the 
task that you will add to the collection is a package. To add the new task executable into the collection for that 
container, you call the Add method . The method has a single parameter, a string, that contains the CLSID, 
PROGID, STOCK moniker, or CreationName of the task you are adding. 


Task Names 
Although you can specify a task by name or by ID, the STOCK moniker is the parameter used most often in the 


Add method. To add a task to an executable identified by the STOCK moniker, use the following syntax: 


Executable exec = package.Executables.Add("STOCK:BulkInsertTask") ; 


Dim exec As Executable = package.Executables.Add("STOCK:BulkInsertTask" ) 


The following list shows the names for each task that are used after the STOCK moniker. 
e ActiveXScriptlask 

e BulkinsertTask 

e ExecuteProcessTask 


e ExecutePackageTask 


Exec80PackageTask 


e FileSystemTask 

e@ FTPTask 

e MSMQtTask 

e PipelineTask 

e ScriptTask 

e SendMailTask 

e SQLTask 

e TransferStoredProcedures Task 
e TransferLoginsTask 

e TransferErrorMessages Task 
e TransferJobsTask 

e TransferObjectsTask 

e TransferDatabaseTask 

e WebServicelask 

e WmiDataReaderTask 

e WmiEventWatcherTask 

e XMLTask 


If you prefer a more explicit syntax, or if the task that you want to add does not have a STOCK moniker, you can 
add the task to the executable using its long name. This syntax requires that you also specify the version number 
of the task. 


Executable exec = package.Executables.Add( 
"Microsoft.SqlServer.Dts.Tasks.ScriptTask.ScriptTask, " + 
"Microsoft.SqlServer.ScriptTask, Version=10.0.000.0, " + 


"Culture=neutral, PublickeyToken=89845dcd8080cc91") ; 


Dim exec As Executable = package.Executables.Add( _ 
"Microsoft.SqlServer.Dts.Tasks.ScriptTask.ScriptTask, " & _ 
"Microsoft.SqlServer.ScriptTask, Version=10.0.000.0, " & _ 
"Culture=neutral, PublickeyToken=89845dcd8080cc91" ) 


You can obtain the long name for the task programmatically, without having to specify the task version, by using 
the Assembly QualifiedName property of the class, as shown in the following example. This example requires 
a reference to the Microsoft.SqlServerSQLTask assembly. 


using Microsoft.SqlServer.Dts.Tasks.ExecuteSQLTask; 


Executable exec = package.Executables.Add( 
typeof (Microsoft.SqlServer.Dts.Tasks.ExecuteSQLTask.ExecuteSQLTask) .AssemblyQualifiedName) ; 


Imports Microsoft.SqlServer.Dts.Tasks.ExecuteSQLTask 


Dim exec As Executable = package.Executables.Add( _ 
GetType(Microsoft.SqlServer.Dts.Tasks.ExecuteSQLTask.ExecuteSQLTask) .AssemblyQualifiedName) 


The following code example shows how to create an Executables collection from a new package, and then add a 
File System task and a Bulk Insert task to the collection, by using their STOCK monikers. This example requires a 
reference to the Microsoft.SqlServer.FileSystemTask and Microsoft.SqlServer.BulklnsertTask assemblies. 


using System; 

using Microsoft.SqlServer.Dts.Runtime; 

using Microsoft.SqlServer.Dts.Tasks.FileSystemTask; 
using Microsoft.SqlServer.Dts.Tasks.BulkInsertTask; 


namespace Microsoft.SqlServer.Dts.Samples 
{ 
class Program 
{ 
static void Main(string[] args) 
{ 
Package p = new Package(); 
// Add a File System task to the package. 
Executable execl = p.Executables.Add("STOCK:FileSystemTask") ; 
TaskHost thFileSystemTask = exec1 as TaskHost; 
// Add a Bulk Insert task to the package. 
Executable exec2 = p.Executables.Add("STOCK:BulkInsertTask") ; 
TaskHost thBulkInsertTask = exec2 as TaskHost; 


// Iterate through the package Executables collection. 
Executables pExecs = p.Executables; 
foreach (Executable pExec in pExecs) 
{ 
TaskHost taskHost = (TaskHost)pExec; 
Console.WriteLine("Type {@}", taskHost.InnerObject.ToString()); 


} 
Console.Read(); 


Imports Microsoft.SqlServer.Dts.Runtime 
Imports Microsoft.SqlServer.Dts.Tasks.FileSystemTask 
Imports Microsoft.SqlServer.Dts.Tasks.BulkInsertTask 


Module Module1 
Sub Main() 


Dim p As Package = New Package() 


Add a File System task to the package. 

Dim execl As Executable = p.Executables.Add("STOCK:FileSystemTask") 
Dim thFileSystemTask As TaskHost = CType(exec1, TaskHost) 

" Add a Bulk Insert task to the package. 

Dim exec2 As Executable = p.Executables.Add("STOCK:BulkInsertTask" ) 
Dim thBulkInsertTask As TaskHost = CType(exec2, TaskHost) 


Iterate through the package Executables collection. 

Dim pExecs As Executables = p.Executables 

Dim pExec As Executable 

For Each pExec In pExecs 
Dim taskHost As TaskHost = CType(pExec, TaskHost) 
Console.WriteLine("Type {@}", taskHost.InnerObject.ToString()) 

Next 

Console. Read() 


End Sub 


End Module 


Sample Output: 
Type Microsoft.SqlServer.Dts.Tasks.FileSystemTask.FileSystemTask 


Type Microsoft.SqlServer.Dts.Tasks.BulkInsertTask.BulkInsertTask 


TaskHost Container 


The TaskHost class is a container that does not appear in the graphical user interface, but is very important in 
programming. This class is a wrapper for every task. Tasks that are added to the package by using the Add 
method as an Executable object can be cast as a TaskHost object. When a task is cast as a TaskHost, you can use 
additional properties and methods on the task. Also, the task itself can be accessed through the InnerObject 
property of the TaskHost. Depending on your needs, you may decide to keep the task as a TaskHost object so 
that you can use the properties of the task through the Properties collection. The advantage of using the 
Properties is that you can write more generic code. If you need very specific code for a task, then you should 
cast the task to its appropriate object. 


The following code example shows how to cast a TaskHost, thBulkInsertTask, that contains a Bulkinsertlask, to a 
BulkInsertTask object. 


BulkInsertTask myTask = thBulkInsertTask.InnerObject as BulkInsertTask; 


Dim myTask As BulkInsertTask = CType(thBulkInsertTask.InnerObject, BulkInsertTask) 


The following code example shows how to cast the executable to a TaskHost, and then use the InnerObject 
property to determine which type of executable is contained by the host. 


using System; 


using Microsoft.SqlServer.Dts.Runtime; 


using Microsoft.SqlServer.Dts.Tasks.FileSystemTask; 


using Microsoft.SqlServer.Dts.Tasks.BulkInsertTask; 


namespace Microsoft.SqlServer.Dts.Samples 


{ 


class Program 


{ 


static void Main(string[] args) 


{ 


Package p = new Package(); 

// Add a File System task to the package. 

Executable execl = p.Executables.Add("STOCK:FileSystemTask") ; 
TaskHost thFileSystemTask1 = exec1 as TaskHost; 

// Add a Bulk Insert task to the package. 

Executable exec2 = p.Executables.Add("STOCK:BulkInsertTask") ; 
TaskHost thFileSystemTask2 = exec2 as TaskHost; 


// Iterate through the package Executables collection. 
Executables pExecs = p.Executables; 
foreach (Executable pExec in pExecs) 
{ 
TaskHost taskHost = (TaskHost)pExec; 
if (taskHost.InnerObject is Microsoft.SqlServer.Dts.Tasks.FileSystemTask.FileSystemTask) 
{ 
// Do work with FileSystemTask here. 
Console.WriteLine("Found task of type {@}", taskHost.InnerObject.ToString()); 
t 
else if (taskHost.InnerObject is Microsoft.SqlServer.Dts.Tasks.BulkInsertTask.BulkInsertTask) 
{ 
// Do work with BulkInsertTask here. 
Console.WriteLine("Found task of type {@}", taskHost.InnerObject.ToString()); 
} 
// Add additional statements to check InnerObject, if desired. 


} 
Console.Read(); 


Imports Microsoft.SqlServer.Dts.Runtime 
Imports Microsoft.SqlServer.Dts.Tasks.FileSystemTask 
Imports Microsoft.SqlServer.Dts.Tasks.BulkInsertTask 


Module Module1 
Sub Main() 


Dim p As Package = New Package() 
" Add a File System task to the package. 
Dim execl As Executable = p.Executables.Add("STOCK:FileSystemTask") 
Dim thFileSystemTask1 As TaskHost = CType(execl, TaskHost) 
" Add a Bulk Insert task to the package. 
Dim exec2 As Executable = p.Executables.Add("STOCK:BulkInsertTask" ) 
Dim thFileSystemTask2 As TaskHost = CType(exec2, TaskHost) 
" Iterate through the package Executables collection. 
Dim pExecs As Executables = p.Executables 
Dim pExec As Executable 
For Each pExec In pExecs 
Dim taskHost As TaskHost = CType(pExec, TaskHost) 
If TypeOf taskHost.InnerObject Is Microsoft.SqlServer.Dts.Tasks.FileSystemTask.FileSystemTask Then 
" Do work with FileSystemTask here. 
Console.WriteLine("Found task of type {@}", taskHost.InnerObject.ToString()) 
ElseIf TypeOf taskHost.InnerObject Is Microsoft.SqlServer.Dts.Tasks.BulkInsertTask.BulkInsertTask Then 
" Do work with BulkInsertTask here. 
Console.WriteLine("Found task of type {@}", taskHost.InnerObject.ToString()) 
End If 
" Add additional statements to check InnerObject, if desired. 
Next 


Console. Read() 
End Sub 


End Module 


| 








Sample Output: 
Found task of type Microsoft.SqlServer.Dts.Tasks.FileSystemTask.FileSystemTask 
Found task of type Microsoft.SqlServer.Dts.Tasks.BulkInsertTask.BulkInsertTask 


The Add statement returns an executable that is cast to a TaskHost object from the newly created Executable 
object. 


To set properties or to call methods on the new object, you have two options: 


1. Use the Properties collection of the TaskHost. For example, to obtain a property from the object, use 
th.Properties["propertyname"].GetValue(th)) . To set a property, use 


th.Properties["propertyname"].SetValue(th, <value>); . 


2. Cast the InnerObject of the TaskHost to the task class. For example, to cast the Bulk Insert task to a 
BulklinsertTask after it has been added to a package as an Executable and subsequently cast to a TaskHost, 
use BulkInsertTask myTask = th.InnerObject as BulkInsertTask; . 


Using the TaskHost class in code, instead of casting to the task-specific class has the following advantages: 
e The TaskHostProperties provider does not require a reference to the assembly in the code. 


e You can code generic routines that work for any task, because you do not have to know the name of the 
task at compile time. Such generic routines include methods where you pass in the name of the task to 
the method, and the method code works for all tasks. This is a good method for writing test code. 


Casting from the TaskHost to the task-specific class has the following advantages: 
e The Visual Studio project gives you statement completion (IntelliSense). 
e@ The code may run faster. 


e Task-specific objects enable early binding and the resulting optimizations. For more information about 
early and late binding, see the topic "Early and Late Binding" in Visual Basic Language Concepts. 


The following code example expands on the concept of reusing task code. Instead of casting tasks to their 
specific class equivalents, the code example shows how to cast the executable to a TaskHost, and then uses the 
Properties to write generic code against all the tasks. 


using System; 
using Microsoft.SqlServer.Dts.Runtime; 


namespace Microsoft.SqlServer.Dts.Samples 


ib 
class Program 
{ 
static void Main(string[] args) 
{ 
Package package = new Package(); 
string[] tasks = { "STOCK:SQLTask", "STOCK:ScriptTask", 
"STOCK: ExecuteProcessTask", "STOCK:PipelineTask", 
"STOCK: FTPTask", "STOCK:SendMailTask", "STOCK:MSMQTask" }; 
foreach (string s in tasks) 
{ 
TaskHost taskhost = package.Executables.Add(s) as TaskHost; 
DtsProperties props = taskhost.Properties; 
Console.WriteLine("Enumerating properties on " + taskhost.Name) ; 
Console.WriteLine(" TaskHost.InnerObject is " + taskhost.InnerObject.ToString()); 
Console.WriteLine(); 
foreach (DtsProperty prop in props) 
{ 
Console.WriteLine("Properties for " + prop.Name) ; 
Console.WriteLine("Name : " + prop.Name) ; 
Console.WriteLine("Type : " + prop.Type.ToString()); 
Console.WriteLine("Readable : " + prop.Get.ToString()); 
Console.WriteLine("Writable : " + prop.Set.ToString()); 
Console.WriteLine(); 
t 
} 
Console.Read(); 
} 
} 


Imports Microsoft.SqlServer.Dts.Runtime 


Module Module1 


Sub Main() 


Dim package As Package = New Package() 


Dim tasks() As String = New String() {"STOCK:SQLTask", "STOCK:ScriptTask", _ 
"STOCK: ExecuteProcessTask", "STOCK:PipelineTask", _ 
"STOCK: FTPTask", "STOCK:SendMailTask", "STOCK:MSMQTask"} 


For Each s As String In tasks 


Dim taskhost As TaskHost = CType(package.Executables.Add(s), TaskHost) 

Dim props As DtsProperties = taskhost.Properties 

Console.WriteLine("Enumerating properties on " & taskhost.Name) 
Console.WriteLine(" TaskHost.InnerObject is " & taskhost.InnerObject.ToString()) 
Console.WriteLine() 


For Each prop As DtsProperty In props 


Console.WriteLine("Properties for " + prop.Name) 


Console.WriteLine(" Name : " + prop.Name) 
Console.WriteLine(" Type : " + prop.Type.ToString() ) 
Console.WriteLine(" Readable : " + prop.Get.ToString()) 
Console.WriteLine(" Writable : " + prop.Set.ToString()) 
Console.WriteLine() 
Next 
Next 


Console. Read() 
End Sub 


End Module 


External Resources 


Blog entry, EZAPI - Updated for SQL Server 2012, on blogs.msdn.com. 


See Also 
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A precedence constraint, represented in the object model by the PrecedenceConstraint class, establishes the 
order in which Executable objects run in a package. The precedence constraint allows the execution of the 
containers and tasks in a package to be dependent on the result of the execution of a previous task or container. 
Precedence constraints are established between pairs of Executable objects by calling the Add method of the 
PrecedenceConstraints collection on the container object. After you create a constraint between two executable 
objects, you set the Value property to establish the criteria for executing the second executable defined in the 
constraint. 


You can use both a constraint and an expression in a single precedence constraint, depending on the value that 
you specify for the EvalOp property, as described in the following table: 


VALUE OF THE EVALOP PROPERTY DESCRIPTION 


Constraint Specifies that the execution outcome determines whether 
the constrained container or task runs. Set the Value 
property of the PrecedenceConstraint to the desired value 
from the DTSExecResult enumeration. 


Expression Specifies that the value of an expression determines whether 
the constrained container or task runs. Set the Expression 
property of the PrecedenceConstraint. 


ExpressionAndConstraint Specifies that the constraint outcome must occur and the 
expression must evaluate for the constrained container or 
task to run. Set both the Value and the Expression 
properties of the PrecedenceConstraint, and set its 
LogicalAnd property to true. 


ExpressionOrConstraint Specifies that either the constraint outcome must occur, or 
the expression must evaluate, for the constrained container 
or task to run. Set both the Value and the Expression 
properties of the PrecedenceConstraint, and set its 
LogicalAnd property to false. 


The following code sample demonstrates adding two tasks to a package. A PrecedenceConstraint is created 
between them that prevents the second task from running until the first task finishes. 


using System; 
using Microsoft.SqlServer.Dts.Runtime; 


namespace Microsoft.SqlServer.Dts.Samples 
{ 
class Program 
{ 
static void Main(string[] args) 


{ 
Package p = new Package(); 


// Add a File System task. 
Executable eFileTask1 = p.Executables.Add("STOCK:FileSystemTask") ; 
TaskHost thFileHost1 = eFileTask1 as TaskHost; 


// Add a second File System task. 
Executable eFileTask2 = p.Executables.Add("STOCK:FileSystemTask") ; 
TaskHost thFileHost2 = eFileTask2 as TaskHost; 


// Put a precedence constraint between the tasks. 

// Set the constraint to specify that the second File System task cannot run 

// until the first File System task finishes. 

PrecedenceConstraint pcFileTasks = 
p.PrecedenceConstraints.Add((Executable)thFileHost1, (Executable)thFileHost2) ; 

pcFileTasks.Value = DTSExecResult.Completion; 


Imports Microsoft.SqlServer.Dts.Runtime 
Module Module1 
Sub Main() 


Dim p As Package = New Package() 

" Add a File System task. 

Dim eFileTask1 As Executable = p.Executables.Add("STOCK:FileSystemTask" ) 
Dim thFileHost1 As TaskHost = CType(eFileTask1, TaskHost) 

" Add a second File System task. 

Dim eFileTask2 As Executable = p.Executables.Add("STOCK:FileSystemTask" ) 
Dim thFileHost2 As TaskHost = CType(eFileTask2, TaskHost) 


Put a precedence constraint between the tasks. 
" Set the constraint to specify that the second File System task cannot run 

until the first File System task finishes. 

Dim pcFileTasks As PrecedenceConstraint = _ 

p.PrecedenceConstraints.Add(CType(thFileHost1, Executable), CType(thFileHost2, Executable) ) 


pcFileTasks.Value = DTSExecResult.Completion 


End Sub 


End Module 


See Also 


Adding the Data Flow Task Programmatically 
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Variables are a way to dynamically set values and control processes in packages, containers, tasks, and event 
handlers. Variables can also be used by precedence constraints to control the direction of the flow of data to 
different tasks. Variables have a variety of uses: 


e Update properties of a package at run time. 
e Populate parameter values for Transact-SQL statements at run time. 
e Control the flow of a Foreach loop. For more information, see Add Enumeration to a Control Flow. 


e Control a precedence constraint by its use in an expression. A precedence constraint can include variables 
in the constraint definition. For more information, see Add Expressions to Precedence Constraints. 


e Control the conditional repeat of a For Loop container. For more information, see Add Iteration to a 
Control Flow. 


e Build expressions that include variable values. 


e You can create custom variables for all container types: packages, Foreach Loop containers, For Loop 
containers, Sequence containers, TaskHosts, and event handlers. For more information, see Integration 
Services (SSIS) Variables and Use Variables in Packages. 


Scope 


Each container has its own Variables collection. When a new variable is created, it is within the scope of its 
parent container. Because the package container is at the top of the container hierarchy, variables with package 
scope function like global variables, and are visible to all containers within the package. The collection of 
variables for the container can also be accessed by the children of the container through the Variables collection, 
by using either the variable name or the variable's index in the collection. 


Because the visibility of a variable is scoped from the top down, variables declared at the package level are 
visible to all the containers in the package. Therefore, the Variables collection on a container includes all the 
variables that belong to its parent in addition to its own variables 


Conversely, the variables that are contained in a task are limited in scope and visibility, and are only visible to the 
task. 


If a package runs other packages, the variables defined in the scope of the calling package are available to the 
called package. The only exception occurs when a same-named variable exists in the called package. When this 
collision occurs, the variable value in the called package overrides the value from the calling package. Variables 
defined in the scope of the called package are never available back to the calling package. 


The following code example programmatically creates a variable, myCcustomvar , at the package scope, and then 
iterates through all the variables visible to the package, printing their name, data type, and value. 


using System; 
using Microsoft.SqlServer.Dts.Runtime; 


namespace Microsoft.SqlServer.Dts.Samples 
{ 
class Program 
{ 
static void Main(string[] args) 
{ 

Application app = new Application(); 

// Load a sample package that contains a variable that sets the file name. 

Package pkg = app.LoadPackage( 
@"C:\Program Files\Microsoft SQL Server\100\Samples\Integration Services" + 
@"\Package Samples\CaptureDataLineage Sample\CaptureDataLineage\CaptureDataLineage.dtsx", 
null); 

Variables pkgVars = pkg.Variables; 

Variable myVar = pkg.Variables.Add("myCustomVar", false, "User", "3"); 

foreach (Variable pkgVar in pkgVars) 

{ 
Console.WriteLine("Variable: {0}, {1}, {2}", pkgVar.Name, 

pkgVar.DataType, pkgVar.Value.ToString()); 
} 
Console.Read() ; 


Imports Microsoft.SqlServer.Dts.Runtime 
Module Module1 
Sub Main() 


Dim app As Application = New Application() 
" Load a sample package that contains a variable that sets the file name. 
Dim pkg As Package = app.LoadPackage( _ 
"C:\Program Files\Microsoft SQL Server\100\Samples\Integration Services” & _ 
"\Package Samples\CaptureDataLineage Sample\CaptureDataLineage\CaptureDataLineage.dtsx", _ 
Nothing) 
Dim pkgVars As Variables = pkg.Variables 
Dim myVar As Variable = pkg.Variables.Add("myCustomVar", False, "User", "3") 
Dim pkgVar As Variable 
For Each pkgVar In pkgVars 
Console.WriteLine("Variable: {0}, {1}, {2}", pkgVar.Name, _ 
pkgVar.DataType, pkgVar.Value.ToString() ) 
Next 
Console. Read() 


End Sub 


End Module 


Sample Output: 

Variable: CancelEvent, Int32, @ 

Variable: CreationDate, DateTime, 4/18/2003 11:57:00 AM 
Variable: CreatorComputerName, String, 

Variable: CreatorName, String, 


Variable: ExecutionInstanceGUID, String, {237AB5A4-7E59-4FC9-8D61-E8F20363DF25} 


Variable: FileName, String, Junk 

Variable: InteractiveMode, Boolean, False 

Variable: LocaleID, Int32, 1033 

Variable: MachineName, String, MYCOMPUTERNAME 

Variable: myCustomVar, String, 3 

Variable: OfflineMode, Boolean, False 

Variable: PackageID, String, {F@D2E396-A6A5-42AE-9467-04CE946A810C} 
Variable: PackageName, String, DTSPackage1 

Variable: StartTime, DateTime, 1/28/2005 7:55:39 AM 

Variable: UserName, String, <domain>\<userid> 

Variable: VersionBuild, Int32, 198 

Variable: VersionComments, String, 

Variable: VersionGUID, String, {90E105B4-B4AF -4263-9CBD-C2050C2D6148} 
Variable: VersionMajor, Int32, 1 

Variable: VersionMinor, Int32, @ 


Notice that all the variables scoped in the System namespace are available to the package. For more 
information, see System Variables. 


Namespaces 


Microsoft SQL Server Integration Services ( SSIS) provides two default namespaces where variables reside; 
User and System namespaces. By default, any custom variable created by the developer is added to the User 
namespace. System variables reside in the System namespace. You can create additional namespaces other 
than the User namespace to hold custom variables, and you can change the name of the User namespace, but 
you cannot add or modify variables in the System namespace, or assign system variables to a different 


namespace. 


The system variables that are available differ depending on the container type. For a list of the system variables 
available to packages, containers, tasks, and event handlers, see System Variables. 


Value 


The value of a custom variable can be a literal or an expression: 
e If you want the variable to contain a literal value, set the value of its Value property. 


e If you want the variable to contain an expression, so that you can use the results of the expression as its 
value, set the EvaluateAsExpression property of the variable to true, and provide an expression in the 
Expression property. At run time, the expression is evaluated, and the result of the expression is used as 
the value of the variable. For example, if the expression property of a variable is "1e@ * 2""1e0 * 2", the 


variable evaluates to a value of 200. 


For a variable, you cannot explicitly set the value of its DataType. The DataType value is inferred from the initial 
value assigned to the variable, and cannot be changed afterward. For more information about variable data 


types, see Integration Services Data Types. 


The following code example creates a new variable, sets EvaluateAsExpression to true, assigns the expression 
"1e@ * 2" to the expression property of the variable, and then outputs the value of the variable. 


using System; 
using Microsoft.SqlServer.Dts.Runtime; 


namespace Microsoft.SqlServer.Dts.Samples 
{ 
class Program 
{ 
static void Main(string[] args) 
{ 
Package pkg = new Package(); 
Variable v10@ = pkg.Variables.Add("myVar", false, "", 1); 
v100.EvaluateAsExpression = true; 
v10@.Expression = "100 * 2"; 
Console.WriteLine("Expression for myVar: {@}", 
v10@.Properties["Expression"].GetValue(v10@) ) ; 
Console.WriteLine("Value of myVar: {@}", v10@.Value.ToString()); 
Console.Read(); 


Imports Microsoft.SqlServer.Dts.Runtime 
Module Module1 
Sub Main() 


Dim pkg As Package = New Package 
Dim v1@@ As Variable = pkg.Variables.Add("myVar", False, "", 1) 
v100.EvaluateAsExpression = True 
v100.Expression = "100 * 2" 
Console.WriteLine("Expression for myVar: {@}", 
v10@.Properties("Expression") .GetValue(v1@@) ) 
Console.WriteLine("Value of myVar: {@}", v100.Value.ToString) 
Console. Read() 


End Sub 


End Module 


Sample Output: 
Expression for myVar: 100 * 2 
Value of myVar: 200 


The expression must be a valid expression that uses the SSIS expression syntax. Literals are permitted in variable 
expressions, in addition to the operators and functions that the expression syntax provides, but expressions 


cannot reference other variables or columns. For more information, see Integration Services (SSIS) Expressions. 


Configuration Files 


If a configuration file includes a custom variable, the variable can be updated at run time. What this means is 
that when the package runs, the value of the variable originally in the package is replaced with a new value from 
the configuration file. This replacement technique is useful when a package is deployed to multiple servers that 
require different variable values. For example, a variable can specify the number of times a Foreach Loop 
container repeats its workflow, or list the recipients that an event handler sends e-mail to when an error is 


raised, or change the number of errors that can occur before the package fails. These variables are dynamically 


provided in configuration files for each environment. Therefore, only variables that are read/write are allowed in 
configuration files. For more information, see Create Package Configurations. 


See Also 


Integration Services (SSIS) Variables 
Use Variables in Packages 
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The SSIS runtime provides a collection of events that occur before, during, and after the validation and execution 
of a package. These events can be captured in two ways. The first method is by implementing the IDTSEvents 
interface in a class, and supplying the class as a parameter to the Execute and Validate methods of the 
package. The second method is by creating DtsEventHandler objects, which can contain other SSIS objects, such 
as tasks and loops, that are executed when an event in IDTSEvents occurs. This section describes these two 
methods and provides code examples to demonstrate their use. 


Receiving IDTSEvents Callbacks 


Developers who build and execute packages programmatically can receive event notifications during the 
validation and execution process using the IDTSEvents interface. This is done by creating a class that implements 
the IDTSEvents interface and providing this class as a parameter to the Validate and Execute methods of a 
package. The methods of the class are then called by the run-time engine when the events occur. 


The DefaultEvents class is a class that already implements the IDTSEvents interface; therefore, another 
alternative to implementing IDTSEvents directly is to derive from DefaultEvents and override the specific events 
that you want to respond to. You then provide your class as a parameter to the Validate and Execute methods 
of the Package to receive event callbacks. 


The following code sample demonstrates a class that derives from DefaultEvents, and overrides the 
OnPreExecute method. The class is then provided as aparameter to the Validate and Execute methods of the 
package. 


using System; 
using Microsoft.SqlServer.Dts.Runtime; 


namespace Microsoft.SqlServer.Dts.Samples 
{ 
class Program 
{ 
static void Main(string[] args) 
{ 
Package p = new Package(); 
MyEventsClass eventsClass = new MyEventsClass(); 


p.Validate(null, null, eventsClass, null); 
p.Execute(null, null, eventsClass, null, null); 


Console.Read(); 


} 
class MyEventsClass : DefaultEvents 


{ 
public override void OnPreExecute(Executable exec, ref bool fireAgain) 
if 
// TODO: Add custom code to handle the event. 
Console.WriteLine("The PreExecute event of the 
exec.ToString() + " has been raised."); 


ae 


Imports Microsoft.SqlServer.Dts.Runtime 
Module Module1 
Sub Main() 


Dim p As Package = New Package() 
Dim eventsClass As MyEventsClass = New MyEventsClass() 


p.Validate(Nothing, Nothing, eventsClass, Nothing) 
p.Execute(Nothing, Nothing, eventsClass, Nothing, Nothing) 


Console. Read() 
End Sub 
End Module 


Class MyEventsClass 
Inherits DefaultEvents 


Public Overrides Sub OnPreExecute(ByVal exec As Executable, ByRef fireAgain As Boolean) 
" TODO: Add custom code to handle the event. 
Console.WriteLine("The PreExecute event of the " & _ 
exec. ToString() & " has been raised.") 


End Sub 


End Class 


Creating DtsEventHandler Objects 


The run-time engine provides a robust, highly flexible event handling and notification system through the 


DtsEventHandler object. These objects let you design whole workflows within the event handler, which execute 
only when the event that the event handler belongs to occurs. The DtsEventHandler object is a container that is 
executed when the corresponding event on its parent object fires. This architecture lets you create isolated 
workflows that are executed in response to events that occur on a container. Because DtsEventHandler objects 
are synchronous, execution does not resume until the event handlers that are attached to the event have 


returned. 


The following code demonstrates how to create a DtsEventHandler object. The code adds a FileSystemTask to 
the Executables collection of the package, and then creates a DtsEventHandler object for the OnError event of 
the task. A FileSystemTask is added to the event handler, which is executed when the OnError event occurs for 
the first FileSystemTask. This example assumes that you have a file that is named 
C\Windows\Temp\DemofFile.txt for testing. The first time that you run the sample, if copies the file successfully 
and the event handler is not called. The second time you run the sample, the first FileSystemTask fails to copy 
the file (because the value of OverwriteDestinationFile is false), the event handler is called, the second 
FileSystemTask deletes the source file, and the package reports failure because of the error that occurred. 


Example 


using System; 

using System.I0; 

using Microsoft.SqlServer.Dts.Runtime; 

using Microsoft.SqlServer.Dts.Tasks.FileSystemTask; 


namespace Microsoft.SqlServer.Dts.Samples 


{ 
class Program 
< 
static void Main(string[] args) 
{ 
string f = "DemoFile.txt"; 
Executable e; 
TaskHost th; 
FileSystemTask fst; 
Package p = new Package(); 
p.Variables.Add("sourceFile", true, String.Empty, 
@"C:\Windows\Temp\" + ); 
p.Variables.Add("destinationFile", true, String.Empty, 
Path.Combine(Directory.GetCurrentDirectory(), f)); 
// Create a first File System task and add it to the package. 
// This task tries to copy a file from one folder to another. 
e = p.Executables.Add("STOCK:FileSystemTask") ; 
th = e as TaskHost; 
th.Name = "FileSystemTask1"; 
fst = th.InnerObject as FileSystemTask; 
fst.Operation = DTSFileSystemOperation.CopyFile; 
fst.OverwriteDestinationFile = false; 
fst.Source = "“sourceFile"; 
fst.IsSourcePathVariable = true; 
fst.Destination = "destinationFile"; 
fst.IsDestinationPathVariable = true; 
// Add an event handler for the FileSystemTask's OnError event. 
DtsEventHandler ehOnError = (DtsEventHandler)th.EventHandlers.Add("OnError") ; 
// Create a second File System task and add it to the event handler. 
// This task deletes the source file if the event handler is called. 
e = ehOnError.Executables.Add("STOCK:FileSystemTask") ; 
th = e as TaskHost; 
th.Name = "FileSystemTask2"; 
fst = th.InnerObject as FileSystemTask; 
fst.Operation = DTSFileSystemOperation.DeleteFile; 
fst.Source = "“sourceFile"; 
fst.IsSourcePathVariable = true; 
DTSExecResult vr = p.Validate(null, null, null, null); 
Console.WriteLine("ValidationResult = " + vr.ToString()); 
if (vr == DTSExecResult.Success) 
{ 
DTSExecResult er = p.Execute(null, null, null, null, null); 
Console.WriteLine("ExecutionResult = " + er.ToString()); 
if (er == DTSExecResult.Failure) 
if (!File.Exists(@"C:\Windows\Temp\" + #)) 
Console.WriteLine("Source file has been deleted by the event handler."); 
} 
Console.Read(); 
t 
} 


Imports System.IO 
Imports Microsoft.SqlServer.Dts.Runtime 
Imports Microsoft.SqlServer.Dts.Tasks.FileSystemTask 


Module Module1 


Sub Main() 


Dim f As String = "DemoFile.txt" 
Dim e As Executable 

Dim th As TaskHost 

Dim fst As FileSystemTask 


Dim p As Package = New Package() 


p.Variables.Add("sourceFile", True, String.Empty, _ 
"C:\Windows\Temp\" & #) 

p.Variables.Add("destinationFile", True, String.Empty, _ 
Path.Combine(Directory.GetCurrentDirectory(), #)) 


Create a first File System task and add it to the package. 
" This task tries to copy a file from one folder to another. 
e = p.Executables.Add("STOCK:FileSystemTask" ) 

th = CType(e, TaskHost) 

th.Name = "FileSystemTask1" 


fst = CType(th.InnerObject, FileSystemTask) 


fst.Operation = DTSFileSystemOperation.CopyFile 
fst.OverwriteDestinationFile = False 

fst.Source = "sourceFile" 
fst.IsSourcePathVariable = True 

fst.Destination = "destinationFile" 
fst.IsDestinationPathVariable = True 

" Add an event handler for the FileSystemTask's OnError event. 

Dim ehOnError As DtsEventHandler = CType(th.EventHandlers.Add("OnError"), DtsEventHandler) 


Create a second File System task and add it to the event handler. 
" This task deletes the source file if the event handler is called. 
e = ehOnError.Executables.Add("STOCK:FileSystemTask") 

th = CType(e, TaskHost) 

th.Name = "FileSystemTask1" 


fst = CType(th.InnerObject, FileSystemTask) 


fst.Operation = DTSFileSystemOperation.DeleteFile 
fst.Source = "sourceFile" 
fst.IsSourcePathVariable = True 


Dim vr As DTSExecResult = p.Validate(Nothing, Nothing, Nothing, Nothing) 
Console.WriteLine("ValidationResult = " + vr.ToString()) 
If vr = DTSExecResult.Success Then 
Dim er As DTSExecResult = p.Execute(Nothing, Nothing, Nothing, Nothing, Nothing) 
Console.WriteLine("ExecutionResult = " + er.ToString()) 
If er = DTSExecResult.Failure Then 
If Not File.Exists("C:\Windows\Temp\" + £) Then 
Console.WriteLine("Source file has been deleted by the event handler.") 
End If 
End If 
End it 


Console. Read() 


End Sub 


End Module 


See Also 


Integration Services (SSIS) Event Handlers 
Add an Event Handler to a Package 


Enabling Logging Programmatically 


11/23/2021 * 3 minutes to read « Edit Online 





Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


The run-time engine provides a collection of LogProvider objects that enable event-specific information to be 
captured during package validation and execution. LogProvider objects are available to DtsContainer objects, 
including the TaskHost, Package, ForLoop, and ForEachLoop objects. Logging is enabled on individual containers, 
or on the whole package. 


There are several types of log providers that are available for a container to use. This provides the flexibility to 
create and store log information in many formats. Enlisting a container object in logging is a two-step process: 
first logging is enabled, and then a log provider is selected. The LoggingOptions and LoggingMode properties of 
the container are used to specify the logged events and to select the log provider. 


Enabling Logging 


The LoggingMode property, found in each container that can perform logging, determines whether the 
container's event information is recorded to the event log. This property is assigned a value from the 
DTSLoggingMode structure, and is inherited from the container's parent by default. If the container is a package, 
and therefore has no parent, the property uses the UseParentSetting, which defaults to Disabled. 


Selecting a Log Provider 


After the LoggingMode property is set to Enabled, a log provider is added to the SelectedLogProviders 
collection of the container to complete the process. The SelectedLogProviders collection is available on the 
LoggingOptions object, and contains the log providers selected for the container. The Add method is called to 
create a provider and add it to the collection. The method then returns the log provider that was added to the 
collection. Each provider has configuration settings that are unique to that provider, and these properties are set 
using the ConfigString property. 


The following table lists the available log providers, their description, and their ConfigString information. 
PROVIDER DESCRIPTION CONFIGSTRING PROPERTY 


SQL Server Profiler Generates SQL traces that may be No configuration is required. 
captured and viewed in SQL Server 
Profiler. The default file name extension 
for this provider is .trc. 


SQL Server Writes event log entries to the SQL Server provider requires that the 
sysssislog table in any SQL Server connection to the database be 
database. specified, and also the target database 

name. 

Text File Writes event log entries to ASCII text The name of a file connection manager. 


files in a comma-separated value (CSV) 
format. The default file name extension 
for this provider is .log. 


Windows Event Log Logs to standard Windows Event Log No configuration is required. 
on the local computer in the 
Application log. 


PROVIDER DESCRIPTION CONFIGSTRING PROPERTY 


XML File Writes event log entries to XML The name of a file connection manager. 
formatted file. The default file name 
extension for this provider is .xml 


Events are included in or excluded from the event log by setting the EventFilterKind and the EventFilter 
properties of the container. The EventFilterKind structure contains two values, ExclusionFilter and 
InclusionFilter, that indicate whether the events that are added to the EventFilter are included in the event 
log. The EventFilter property is then assigned a string array that contains the names of the events that are the 
subject of the filtering. 


The following code enables logging on a package, adds the log provider for Text files to the 
SelectedLogProviders collection, and specifies a list of events to include in the logging output. 


Sample 


using System; 
using Microsoft.SqlServer.Dts.Runtime; 


namespace Microsoft.SqlServer.Dts.Samples 
{ 
class Program 
{ 
static void Main(string[] args) 


{ 
Package p = new Package(); 


ConnectionManager loggingConnection = p.Connections.Add("FILE") ; 
loggingConnection.ConnectionString = @"C:\SSISPackageLog. txt"; 


LogProvider provider = p.LogProviders.Add("DTS.LogProviderTextFile.2"); 
provider.ConfigString = loggingConnection.Name; 
p.LoggingOptions.SelectedLogProviders.Add(provider) ; 
p.LoggingOptions.EventFilterKind = DTSEventFilterKind. Inclusion; 
p.LoggingOptions.EventFilter = new String[] { "OnPreExecute", 

"OnPostExecute", "OnError", "“OnWarning", "“OnInformation" }; 
p.LoggingMode = DTSLoggingMode. Enabled; 


// Add tasks and other objects to the package. 


Imports Microsoft.SqlServer.Dts.Runtime 
Module Module1 
Sub Main() 
Dim p As Package = New Package() 


Dim loggingConnection As ConnectionManager = p.Connections.Add("FILE") 
loggingConnection.ConnectionString = "C:\SSISPackageLog. txt" 


Dim provider As LogProvider = p.LogProviders.Add("DTS.LogProviderTextFile.2") 

provider.ConfigString = loggingConnection.Name 

p.LoggingOptions.SelectedLogProviders.Add(provider) 

p.LoggingOptions.EventFilterKind = DTSEventFilterKind.Inclusion 

p.LoggingOptions.EventFilter = New String() {"OnPreExecute", _ 
"OnPostExecute", "OnError", "OnWarning", "OnInformation"} 

p.LoggingMode = DTSLoggingMode. Enabled 


Add tasks and other objects to the package. 
End Sub 


End Module 


See Also 


Integration Services (SSIS) Logging 
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SQL Server Data Tools (SSDT) includes a task called the Data Flow task, which is represented by the 
Microsoft.SqlServer.Dts.Pipeline. Wrapper namespace in the object model. The Data Flow task is a specialized, 
high-performance task, dedicated to transforming and moving data during package execution. Like other tasks, 
the Data Flow task is wrapped by the TaskHost object, and from the perspective of the run-time engine, this task 
is just another task in the package. However, the data flow contains additional objects called data flow 
components. These components are the components that make data move from a source to a destination, 
sometimes through a transformation. The components define both the direction of movement and how data is 
transformed. Configuring the Data Flow task involves adding components to the task, and then connecting them 
to establish the flow of data and achieve the intended transformation. 


There are three types of components within a Data Flow task: Data Flow Sources, Data Flow 
Transformations, and Data Flow Destinations, shown in that order within the SSIS Designer toolbox. These 
types are also referred to more simply as sources, transformations, or destinations. As implied by the names, 
data flows from a source to a transformation, and then to a destination. This is a simplistic description of the 
data flow to illustrate the concept, but the Data Flow task is flexible and powerful enough to handle multiple 
sources, and to connect together many transformations that send output to multiple destinations. 


The Data Flow task is added to a package the same way other tasks are added. After the task has been added, it 
is configured by adding components to the data flow task, and configuring and connecting components in the 
task. 


Sample 


The following code sample shows how to add a Data Flow task to a package. This example requires a reference 
to the assemblies Microsoft.SqlServer.PipelineHost, Microsoft.SqlServer.DTSPipelineWrap, and 
Microsoft.SqlServer.ManagecDTS. 


using System; 

using Microsoft.SqlServer.Dts.Runtime; 

using Microsoft.SqlServer.Dts.Pipeline; 

using Microsoft.SqlServer.Dts.Pipeline.Wrapper; 


namespace Microsoft.SqlServer.Dts.Samples 
{ 
class Program 
{ 
static void Main(string[] args) 
{ 
Package p = new Package(); 
Executable e = p.Executables.Add("STOCK:PipelineTask") ; 
TaskHost thMainPipe = e as TaskHost; 
MainPipe dataFlowTask = thMainPipe.InnerObject as MainPipe; 


Imports System.IO 
Imports Microsoft.SqlServer.Dts.Runtime 
Imports Microsoft.SqlServer.Dts.Pipeline 
Imports Microsoft.SqlServer.Dts.Pipeline.Wrapper 
Module Module1 
Sub Main() 
Dim p As Package = New Package() 
Dim e As Executable = p.Executables.Add("STOCK:PipelineTask") 
Dim thMainPipe As TaskHost = CType(e, TaskHost) 
Dim dataFlowTask As MainPipe = CType(thMainPipe.InnerObject, MainPipe) 


End Sub 


End Module 
External Resources 
Blog entry, EZAPI - Updated for SQL Server 2012, on blogs.msdn.com. 


See Also 
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After you have added a data flow task to a package, your next step may be to determine what data flow 
components are available for your use. You can programmatically discover the data flow sources, 
transformations, and destinations that are installed and available on the local computer. For information about 
adding a data flow task to the package, see Adding the Data Flow Task Programmatically. 


Discovering Components 


The Application class provides the PipelineComponentinfos collection, which contains a PipelineComponentinfo 
object for each component correctly installed on the local computer. Each PipelineComponentinfo contains 
information about a component such as its name, description, and creation name. You can use the value 
returned in the CreationName property to set the ComponentClass|D property of the 
IDTSComponentMetaData100 when you add a component to a package. 


Next Step 


After discovering available components, the next step is to add and configure the components, which is 
discussed in the next topic, Adding Data Flow Components Programmatically. 


Sample 


The following code sample shows how to enumerate the PipelineComponentinfos collection of the Application 
object to programmatically discover the data flow components available on the local computer. This sample 
requires a reference to the Microsoft.SqlServer.ManagedDTS assembly. 


using System; 
using Microsoft.SqlServer.Dts.Runtime; 


namespace Microsoft.SqlServer.Dts.Samples 


ib 
class Program 
if 
static void Main(string[] args) 
{ 
Application application = new Application(); 
PipelineComponentInfos componentInfos = application.PipelineComponentInfos; 
foreach (PipelineComponentInfo componentInfo in componentInfos) 
il 
Console.WriteLine("Name: " + componentInfo.Name + "\n" + 
" CreationName: " + componentInfo.CreationName + "\n"); 
t 
Console.Read(); 
t 
} 


Imports Microsoft.SqlServer.Dts.Runtime 
Module Module1 
Sub Main() 
Dim application As Application = New Application() 
Dim componentInfos As PipelineComponentInfos = application.PipelineComponentInfos 


For Each componentInfo As PipelineComponentInfo In componentInfos 
Console.WriteLine("Name: " & componentInfo.Name & vbCrLf & _ 


CreationName: & componentInfo.CreationName & vbCrLf) 


Next 
Console. Read() 
End Sub 


End Module 


See Also 


Adding Data Flow Components Programmatically 
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When you build a data flow, you start by adding components. Then you configure those components and 
connect them together to establish the flow of data at run time. This section describes adding a component to 
the data flow task, creating the design-time instance of the component, and then configuring the component. 
For information about how to connect components, see Connecting Data Flow Components Programmatically. 


Adding a Component 


Call the New method of the ComponentMetaDataCollection collection to create a new component and add it to 
the data flow task. This method returns the IDTSComponentMetaData100 interface of the component. However, 
at this point, the IDTSComponentMetaData100 does not contain information specific to any one component. Set 
the ComponentClassID property to identify the type of component. The data flow task uses the value of this 
property to create an instance of the component at run time. 


The value specified in the ComponentClassID property can be the CLSID, PROGID, or CreationName property of 
the component. The CLSID is normally displayed in the Properties window as the value of the component's 
ComponentClass!D property. For information about obtaining this property and other properties of available 
components, see Discovering Data Flow Components Programmatically. 


Adding a Managed Component 


You cannot use the CLSID or PROGID to add one the managed data flow components to the data flow, because 
these values point to a wrapper and not to the component itself. Instead you can use the CreationName 
property or the AssemblyQualifiedName property as shown in the following sample. 


If you intend to use the AssemblyQualifiedName property, then you must add a reference in your Visual 
Studio project to the assembly that contains the managed component. These assemblies are not listed on the 
.NET tab of the Add Reference dialog box. Normally you must browse to locate the assembly in the 
C:\Program Files\Microsoft SQL Server\100\DTS\PipelineComponents folder. 


The built-in managed data flow components include: 
e ADO.NET Source 

e XML Source 

e DataReader Destination 

e SQL Server Compact Destination 


e Script Component 


The following code sample shows both ways of adding a managed component to the data flow: 


using System; 

using Microsoft.SqlServer.Dts.Runtime; 

using Microsoft.SqlServer.Dts.Pipeline; 

using Microsoft.SqlServer.Dts.Pipeline.Wrapper; 


namespace Microsoft.SqlServer.Dts.Samples 
{ 
class Program 
{ 
static void Main(string[] args) 
{ 
Microsoft.SqlServer.Dts.Runtime.Package package = new Microsoft.SqlServer.Dts.Runtime.Package() ; 
Executable e = package.Executables.Add("STOCK:PipelineTask") ; 
Microsoft.SqlServer.Dts.Runtime.TaskHost thMainPipe = (Microsoft.SqlServer.Dts.Runtime.TaskHost)e; 
MainPipe dataFlowTask = (MainPipe)thMainPipe.InnerObject; 


// The Application object will be used to obtain the CreationName 
// of a PipelineComponentInfo from its PipelineComponentInfos collection. 
Application app = new Application(); 


// Add a first ADO NET source to the data flow. 

// The CreationName property requires an Application instance. 

IDTSComponentMetaData10@ component1 = dataFlowTask.ComponentMetaDataCollection.New() ; 
component1.Name = "DataReader Source"; 

component1.ComponentClassID = app.PipelineComponentInfos["DataReader Source" ].CreationName; 


// Add a second ADO NET source to the data flow. 
// The AssemblyQualifiedName property requires a reference to the assembly. 
IDTSComponentMetaData10@ component2 = dataFlowTask.ComponentMetaDataCollection.New() ; 
component2.Name = "DataReader Source"; 
component2.ComponentClassID = 

typeof (Microsoft.SqlServer.Dts.Pipeline.DataReaderSourceAdapter ) .AssemblyQualifiedName; 


} 


Imports Microsoft.SqlServer.Dts.Runtime 
Imports Microsoft.SqlServer.Dts.Pipeline 
Imports Microsoft.SqlServer.Dts.Pipeline.Wrapper 


Module Module1 
Sub Main() 


Dim package As Microsoft.SqlServer.Dts.Runtime.Package = _ 
New Microsoft.SqlServer.Dts.Runtime.Package() 
Dim e As Executable = package.Executables.Add("STOCK:PipelineTask") 
Dim thMainPipe As Microsoft.SqlServer.Dts.Runtime.TaskHost = _ 
CType(e, Microsoft.SqlServer.Dts.Runtime.TaskHost) 
Dim dataFlowTask As MainPipe = CType(thMainPipe.InnerObject, MainPipe) 


The Application object will be used to obtain the CreationName 


of a PipelineComponentInfo from its PipelineComponentInfos collection. 
Dim app As New Application() 


" Add a first ADO NET source to the data flow. 


The CreationName property requires an Application instance. 

Dim component1 As IDTSComponentMetaData10e = _ 
dataFlowTask.ComponentMetaDataCollection.New() 

component1.Name = "DataReader Source" 

component1.ComponentClassID = app.PipelineComponentInfos("DataReader Source") .CreationName 


" Add a second ADO NET source to the data flow. 


The AssemblyQualifiedName property requires a reference to the assembly. 

Dim component2 As IDTSComponentMetaData100 = _ 
dataFlowTask.ComponentMetaDataCollection.New() 

component2.Name = "DataReader Source" 

component2.ComponentClassID = _ 

GetType(Microsoft.SqlServer.Dts.Pipeline.DataReaderSourceAdapter) .AssemblyQualifiedName 


End Sub 


End Module 


Creating the Design-time Instance of the Component 


Call the Instantiate method to create the design time instance of the component identified by the 
ComponentClassID property. This method returns the CManagedComponentWrapper object, which is the 
managed wrapper for the IDTSDesigntimeComponent100 interface. 


Whenever possible, you should modify a component by using the methods of the design-time instance instead 
of by modifying the component metadata directly. Although there are items in the metadata that you must set 
directly, such as connections, generally it is inadvisable to modify the metadata directly because you bypass the 
ability of the component to monitor and validate changes. 


Assigning Connections 


Some components, such as the OLE DB Source component, require a connection to external data and use an 
existing ConnectionManager object in the package for this purpose. The Count property of the 
RuntimeConnectionCollection collection indicates the number of run-time ConnectionManager objects required 
by the component. If the count is greater than zero, the component requires a connection. Assign a connection 
manager from the package to the component by specifying the ConnectionManager and Name properties of 
the first connection in the RuntimeConnectionCollection. Note that the name of the connection manager in the 


run-time connection collection must match the name of the connection managerreferenced from the package. 


Setting the Values of Custom Properties 


After creating the design-time instance of the component, call the ProvideComponentProperties method. This 
method is similar to a constructor because it initializes a newly created component by creating its custom 
properties and its input and output objects. Do not call ProvideComponentProperties more than one time on a 
component, because the component may reset itself and lose any modifications previously made to its 
metadata. 


The CustomPropertyCollection of the component contains a collection of IDTSCustomProperty100 objects 
specific to the component. Unlike other programming models, where the properties of an object are always 
visible on the object, components only populate their custom property collections when you call the 
ProvideComponentProperties method. After you call method, use the SetComponentProperty method of the 
design-time instance of the component to assign values to its custom properties. This method accepts a 
name/value pair that identifies the custom property and provides its new value. 


Initializing Output Columns 


After you add a component to the task and configure it, initialize the collection of columns in the IDTSOutput100 
of the object. This step is especially relevant for source components, but may not initialize the columns for 
transformation and destination components because they generally depend on the columns that they receive 
from upstream components. 


Call the ReinitializeMetaData method to initialize the columns in the outputs of a source component. Because 
components do not automatically connect to external data sources, call the AcquireConnections method before 
calling ReinitializeMetaData to provide the component access to its external data source and the ability to 
populate its column metadata. Finally, call the ReleaseConnections method to release the connection. 


Next Step 


After adding and configuring the component, the next step is to create paths between components, which is 
discussed in the topic, Creating a Path Between Two Components. 


Sample 


The following code sample adds the OLE DB Source component to a data flow task, creates a design-time 
instance of the component, and configures the component's properties. This example requires an additional 
reference to the assembly Microsoft.SqlServer.DTSRuntimeWrap. 


using System; 

using Microsoft.SqlServer.Dts.Runtime; 

using Microsoft.SqlServer.Dts.Runtime.Wrapper; 
using Microsoft.SqlServer.Dts.Pipeline; 

using Microsoft.SqlServer.Dts.Pipeline.Wrapper; 


namespace Microsoft.SqlServer.Dts.Samples 


{ 
class Program 
{ 
static void Main(string[] args) 
{ 
Runtime.Package package = new Runtime.Package(); 
Executable e = package.Executables.Add("STOCK:PipelineTask") ; 
Runtime.TaskHost thMainPipe = e as Runtime. TaskHost; 
MainPipe dataFlowTask = thMainPipe.InnerObject as MainPipe; 
// Add an OLEDB connection manager to the package. 
ConnectionManager cm = package.Connections.Add("OLEDB") ; 
cm.Name = "OLEDB ConnectionManager" ; 
cm.ConnectionString = "Data Source=(local);" + 
"Initial Catalog=AdventureWorks ;Provider=SQLOLEDB.1;" + 
"Integrated Security=SSPI;" 
// Add an OLE DB source to the data flow. 
IDTSComponentMetaData10@ component = 
dataFlowTask.ComponentMetaDataCollection.New() ; 
component.Name = "OLEDBSource"; 
component.ComponentClassID = "DTSAdapter.OleDbSource.1"; 
// You can also use the CLSID of the component instead of the PROGID. 
//component.ComponentClassID = "{2C@A8BE5-1EDC-4353-A@EF-B778599C65A0}" ; 
// Get the design time instance of the component. 
CManagedComponentWrapper instance = component.Instantiate(); 
// Initialize the component 
instance.ProvideComponentProperties() ; 
// Specify the connection manager. 
if (component.RuntimeConnectionCollection.Count > @) 
{ 
component. RuntimeConnectionCollection[@].ConnectionManager = 
DtsConvert.GetExtendedInterface(package.Connections[@]); 
component .RuntimeConnectionCollection[@].ConnectionManagerID = 
package.Connections[@].ID; } 
// Set the custom properties. 
instance.SetComponentProperty("AccessMode", 2); 
instance.SetComponentProperty("SqlCommand", 
"Select * from Production.Product") ; 
// Reinitialize the metadata. 
instance.AcquireConnections (null) ; 
instance.ReinitializeMetaData() ; 
instance.ReleaseConnections(); 
// Add other components to the data flow and connect them. 
} 
t 


Imports Microsoft.SqlServer.Dts.Runtime 

Imports Microsoft.SqlServer.Dts.Runtime.Wrapper 
Imports Microsoft.SqlServer.Dts.Pipeline 

Imports Microsoft.SqlServer.Dts.Pipeline.Wrapper 


Module Module1 
Sub Main() 


Dim package As Microsoft.SqlServer.Dts.Runtime.Package = _ 
New Microsoft.SqlServer.Dts.Runtime.Package() 
Dim e As Executable = package.Executables.Add("STOCK:PipelineTask") 
Dim thMainPipe As Microsoft.SqlServer.Dts.Runtime.TaskHost = _ 
CType(e, Microsoft.SqlServer.Dts.Runtime.TaskHost) 
Dim dataFlowTask As MainPipe = CType(thMainPipe.InnerObject, MainPipe) 
" Add an OLEDB connection manager to the package. 
Dim cm As ConnectionManager = package.Connections.Add("OLEDB" ) 
cm.Name = "OLEDB ConnectionManager"™ 
cm.ConnectionString = "Data Source=(local);" & _ 
"Initial Catalog=AdventureWorks ;Provider=SQLOLEDB.1;" & _ 
"Integrated Security=SSPI;" 


" Add an OLE DB source to the data flow. 
Dim component As IDTSComponentMetaData1@e = _ 
dataFlowTask.ComponentMetaDataCollection.New() 
component.Name = "“OLEDBSource"™ 
component.ComponentClassID = "DTSAdapter.OleDbSource.1" 
"You can also use the CLSID of the component instead of the PROGID. 
"“component.ComponentClassID = "{2C@A8BE5-1EDC-4353-A@EF -B778599C65A0}" ; 
" Get the design time instance of the component. 
Dim instance As CManagedComponentWrapper = component.Instantiate() 
" Initialize the component. 
instance.ProvideComponentProperties() 
" Specify the connection manager. 
If component.RuntimeConnectionCollection.Count > @ Then 
component .RuntimeConnectionCollection(@).ConnectionManager = _ 
DtsConvert.GetExtendedInterface(package.Connections(@) ) 
component .RuntimeConnectionCollection(@).ConnectionManagerID = _ 
package.Connections(@).ID 
End If 
" Set the custom properties. 
instance.SetComponentProperty("AccessMode", 2) 
instance.SetComponentProperty("SqlCommand", _ 
"Select * from Production.Product") 
" Reinitialize the metadata. 
instance.AcquireConnections(vbNull) 
instance.ReinitializeMetaData() 
instance.ReleaseConnections() 


Add other components to the data flow and connect them. 
End Sub 


End Module 


External Resources 


Blog entry, EZAPI - Updated for SQL Server 2012, on blogs.msdn.com. 


See Also 
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After you have added components to the data flow task, you connect them to create an execution tree that 
represents the flow of data from sources through transformations to destinations. You use IDTSPath100 objects 
to connect the components in the data flow. 


Creating a Path 


Call the New method of the PathCollection property of the MainPipe interface to create a new path and add it to 
the collection of paths in the data flow task. This method returns a new, disconnected IDTSPath100 object, which 
you then use to connect two components. 


Call the AttachPathAndPropagateNotifications method to connect the path and to notify the components 
participating in the path that they have been connected. This method accepts an IDTSOutput100 of the upstream 
component and an IDTSInput100 of the downstream component as parameters. By default, the call to the 
component's ProvideComponentProperties method creates a single input for components that have inputs, and 
a single output for components that have outputs. The following example uses this default output of the source 
and input of the destination. 


Next Step 


After you establish a path between two components, the next step is to map input columns in the downstream 
component, which is discussed in the next topic, Selecting Input Columns Programmatically. 


Sample 


The following code sample shows how to establish a path between two components. 


using System; 

using Microsoft.SqlServer.Dts.Runtime; 

using Microsoft.SqlServer.Dts.Pipeline; 

using Microsoft.SqlServer.Dts.Pipeline.Wrapper; 


namespace Microsoft.SqlServer.Dts.Samples 
{ 
class Program 
{ 
static void Main(string[] args) 
{ 
Package package = new Package(); 
Executable e = package.Executables.Add("STOCK:PipelineTask") ; 
TaskHost thMainPipe = e as TaskHost; 
MainPipe dataFlowTask = thMainPipe.InnerObject as MainPipe; 


// Create the source component. 

IDTSComponentMetaData10@ source = 
dataFlowTask.ComponentMetaDataCollection.New() ; 

source.ComponentClassID = "DTSAdapter.OleDbSource"; 

CManagedComponentWrapper srcDesignTime = source.Instantiate(); 

srcDesignTime.ProvideComponentProperties() ; 


// Create the destination component. 

IDTSComponentMetaData1@@ destination = 
dataFlowTask.ComponentMetaDataCollection.New() ; 

destination.ComponentClassID = "DTSAdapter.OleDbDestination”" ; 

CManagedComponentWrapper destDesignTime = destination.Instantiate(); 

destDesignTime.ProvideComponentProperties() ; 


// Create the path. 

IDTSPath10@ path = dataFlowTask.PathCollection.New(); 

path.AttachPathAndPropagateNotifications(source.OutputCollection[@], 
destination. InputCollection[@]); 


Imports Microsoft.SqlServer.Dts.Runtime 
Imports Microsoft.SqlServer.Dts.Pipeline 
Imports Microsoft.SqlServer.Dts.Pipeline.Wrapper 


Module Module1 
Sub Main() 


Dim package As Microsoft.SqlServer.Dts.Runtime.Package = _ 
New Microsoft.SqlServer.Dts.Runtime.Package() 

Dim e As Executable = package.Executables.Add("STOCK:PipelineTask") 

Dim thMainPipe As Microsoft.SqlServer.Dts.Runtime.TaskHost = _ 
CType(e, Microsoft.SqlServer.Dts.Runtime.TaskHost) 

Dim dataFlowTask As MainPipe = CType(thMainPipe.InnerObject, MainPipe) 

" Create the source component. 

Dim source As IDTSComponentMetaData100 = _ 
dataFlowTask.ComponentMetaDataCollection.New() 

source.ComponentClassID = "DTSAdapter.OleDbSource" 

Dim srcDesignTime As CManagedComponentWrapper = source.Instantiate() 

srcDesignTime. ProvideComponentProperties() 

" Create the destination component. 

Dim destination As IDTSComponentMetaData1ee = _ 
dataFlowTask.ComponentMetaDataCollection.New( ) 

destination.ComponentClassID = "DTSAdapter.OleDbDestination"” 

Dim destDesignTime As CManagedComponentWrapper = destination.Instantiate() 

destDesignTime.ProvideComponentProperties() 


" Create the path. 

Dim path As IDTSPath1@@ = dataFlowTask.PathCollection.New() 

path.AttachPathAndPropagateNotifications(source.OutputCollection(®), _ 
destination. InputCollection(@) ) 


End Sub 


End Module 


See Also 
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After you have programmatically connected components, select the columns from upstream components that 
you will transform or pass through to downstream components. If you do not select input columns for your 
component, the component does not receive any rows from the data flow task. 


Selecting Columns 


Call the GetVirtuallnput method to retrieve the list of available columns from an upstream component, then call 
the SetUsageType method of the design-time component instance to select columns from the virtual input 
column collection. When you call this method, the component creates a new input column in its input column 
collection that has the same lineage ID as the corresponding column in the output collection of the upstream 
component. 


Do not select columns by calling the SetUsageType method of the virtual input object directly, because this 
bypasses the component's ability to reject columns based on inappropriate data types or other properties. 


Sample 


The following code sample demonstrates how to use the design-time instance of a component to select the 
columns for a component. 


using System; 

using Microsoft.SqlServer.Dts.Runtime; 

using Microsoft.SqlServer.Dts.Pipeline; 

using Microsoft.SqlServer.Dts.Pipeline.Wrapper; 


namespace Microsoft.SqlServer.Dts.Samples 
{ 
class Program 
ul 
static void Main(string[] args) 
{ 
// Create a package and add a Data Flow task. 
Package package = new Package(); 
Executable e = package.Executables.Add("STOCK:PipelineTask") ; 
TaskHost thMainPipe = e as TaskHost; 
MainPipe dataFlowTask = thMainPipe.InnerObject as MainPipe; 


// Add an OLE DB connection manager to the package. 
ConnectionManager conMgr = package.Connections.Add("OLEDB") ; 
conMgr.ConnectionString = "Provider=SQLOLEDB.1;" + 
"Data Source=<servername>;Initial Catalog=AdventureWorks;" + 
"Integrated Security=SSPI;"; 
conMgr.Name = "SSIS Connection Manager for OLE DB"; 
conMgr.Description = "OLE DB connection to the AdventureWorks database."; 


// Create and configure an OLE DB source component. 

IDTSComponentMetaData10@ source = 
dataFlowTask.ComponentMetaDataCollection.New(); 

source.ComponentClassID = "DTSAdapter.OleDbSource”" ; 

// Create the design-time instance of the source. 

CManagedComponentWrapper srcDesignTime = source.Instantiate(); 

// The ProvideComponentProperties method creates a default output. 
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// Assign the connection manager. 
source.RuntimeConnectionCollection[@].ConnectionManager = 
DtsConvert.GetExtendedInterface(conMgr) ; 
// Set the custom properties of the source. 
srcDesignTime.SetComponentProperty("AccessMode", 2); 
srcDesignTime.SetComponentProperty("SqlCommand", 
"Select * from Production.Product") ; 


// Connect to the data source, 

// and then update the metadata for the source. 
srcDesignTime.AcquireConnections(nul1) ; 
srcDesignTime.ReinitializeMetaData() ; 
srcDesignTime.ReleaseConnections(); 


// Create and configure an OLE DB destination. 
IDTSComponentMetaData1@@ destination = 
dataFlowTask.ComponentMetaDataCollection.New(); 
destination.ComponentClassID = "DTSAdapter.OleDbDestination”"; 
// Create the design-time instance of the destination. 
CManagedComponentWrapper destDesignTime = destination.Instantiate(); 
// The ProvideComponentProperties method creates a default input. 
destDesignTime.ProvideComponentProperties(); 


// Create the path from source to destination. 

IDTSPath10@ path = dataFlowTask.PathCollection.New(); 

path.AttachPathAndPropagateNotifications(source.OutputCollection[@], 
destination. InputCollection[@]); 


// Get the destination's default input and virtual input. 
IDTSInput10@ input = destination. InputCollection[@]; 
IDTSVirtualInput10@ vInput = input.GetVirtualInput() ; 


// Iterate through the virtual input column collection. 
foreach (IDTSVirtualInputColumn1ee@ vColumn in vInput.VirtualInputColumnCollection) 
{ 
// Call the SetUsageType method of the destination 
// to add each available virtual input column as an input column. 
destDesignTime.SetUsageType( 
input.ID, vInput, vColumn.LineageID, DTSUsageType.UT_READONLY) ; 


// Verify that the columns have been added to the input. 

foreach (IDTSInputColumn1e@ inputColumn in destination. InputCollection[@].InputColumnCollection) 
Console.WriteLine(inputColumn.Name) ; 

Console.Read(); 


// Add other components to the data flow and connect them. 


Imports Microsoft.SqlServer.Dts.Runtime 
Imports Microsoft.SqlServer.Dts.Pipeline 
Imports Microsoft.SqlServer.Dts.Pipeline.Wrapper 


Module Module1 


Sub Main() 
" Create a package and add a Data Flow task. 

Dim package As Microsoft.SqlServer.Dts.Runtime.Package = _ 
New Microsoft.SqlServer.Dts.Runtime.Package() 

Dim e As Executable = package.Executables.Add("STOCK:PipelineTask") 

Dim thMainPipe As Microsoft.SqlServer.Dts.Runtime.TaskHost = _ 
CType(e, Microsoft.SqlServer.Dts.Runtime.TaskHost) 

Dim dataFlowTask As MainPipe = CType(thMainPipe.InnerObject, MainPipe) 


Add an OLE DB connection manager to the package. 
Dim conMgr As ConnectionManager = package.Connections.Add("OLEDB" ) 
conMgr.ConnectionString = "Provider=SQLOLEDB.1;" & _ 
"Data Source=<servername>;Initial Catalog=AdventureWorks;" & _ 
"Integrated Security=SSPI;" 
conMgr.Name = "SSIS Connection Manager for OLE DB" 
conMgr.Description = "OLE DB connection to the AdventureWorks database." 
" Create and configure an OLE DB source component. 
Dim source As IDTSComponentMetaData100 = _ 
dataFlowTask.ComponentMetaDataCollection.New 
source.ComponentClassID = "DTSAdapter.OleDbSource” 
" Create the design-time instance of the source. 
Dim srcDesignTime As CManagedComponentWrapper = source.Instantiate 
" The ProvideComponentProperties method creates a default output. 
srcDesignTime. ProvideComponentProperties() 
" Assign the connection manager. 
source.RuntimeConnectionCollection(@).ConnectionManager = _ 
DtsConvert.GetExtendedInterface(conMgr) 
" Set the custom properties of the source. 
srcDesignTime.SetComponentProperty("AccessMode", 2) 
srcDesignTime.SetComponentProperty("SqlCommand", _ 
"Select * from Production.Product") 


Connect to the data source, 

"and then update the metadata for the source. 

srcDesignTime.AcquireConnections (Nothing) 

srcDesignTime. ReinitializeMetaData() 

srcDesignTime.ReleaseConnections() 

" Create and configure an OLE DB destination. 

Dim destination As IDTSComponentMetaData10e = _ 
dataFlowTask.ComponentMetaDataCollection.New 

destination.ComponentClassID = "DTSAdapter.OleDbDestination"” 

" Create the design-time instance of the destination. 

Dim destDesignTime As CManagedComponentWrapper = destination. Instantiate 

" The ProvideComponentProperties method creates a default input. 

destDesignTime.ProvideComponentProperties() 

" Create the path from source to destination. 

Dim path As IDTSPath100 = dataFlowTask.PathCollection.New 

path.AttachPathAndPropagateNotifications(source.OutputCollection(®), _ 
destination. InputCollection(@) ) 

" Get the destination's default input and virtual input. 

Dim input As IDTSInput10@ = destination. InputCollection(@) 

Dim vInput As IDTSVirtualInput10® = input.GetVirtualInput 

" Iterate through the virtual input column collection. 

For Each vColumn As IDTSVirtualInputColumn1@@ In vInput.VirtualInputColumnCollection 
" Call the SetUsageType method of the destination 
"to add each available virtual input column as an input column. 
destDesignTime.SetUsageType(input.ID, vInput, vColumn.LineageID, DTSUsageType.UT_READONLY) 

Next 

" Verify that the columns have been added to the input. 

For Each inputColumn As IDTSInputColumn1@@ In destination. InputCollection(@).InputColumnCollection 
Console.WriteLine(inputColumn.Name) 

Next 

Console. Read() 


Add other components to the data flow and connect them. 


End Sub 


End Module 


See Also 
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After building a new package programmatically, or modifying an existing one, you usually want to save your 
changes. 


All of the methods used in this topic to save packages require a reference to the 
Microsoft.SqlServer.ManagedDTS assembly. After you add the reference in a new project, import the 
Microsoft.SqlServer.Dts.Runtime namespace with a using or Imports statement. 


Saving a Package Programmatically 


To save a package programmatically, call one of the following methods of the Integration Services Application 


class: 
STORAGE LOCATION METHOD TO CALL 
File SaveToXml 
SSIS Package Store SaveToDtsServer 
SQL Server SaveToSq|Server 


or 


SaveToSq|ServerAs 


IMPORTANT 


The methods of the Application class for working with the SSIS Package Store only support "." or the server name for the 


local server. You cannot use "(local)" or "localhost". 





See Also 
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If you need manage and run Integration Services packages outside the development environment, you can 
manipulate packages programmatically. In this approach, you have a range of options: 


e Load and run an existing package without modification. 
e Load an existing package, reconfigure it (for example, for a different data source), and run it. 


e Create a new package, add and configure components object by object and property by property, save it, 
and run it. 


You can load and run an existing package from a client application by writing only a few lines of code. 


This section describes and demonstrates how to run an existing package programmatically and how to access 
the output of the data flow from other applications. As an advanced programming option, you can 
programmatically create an Integration Services package line by line as described in the topic, Building Packages 
Programmatically. 


This section also discusses other administrative tasks that you can perform programmatically to manage stored 
packages, running packages, and package roles. 


Running Packages on the Integration Services Server 


When you deploy packages to the Integration Services server, you can run the packages programmatically by 
using the Microsoft.SqlServerManagement.IntegrationServices namespace. The 
Microsoft.SqlServer.Management.IntegrationServices assembly is compiled with NET Framework 3.5. If you are 
building a .NET Framework 4.0 application, you might need to add the assembly reference directly to your 
project file. 


You can also use the namespace to deploy and manage Integration Services projects on the Integration Services 
server. For an overview of the namespace and code snippets, see the blog entry, A Glimpse of the SSIS Catalog 
Managed Object Model, on blogs.msdn.com. 


In This Section 


Understanding the Differences between Local and Remote Execution 


Discusses critical differences between executing a package locally or on the server. 


Loading and Running a Local Package Programmatically 


Describes how to execute an existing package from a client application on the local computer. 


Loading and Running a Remote Package Programmatically 
Describes how to execute an existing package from a client application and to ensure that the package runs on 
the server. 


Loading the Output of a Local Package 
Describes how to execute a package on the local computer and how to load the data flow output into a client 
application by using the DataReader destination and the DtsClient namespace. 


Enumerating Available Packages Programmatically 


Describes how to discover available packages that are managed by the Integration Services service. 


Managing Packages and Folders Programmatically 
Describes how to create, rename, and delete both packages and folders. 


Managing Running Packages Programmatically 
Describes how to list packages that are currently running, examine their properties, and stop a running package. 


Managing Package Roles Programmatically (SSIS Service) 
Describes how to get or set information about the roles assigned to a package or a folder. 


Reference 


Integration Services Error and Message Reference 
Lists the predefined Integration Services error codes with their symbolic names and descriptions. 


Related Sections 


Extending Packages with Scripting 
Discusses how to extend the control flow by using the Script task, and how to extend the data flow by using the 
Script component. 


Extending Packages with Custom Objects 
Discusses how to create program custom tasks, data flow components, and other package objects for use in 
multiple packages. 


Building Packages Programmatically 


Discusses how to create, configure, and save Integration Services packages programmatically. 


See Also 


SQL Server Integration Services 


Understanding the Differences between Local and 


Remote Execution 
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Package developers and administrators should be aware that there are restrictions related to where an 
Integration Services package runs. 


e A package runs on the same computer as the program that launches it. Even when a program 
loads a package that is stored remotely on another server, the package runs on the local computer. 


e You can only run a package outside the development environment on a computer that has 
Integration Services installed. You cannot run packages outside of SQL Server Data Tools (SSDT) ona 
client computer that does not have Integration Services installed, and the terms of your SQL Server 
licensing may not permit you to install Integration Services on additional computers. SQL Server 
Integration Services is a server component and is not redistributable to client computers. To run packages 
from a client computer, you need to launch them in a manner that ensures that the packages run on the 
server. 


For more information about loading and running a saved package, see: 

e@ Loading and Running a Local Package Programmatically 

e® Loading and Running a Remote Package Programmatically 

For more information about running a package and loading its output into a custom program, see: 


e@ Loading the Output of a Local Package 


See Also 


Loading and Running a Local Package Programmatically 
Loading and Running a Remote Package Programmatically 
Loading the Output of a Local Package 


Loading and Running a Local Package 


Programmatically 
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You can run Integration Services packages as needed or at predetermined times by using the methods described 
in Running Packages. However, with only a few lines of code, you can also run a package from a custom 
application such as a Windows Forms application, a console application, an ASPNET Web form or Web service, 
or a Windows service. 


This topic discusses: 
e Loading a package programmatically 
e Running a package programmatically 


All of the methods used in this topic to load and run packages require a reference to the 
Microsoft.SqlServer.ManagedDTS assembly. After adding the reference in a new project, import the 
Microsoft.SqlServer.Dts.Runtime namespace with a using or Imports statement. 


Loading a Package Programmatically 


To load a package programmatically on the local computer, whether the package is stored locally or remotely, 
call one of the following methods: 


STORAGE LOCATION METHOD TO CALL 
File LoadPackage 

SSIS Package Store LoadFromDtsServer 
SQL Server LoadFromSq|lServer 


IMPORTANT 


The methods of the Application class for working with the SSIS Package Store only support ".", localhost, or the server 


name for the local server. You cannot use "(local)". 





Running a Package Programmatically 


Developing a custom application in managed code that runs a package on the local computer requires the 
following approach. The steps summarized here are demonstrated in the sample console application that 
follows. 


To run a package on the local computer programmatically 

1. Start the Visual Studio development environment, and create a new application in your preferred 
development language. This example uses a console application; however you can also run a package 
from a Windows Forms application, an ASPNET Web form or Web service, or a Windows service. 


2. On the Project menu, click Add Reference and add a reference to 


Microsoft.SqlServer.ManagedDTS.dll. Click OK. 


3. Use the Visual Basic Imports statement or the C# using statement to import the 
Microsoft.SqlServer.Dts.Runtime namespace. 


4. Add the following code in the main routine. The completed console application should look like the 


following example. 





NOTE 
The sample code demonstrates loading the package from the file system by using the LoadPackage method. 
However you can also load the package from the MSDB database by calling the LoadFromSq|lServer method, or 


from the Integration Services package store by calling the LoadFromDtsServer method. 








5. Run the project. The sample code executes the CalculatedColumns sample package that is installed with 
the SQL Server samples. The result of package execution is displayed in the console window. 


Sample Code 


Imports Microsoft.SqlServer.Dts.Runtime 
Module Module1 
Sub Main() 


Dim pkgLocation As String 

Dim pkg As New Package 

Dim app As New Application 

Dim pkgResults As DTSExecResult 


pkgLocation = _ 
"C:\Program Files\Microsoft SQL Server\100\Samples\Integration Services” & _ 
"\Package Samples\CalculatedColumns Sample\CalculatedColumns\CalculatedColumns.dtsx" 
pkg = app.LoadPackage(pkgLocation, Nothing) 
pkgResults = pkg.Execute() 


Console.WriteLine(pkgResults.ToString()) 
Console. ReadKey() 


End Sub 


End Module 


using System; 
using Microsoft.SqlServer.Dts.Runtime; 


namespace RunFromClientAppCs 


{ 


class Program 


{ 


static void Main(string[] args) 
{ 
string pkgLocation; 
Package pkg; 
Application app; 
DTSExecResult pkgResults; 


pkgLocation = 
@"C:\Program Files\Microsoft SQL Server\100\Samples\Integration Services" + 
@"\Package Samples\CalculatedColumns Sample\CalculatedColumns\CalculatedColumns.dtsx"; 
app = new Application(); 
pkg = app.LoadPackage(pkgLocation, null); 
pkgResults = pkg.Execute(); 


Console.WriteLine(pkgResults.ToString()); 
Console. ReadKey(); 


Capturing Events from a Running Package 


When you run a package programmatically as shown in the preceding sample, you may also want to capture 
errors and other events that occur as the package executes. You can accomplish this by adding a class that 
inherits from the DefaultEvents class, and by passing a reference to that class when you load the package. 
Although the following example captures only the OnError event, there are many other events that the 
DefaultEvents class lets you capture. 


To run a package on the local computer programmatically and capture package events 


1. Follow the steps in the preceding example to create a project for this example. 


2. Add the following code in the main routine. The completed console application should look like the 


following example. 


3. Run the project. The sample code executes the CalculatedColumns sample package that is installed with 
the SQL Server samples. The result of package execution is displayed in the console window, along with 


any errors that occur. 


Sample Code 


Imports Microsoft.SqlServer.Dts.Runtime 
Module Module1 
Sub Main() 
Dim pkgLocation As String 
Dim pkg As New Package 
Dim app As New Application 
Dim pkgResults As DTSExecResult 
Dim eventListener As New EventListener() 
pkgLocation = _ 
"C:\Program Files\Microsoft SQL Server\100\Samples\Integration Services” & _ 
"\Package Samples\CalculatedColumns Sample\CalculatedColumns\CalculatedColumns.dtsx" 
pkg = app.LoadPackage(pkgLocation, eventListener) 


pkgResults = pkg.Execute(Nothing, Nothing, eventListener, Nothing, Nothing) 


Console.WriteLine(pkgResults.ToString()) 
Console. ReadKey() 


End Sub 


End Module 


Class EventListener 
Inherits DefaultEvents 


Public Overrides Function OnError(ByVal source As Microsoft.SqlServer.Dts.Runtime.DtsObject, _ 


ByVal errorCode As Integer, ByVal subComponent As String, ByVal description As String, _ 
ByVal helpFile As String, ByVal helpContext As Integer, _ 

ByVal idofInterfaceWithError As String) As Boolean 

" Add application-specific diagnostics here. 

Console.WriteLine("Error in {@}/{1} : {2}", source, subComponent, description) 
Return False 


End Function 


End Class 


using System; 
using Microsoft.SqlServer.Dts.Runtime; 


namespace RunFromClientAppWithEventsCs 
{ 
class MyEventListener : DefaultEvents 
{ 
public override bool OnError(DtsObject source, int errorCode, string subComponent, 
string description, string helpFile, int helpContext, string idofInterfaceWithError) 


// Add application-specific diagnostics here. 
Console.WriteLine("Error in {@}/{1} : {2}", source, subComponent, description) ; 
return false; 


} 


class Program 
{ 
static void Main(string[] args) 
{ 
string pkgLocation; 
Package pkg; 
Application app; 
DTSExecResult pkgResults; 


MyEventListener eventListener = new MyEventListener(); 


pkgLocation = 
@"C:\Program Files\Microsoft SQL Server\100\Samples\Integration Services" + 
@"\Package Samples\CalculatedColumns Sample\CalculatedColumns\CalculatedColumns.dtsx" ; 
app 
pkg = app.LoadPackage(pkgLocation, eventListener) ; 
pkgResults = pkg.Execute(null, null, eventListener, null, null); 


new Application(); 


Console.WriteLine(pkgResults.ToString()); 
Console. ReadKey() ; 


See Also 


Understanding the Differences between Local and Remote Execution 
Loading and Running a Remote Package Programmatically 
Loading the Output of a Local Package 


Loading and Running a Remote Package 


Programmatically 
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To run remote packages from a local computer that does not have Integration Services installed, start the 
packages so that they run on the remote computer on which Integration Services is installed. You do this by 
having the local computer use SQL Server Agent, a Web service, or a remote component to start the packages 
on the remote computer. If you try to start the remote packages directly from the local computer, the packages 
will load onto and try to run from the local computer. If the local computer does not have Integration Services 
installed, the packages will not run. 





NOTE 

You cannot run packages outside SQL Server Data Tools on a client computer that does not have Integration Services 
installed, and the terms of your SQL Server licensing might not let you install Integration Services on additional 
computers. Integration Services is a server component and is not redistributable to client computers. 





Alternately, you can run a remote package from a local computer that has Integration Services installed. For 
more information, see Loading and Running a Local Package Programmatically. 


Running a Remote Package on the Remote Computer 
As mentioned above, there are multiple ways in which you can run a remote package on a remote server: 
e Use SQL Server Agent to run the remote package programmatically 


e Use a Web service or remote component to run the remote package programmatically 


Almost all the methods that are used in this topic to load and save packages require a reference to the 
Microsoft.SqlServer.ManagedDTS assembly. The exception is the ADO.NET approach demonstrated in this 
topic for executing the sp_start_job stored procedure, which requires only a reference to System.Data. After 
you add the reference to the Microsoft.SqlServer.ManagedDTS assembly in a new project, import the 
Microsoft.SqlServer.Dts.Runtime namespace with a using or Imports statement. 


Using SQL Server Agent to Run a Remote Package Programmatically on the Server 

The following code sample demonstrates how to programmatically use SQL Server Agent to run a remote 
package on the server. The code sample calls the system stored procedure, sp_start_job, which launches a SQL 
Server Agent job. The job that the procedure launches is named _ RunsstsPackage , and this job is on the remote 


computer. The RunssisPackage job then runs the package on the remote computer. 








NOTE 


The return value of the sp_start_job stored procedure indicates whether the stored procedure was able to start the SQL 
Server Agent job successfully. The return value does not indicate whether the package succeeded or failed. 











For information on troubleshooting packages that are run from SQL Server Agent jobs, see the Microsoft article, 
An SSIS package does not run when you call the SSIS package from a SQL Server Agent job step. 


Sample Code 


Imports System.Data 
Imports System.Data.SqlClient 


Module Module1 
Sub Main() 


Dim jobConnection As SqlConnection 
Dim jobCommand As SqlCommand 

Dim jobReturnValue As SqliParameter 
Dim jobParameter As SqlParameter 
Dim jobResult As Integer 


jobConnection = New SqlConnection("Data Source=(local);Initial Catalog=msdb;Integrated Security=SSPI") 
jobCommand = New SqlCommand("sp_start_job", jobConnection) 
jobCommand.CommandType = CommandType. StoredProcedure 


jobReturnValue = New SqlParameter("@RETURN_VALUE", SqlDbType. Int) 
jobReturnValue.Direction = ParameterDirection.ReturnValue 
jobCommand. Parameters .Add(jobReturnValue) 


jobParameter = New SqlParameter("@job_name", SqlDbType.VarChar) 
jobParameter.Direction = ParameterDirection. Input 
jobCommand. Parameters .Add(jobParameter ) 

jobParameter.Value = "RunSSISPackage" 


jobConnection.Open() 

jobCommand.ExecuteNonQuery ( ) 

jobResult = DirectCast(jobCommand. Parameters ("@RETURN_VALUE").Value, Integer) 
jobConnection.Close() 


Select Case jobResult 


Case @ 
Console.WriteLine("SQL Server Agent job, RunSISSPackage, started successfully.") 
Case Else 
Console.WriteLine("SQL Server Agent job, RunSISSPackage, failed to start.") 
End Select 


Console. Read() 


End Sub 


End Module 


using System; 
using System.Data; 
using System.Data.SqlClient; 


namespace LaunchSSISPackageAgent_CS 
{ 
class Program 
{ 
static void Main(string[] args) 


{ 


SqlConnection jobConnection; 
SqlCommand jobCommand; 
SqlParameter jobReturnValue; 
SqlParameter jobParameter; 
int jobResult; 


jobConnection = new SqlConnection("Data Source=(local);Initial Catalog=msdb; Integrated 
Security=SSPI") ; 

jobCommand = new SqlCommand("sp_start_job", jobConnection) ; 

jobCommand.CommandType = CommandType. StoredProcedure; 


jobReturnValue = new SqlParameter("@RETURN_VALUE", SqlDbType. Int); 
jobReturnValue.Direction = ParameterDirection.ReturnValue; 
jobCommand. Parameters .Add(jobReturnValue) ; 


jobParameter = new SqlParameter("@job_name", SqlDbType.VarChar) ; 
jobParameter.Direction = ParameterDirection. Input; 
jobCommand. Parameters .Add(jobParameter) ; 

jobParameter.Value = "RunSSISPackage" ; 


jobConnection.Open() ; 

jobCommand.ExecuteNonQuery() ; 

jobResult = (Int32)jobCommand.Parameters["@RETURN_VALUE"].Value; 
jobConnection.Close(); 


switch (jobResult) 
af 


case @: 
Console.WriteLine("SQL Server Agent job, RunSISSPackage, started successfully."); 
break; 

default: 
Console.WriteLine("SQL Server Agent job, RunSISSPackage, failed to start."); 
break; 


} 
Console.Read(); 


Using a Web Service or Remote Component to Run a Remote Package Programmatically 


The previous solution for running packages programmatically on the server does not require any custom code 
on the server. However, you may prefer a solution that does not rely on SQL Server Agent to execute packages. 
The following example demonstrates a Web service that can be created on the server to start Integration 
Services packages locally, and a test application that can be used to call the Web service from a client computer. 
If you prefer to create a remote component instead of a Web service, you can use the same code logic with very 
few changes in a remote component. However a remote component may require more extensive configuration 


than a Web service. 





IMPORTANT 


With its default settings for authentication and authorization, a Web service generally does not have sufficient 
permissions to access SQL Server or the file system to load and execute packages. You may have to assign appropriate 
permissions to the Web service by configuring its authentication and authorization settings in the web.config file and 
assigning database and file system permissions as appropriate. A complete discussion of Web, database, and file system 
permissions is beyond the scope of this topic. 


IMPORTANT 


The methods of the Application class for working with the SSIS Package Store support only ".", localhost, or the server 


name for the local server. You cannot use "(local)". 





Sample Code 


The following code samples show how to create and test the Web service. 


Creating the Web Service 
An Integration Services package can be loaded directly from a file, directly from SQL Server, or from the SSIS 
Package Store, which manages package storage in both SQL Server and special file system folders. This sample 
supports all the available options by using a Select Case or switch construct to select the appropriate syntax 
for starting the package and to concatenate the input arguments appropriately. The LaunchPackage Web service 
method returns the result of package execution as an integer instead of a DISExecResult value so that client 
computers do not require a reference to any Integration Services assemblies. 
1. Open Visual Studio and create a Web service project in your preferred programming language. The 

sample code uses the name LaunchSSI|SPackageService for the project. 


2. Add a reference to Microsoft.SqlServer.ManagedDTS and add an Imports or using statement to the 
code file for the Microsoft.SqlServer.Dts.Runtime namespace. 


3. Paste the sample code for the LaunchPackage Web service method into the class. (The sample shows the 
whole contents of the code window.) 


4. Build and test the Web service by providing a set of valid values for the input arguments of the 
LaunchPackage method that point to an existing package. For example, if package1.dtsx is stored on the 
server in C:\My Packages, pass "file" as the value of the sourceType, "C:\My Packages" as the value of 
sourceLocation, and "package1" (without the extension) as the value of packageName. 


Imports System.Web 

Imports System.Web.Services 

Imports System.Web.Services.Protocols 
Imports Microsoft.SqlServer.Dts.Runtime 
Imports System.I0O 


<WebService(Namespace:="https://dtsue/")> _ 
<WebServiceBinding(ConformsTo:=WsiProfiles.BasicProfile1_1)> _ 
<Global.Microsoft.VisualBasic.CompilerServices.DesignerGenerated()> _ 
Public Class LaunchSSISPackageService 

Inherits System.Web.Services.WebService 


" LaunchPackage Method Parameters: 

"1. sourceType: file, sql, dts 

"2. sourceLocation: file system folder, (none), logical folder 
" 3. packageName: for file system, ".dtsx" extension is appended 


<WebMethod()> _ 
Public Function LaunchPackage( _ 
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DyVdl Sourcelype AS SLing, _ 
ByVal sourceLocation As String, _ 
ByVal packageName As String) As Integer 'DTSExecResult 


Dim packagePath As String 
Dim myPackage As Package 
Dim integrationServices As New Application 


" Combine path and file name. 
packagePath = Path.Combine(sourceLocation, packageName) 


Select Case sourceType 
Case “filles 


Package is stored as a file. 
" Add extension if not present. 
If String. IsNulloOrEmpty(Path.GetExtension(packagePath)) Then 
packagePath = String.Concat(packagePath, ".dtsx") 
End If 
If File.Exists(packagePath) Then 
myPackage = integrationServices.LoadPackage(packagePath, Nothing) 
Else 
Throw New ApplicationException( _ 
"Invalid file location: " & packagePath) 
End If 
Case "sql" 


Package is stored in MSDB. 


Combine logical path and package name. 


If integrationServices.ExistsOnSqlServer(packagePath, ".", String.Empty, String.Empty) Then 
myPackage = integrationServices.LoadFromSqlServer( _ 
packageName, "(local)", String.Empty, String.Empty, Nothing) 
Else 


Throw New ApplicationException( _ 


"Invalid package name or location: " & packagePath) 
End If 
Case "dts" 


Package is managed by SSIS Package Store. 


Default logical paths are File System and MSDB. 


If integrationServices.ExistsOnDtsServer(packagePath, ".") Then 
myPackage = integrationServices.LoadFromDtsServer(packagePath, "localhost", Nothing) 
Else 
Throw New ApplicationException( _ 
"Invalid package name or location: " & packagePath) 
End If 
Case Else 


Throw New ApplicationException( _ 
"Invalid sourceType argument: valid values are 'file', ‘sql’, and ‘dts'.") 
End Select 


Return myPackage.Execute() 
End Function 


End Class 


using System; 

using System.Web; 

using System.Web.Services; 

using System.Web.Services.Protocols; 
using Microsoft.SqlServer.Dts.Runtime; 
using System.I0; 


[WebService(Namespace = "https://dtsue/")] 
[WebServiceBinding(ConformsTo = WsiProfiles.BasicProfile1_1) ] 
public class LaunchSSISPackageServiceCS : System.Web.Services.WebService 
if 
public LaunchSSISPackageServiceCS() 


{ 


// LaunchPackage Method Parameters: 

// 1. sourceType: file, sql, dts 

// 2. sourceLocation: file system folder, (none), logical folder 
// 3. packageName: for file system, ".dtsx" extension is appended 


[WebMethod ] 
public int LaunchPackage(string sourceType, string sourceLocation, string packageName) 


it 


string packagePath; 
Package myPackage; 
Application integrationServices = new Application(); 


// Combine path and file name. 
packagePath = Path.Combine(sourceLocation, packageName) ; 


switch(sourceType) 
{ 
case "file": 
// Package is stored as a file. 
// Add extension if not present. 
if (String. IsNullOrEmpty(Path.GetExtension(packagePath) ) ) 
if 
packagePath = String.Concat(packagePath, ".dtsx"); 

} 
if (File.Exists(packagePath) ) 
{ 


myPackage = integrationServices.LoadPackage(packagePath, null); 


} 


else 


if 
throw new ApplicationException("Invalid file location: "+packagePath) ; 
} 
break; 
case "sql": 
// Package is stored in MSDB. 
// Combine logical path and package name. 


if (integrationServices.ExistsOnSqlServer(packagePath, 


{ 


myPackage = integrationServices.LoadFromSqlServer(packageName, "(local)", String.Empty, 


,» String.Empty, String.Empty) ) 


String.Empty, null); 
} 


else 


{ 


throw new ApplicationException("Invalid package name or location: "+packagePath) ; 
} 
break; 
case "dts": 
// Package is managed by SSIS Package Store. 
// Default logical paths are File System and MSDB. 
if (integrationServices.ExistsOnDtsServer(packagePath, ".")) 


{ 


myPackage = integrationServices.LoadFromDtsServer(packagePath, "localhost", null); 
} 
else 
{ 
throw new ApplicationException("Invalid package name or location: "+packagePath) ; 
} 
break; 
default: 
throw new ApplicationException("Invalid sourceType argument: valid values are ‘file’, ‘sql’, and 
'dts'."); 
} 


return (Int32)myPackage.Execute(); 


Testing the Web Service 
The following sample console application uses the Web service to run a package. The LaunchPackage method of 
the Web service returns the result of package execution as an integer instead of a DISExecResult value so that 
client computers do not require a reference to any Integration Services assemblies. The sample creates a private 
enumeration whose values mirror the DISExecResult values to report the results of execution. 
1. In Visual Studio, add a new console application, using your preferred programming language, to the 
same solution that contains the Web service project. The sample code uses the name 
LaunchSSISPackageTest for the project. 


2. Set the new console application as the startup project in the solution. 


3. Add a Web reference for the Web service project. If necessary, adjust the variable declaration in the 
sample code for the name that you assign to the Web service proxy object. 


4. Paste the sample code for the Main routine and the private enumeration into the code. (The sample 
shows the whole contents of the code window.) 


5. Edit the line of code that calls the LaunchPackage method to provide a set of valid values for the input 
arguments that point to an existing package. For example, if package1.dtsx is stored on the server in 
C:\My Packages, pass "file" as the value of sourceType , "C:’\\My Packages" as the value of sourceLocation , 


and "package1" (without the extension) as the value of packageName . 


Module LaunchSSISPackageTest 
Sub Main() 


Dim launchPackageService As New LaunchSSISPackageService.LaunchSSISPackageService 
Dim packageResult As Integer 


Try 
packageResult = launchPackageService.LaunchPackage("sql", String.Empty, "SimpleTestPackage" ) 
Catch ex As Exception 


The type of exception returned by a Web service is: 
" System.Web.Services.Protocols.SoapException 
Console.WriteLine("The following exception occurred: " & ex.Message) 


End Try 


Console.WriteLine(CType(packageResult, PackageExecutionResult) .ToString) 
Console. ReadKey() 


End Sub 


Private Enum PackageExecutionResult 
PackageSucceeded 
PackageFailed 
PackageCompleted 
PackageWasCancelled 

End Enum 


End Module 


using System; 


namespace LaunchSSISPackageSvcTestCS 
i 

class Program 

{ 


static void Main(string[] args) 


{ 


LaunchSSISPackageServiceCS.LaunchSSISPackageServiceCS launchPackageService = new 
LaunchSSISPackageServiceCsS.LaunchSSISPackageServiceCsS() ; 
int packageResult = 0; 


try 
{ 
packageResult = launchPackageService.LaunchPackage("sql", String.Empty, "SimpleTestPackage") ; 
t 
catch (Exception ex) 
it 


// The type of exception returned by a Web service is: 
// System.Web.Services.Protocols.SoapException 


Console.WriteLine("The following exception occurred: + ex.Message) ; 


} 


Console.WriteLine(((PackageExecutionResult) packageResult) .ToString()); 
Console. ReadKey() ; 


private enum PackageExecutionResult 


{ 


PackageSucceeded, 
PackageFailed, 
PackageCompleted, 
PackageWasCancelled 


}3 


External Resources 


e Video, How to: Automate SSIS Package Execution by Using the SQL Server Agent (SQL Server Video), on 
technet.microsoft.com 


See Also 


Understanding the Differences between Local and Remote Execution 
Loading and Running a Local Package Programmatically 
Loading the Output of a Local Package 
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Client applications can read the output of Integration Services packages when the output is saved to SQL Server 
destinations by using ADO.NET, or when the output is saved to a flat file destination by using the classes in the 
System.IO namespace. However, a client application can also read the output of a package directly from 
memory, without the need for an intermediate step to persist the data. The key to this solution is the 
Microsoft.SqlServer.Dts.DtsClient namespace, which contains specialized implementations of the 
IDbConnection, |IDbCommand, and |DbDataParameter interfaces from the System.Data namespace. The 
assembly Microsoft.SqlServer.Dts.DtsClient.dll is installed by default in %ProgramFiles%\Microsoft SQL 
Server\100\DTS\Binn. 


IMPORTANT 

The procedure described in this article, which uses the Dtsclient library, works only for packages deployed with the 
package deployment model (that is, with the /sQlL , /DTS , or /File option). This procedure does not work for 
packages deployed with the server deployment model (that is, with the /Isserver option). To consume the output of a 
local package deployed with the server deployment model (that is, with the /1sserver option), use the Data Streaming 


Destination instead of the procedure described in this article. 








NOTE 


The procedure described in this topic requires that the DelayValidation property of the Data Flow task and of any parent 
objects be set to its default value of False. 











Description 


This procedure demonstrates how to develop a client application in managed code that loads the output of a 
package with a DataReader destination directly from memory. The steps summarized here are demonstrated in 
the code sample that follows. 


To load data package output into a client application 

1. In the package, configure a DataReader destination to receive the output that you want to read into the 
client application. Give the DataReader destination a descriptive name, since you will use this name later 
in your client application. Make a note of the name of the DataReader destination. 


2. In the development project, set a reference to the Microsoft.SqlServer.Dts.DtsClient namespace by 
locating the assembly Microsoft.SqlServer.Dts.DtsClient.dll. By default, this assembly is installed in 
C:\Program Files\Microsoft SQL Server\100\DTS\Binn. Import the namespace into your code by 
using the C# Using or the Visual Basic Imports statement. 


3. In your code, create an object of type DtsClient.DtsConnection with a connection string that contains 
the command-line parameters required by dtexec.exe to run the package. For more information, see 
dtexec Utility. Then open the connection with this connection string. You can also use the dtexecuii utility 
to create the required connection string visually. 





NOTE 
The sample code demonstrates loading the package from the file system by using the 
/FILE <path and filename> syntax. However you can also load the package from the MSDB database by using 


the /SQL <package name> syntax, or from the Integration Services package store by using the 


/DTS \<folder name>\<package name> syntax. 








4. Create an object of type DtsClient.DtsCommand that uses the previously created DtsConnection and 
set its Commandfext property to the name of the DataReader destination in the package. Then call the 
ExecuteReader method of the command object to load the package results into a new DataReader. 


5. Optionally, you can indirectly parameterize the output of the package by using the collection of 
DtsDataParameter objects on the DtsCommand object to pass values to variables defined in the 
package. Within the package, you can use these variables as query parameters or in expressions to affect 
the results returned to the DataReader destination. You must define these variables in the package in the 
DtsClient namespace before you can use them with the DtsDataParameter object from a client 
application. (You may need to click the Choose Variable Columns toolbar button in the Variables 
window to display the Namespace column.) In your client code, when you add a DtsDataParameter to 
the Parameters collection of the DtsCommand, omit the DtsClient namespace reference from the 


variable name. For example: 


command.Parameters.Add(new DtsDataParameter("MyVariable", 1)); 


6. Call the Read method of the DataReader repeatedly as needed to loop through the rows of output data. 


Use the data, or save the data for later use, in the client application. 





IMPORTANT 


The Read method of this implementation of the DataReader returns true one more time after the last row of data 
has been read. This makes it difficult to use the usual code that loops through the DataReader while Read returns 
true. If your code attempts to close the DataReader or the connection after reading the expected number of rows, 
without an additional, final call to the Read method, the code will raise an unhandled exception. However, if your 
code attempts to read data on this final iteration through a loop, when Read still returns true but the last row 
has been passed, the code will raise an unhandled ApplicationException with the message, "The SSIS 
|DataReader is past the end of the resultset." This behavior is different from that of other DataReader 
implementations. Therefore, when using a loop to read through the rows in the DataReader while Read returns 
true, you need to write code to catch, test, and discard this anticipated ApplicationException on the last 
successful call to the Read method. Or, if you know in advance the number of rows expected, you can process the 


rows, and then call the Read method one more time before closing the DataReader and the connection. 








7. Call the Dispose method of the DtsCommand object. This is particularly important if you have used 
any DtsDataParameter objects. 


8. Close the DataReader and the connection objects. 


Example 


The following example runs a package that calculates a single aggregate value and saves the value to a 
DataReader destination, and then reads this value from the DataReader and displays the value in a text box on a 


Windows Form. 


The use of parameters is not required when loading the output of a package into a client application. If you do 
not want to use a parameter, you can omit the use of the variable in the DtsClient namespace, and omit the 


code that uses the DtsDataParameter object. 


To create the test package 


ile 


Create a new Integration Services package. The sample code uses "DtsClientWParamPkg.dtsx" as the 
name of the package. 


. Add a variable of type String in the DtsClient namespace. The sample code use Country as the name of 


the variable. (You may need to click the Choose Variable Columns toolbar button in the Variables 
window to display the Namespace column.) 


. Add an OLE DB connection manager that connects to the AdventureWorks2012 sample database. 
. Add a data flow task to the package and switch to the Data Flow design surface. 


. Add an OLE DB source to the data flow and configure it to use the OLE DB connection manager created 


previously, and the following SQL command: 


SELECT * FROM Sales.vIndividualCustomer WHERE CountryRegionName = ? 


. Click Parameters and, in the Set Query Parameters dialog box, map the single input parameter in the 


query, ParameterO, to the DtsClient::Country variable. 


. Add an Aggregate transformation to the data flow, and connect the output of the OLE DB source to the 


transformation. Open the Aggregate Transformation Editor and configure it to peform a "Count all" 
operation on all input columns (*) and to output the aggregated value with the alias CustomerCount. 


. Add a DataReader destination to the data flow and connect the output of the Aggregate transformation to 


the DataReader destination. The sample code uses "DataReaderDest" as the name of the DataReader. 
Select the single available input column, CustomerCount, for the destination. 


. Save the package. The test application created next will run the package and retrieve its output directly 


from memory. 


To create the test application 


1. 


Create a new Windows Forms application. 


. Add a reference to the Microsoft.SqlServer.Dts.DtsClient namespace by browsing to the assembly of 


the same name in %ProgramFiles%\Microsoft SQL Server\100\DTS\Binn. 


. Copy and paste the following sample code into the code module for the form. 


. Modify the value of the dtexecArgs variable as required so that it contains the command-line 


parameters required by dtexec.exe to run the package. The sample code loads the package from the file 
system. 


. Modify the value of the dataReaderName variable as required so that it contains the name of the 


DataReader destination in the package. 


. Put a button and a text box on the form. The sample code uses btnRun as the name of the button, and 


txtResults as the name of the text box. 


. Run the application and click the button. After a brief pause while the package runs, you should see the 


aggregate value calculated by the package (the count of customers in Canada) displayed in the text box 


on the form. 


Sample Code 


Imports System.Data 
Imports Microsoft.SqlServer.Dts.DtsClient 


Public Class Form1 


Private Sub btnRun_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles btnRun.Click 


Dim dtexecArgs As String 
Dim dataReaderName As String 
Dim countryName As String 


Dim dtsConnection As DtsConnection 
Dim dtsCommand As DtsCommand 

Dim dtsDataReader As IDataReader 

Dim dtsParameter As DtsDataParameter 


Windows.Forms.Cursor.Current = Cursors.WaitCursor 


dtexecArgs = "/FILE ""C:\...\DtsClientWParamPkg.dtsx""" 
dataReaderName = "DataReaderDest" 
countryName = "Canada" 


dtsConnection = New DtsConnection() 
With dtsConnection 
-ConnectionString = dtexecArgs 


-Open() 
End With 


dtsCommand = New DtsCommand(dtsConnection) 
dtsCommand.CommandText = dataReaderName 


dtsParameter = New DtsDataParameter("Country", DbType.String) 
dtsParameter.Direction = ParameterDirection. Input 
dtsCommand.Parameters.Add(dtsParameter ) 


dtsParameter.Value = countryName 


dtsDataReader = dtsCommand.ExecuteReader (CommandBehavior.Default) 


With dtsDataReader 

.Read() 

txtResults.Text = .GetInt32(@).ToString("Ne") 
End With 


"After reaching the end of data rows, 
"call the Read method one more time. 
Try 
dtsDataReader.Read() 
Catch ex As Exception 
MessageBox.Show("Exception on final call to Read method:" & ControlChars.CrLf & _ 
ex.Message & ControlChars.CrLf & _ 
ex.InnerException.Message, "Exception on final call to Read method", _ 
MessageBoxButtons.OK, MessageBoxIcon.Error) 
End Try 


The following method is a best practice, and is 


required when using DtsDataParameter objects. 
dtsCommand.Dispose() 


Try 
dtsDataReader.Close() 

Catch ex As Exception 
MessageBox.Show( "Exception closing DataReader:" & ControlChars.CrLf & _ 
ex.Message & ControlChars.CrLf & _ 
ex.InnerException.Message, "Exception closing DataReader", _ 
MessageBoxButtons.OK, MessageBoxIcon.Error) 

End Try 


Try 
dtsConnection.Close() 
Catch ex As Exception 
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ex.Message & ControlChars.CrLf & _ 
ex.InnerException.Message, "Exception closing connection", _ 
MessageBoxButtons.OK, MessageBoxIcon.Error) 

End Try 


Windows.Forms.Cursor.Current = Cursors.Default 


End Sub 


End Class 
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using System; 

using System.Windows. Forms; 

using System.Data; 

using Microsoft.SqlServer.Dts.DtsClient; 


namespace DtsClientwWParamCs 


{ 


public partial class Form1 : Form 


i 
public Form1() 


{ 


InitializeComponent() ; 
this.btnRun.Click += new System.EventHandler(this.btnRun_Click) ; 


private void btnRun_Click(object sender, EventArgs e) 


{ 


string dtexecArgs; 
string dataReaderName; 
string countryName; 


DtsConnection dtsConnection; 
DtsCommand dtsCommand; 
IDataReader dtsDataReader; 
DtsDataParameter dtsParameter; 


Cursor.Current = Cursors.WaitCursor; 

dtexecArgs = @"/FILE ""C:\...\DtsClientWParamPkg.dtsx"""; 
dataReaderName = "DataReaderDest"; 

countryName = "Canada"; 

dtsConnection = new DtsConnection(); 

{ 


dtsConnection.ConnectionString = dtexecArgs; 
dtsConnection.Open(); 


dtsCommand = new DtsCommand(dtsConnection) ; 

dtsCommand.CommandText = dataReaderName; 

dtsParameter = new DtsDataParameter("Country", DbType.String) ; 
dtsParameter.Direction = ParameterDirection. Input; 
dtsCommand.Parameters.Add(dtsParameter) ; 

dtsParameter.Value = countryName; 

dtsDataReader = dtsCommand.ExecuteReader(CommandBehavior.Default) ; 


dtsDataReader.Read(); 
txtResults.Text = dtsDataReader.GetInt32(@).ToString("Ne") ; 


//After reaching the end of data rows. 


// call the Read method one more time. 
try 
{ 
dtsDataReader.Read(); 
t 
catch (Exception ex) 
il 
MessageBox. Show( 
"Exception on final call to Read method:\n" + ex.Message + "\n" + ex.InnerException.Message, 
"Exception on final call to Read method", MessageBoxButtons.OK, MessageBoxIcon.Error) ; 


// The following method is a best practice, and is 
// required when using DtsDataParameter objects. 
dtsCommand.Dispose(); 


try 


{ 
dtsDataReader.Close(); 


} 


catch (Exception ex) 


{ 


MessageBox. Show( 
"Exception closing DataReader:\n" + ex.Message + "\n" + ex.InnerException.Message, 
"Exception closing DataReader", MessageBoxButtons.OK, MessageBoxIcon.Error) ; 


try 
{ 


dtsConnection.Close(); 


} 


catch (Exception ex) 


{ 
MessageBox. Show( 
"Exception closing connection:\n" + ex.Message + "\n" + ex.InnerException.Message, 
"Exception closing connection", MessageBoxButtons.OK, MessageBoxIcon.Error) ; 


Cursor.Current = Cursors.Default; 


See Also 


Understanding the Differences between Local and Remote Execution 
Loading and Running a Local Package Programmatically 
Loading and Running a Remote Package Programmatically 


Enumerating Available Packages Programmatically 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


As you work programmatically with Integration Services packages, you may want to determine whether an 
individual package or folder exists, or to enumerate the saved packages that are available to load and execute. 
The Application class of the Microsoft.SqiServer.Dts.Runtime namespace provides a variety of methods to satisfy 
these requirements. 


Determining Whether a Package or Folder Exists 


To determine programmatically whether a saved package exists, call one of the following methods before 
attempting to load and run it: 


STORAGE LOCATION METHOD TO CALL 
SSIS Package Store ExistsOnDtsServer 
SQL Server ExistsOnSqlServer 


To determine programmatically whether a folder exists before attempting to list the packages stored in it, call 
one of the following methods: 


STORAGE LOCATION METHOD TO CALL 

SSIS Package Store FolderExistsOnDtsServer 

SQL Server FolderExistsOnSqlServer 
Back to top 


Enumerating Available Packages 


To obtain a list of saved packages programmatically, call one of the following methods: 


STORAGE LOCATION METHOD TO CALL 
SSIS Package Store GetDtsServerPackagelnfos 
SQL Server GetPackagelnfos 


The following samples are console applications that demonstrate the use of these methods. 


Example (SSIS Package Store) 


Use the GetDtsServerPackagelnfos method to list packages stored in the SSIS Package Store. The default storage 
locations that are managed by the SSIS Package store are File System and MSDB. You can create additional 
logical folders within these locations. 


Imports Microsoft.SqlServer.Dts.Runtime 


Module Module1 


Sub Main() 


Dim sqlFolder As String 
Dim sqlServer As String 


Dim ssisApplication As Application 
Dim sqlPackages As PackageInfos 
Dim sqlPackage As PackageInfo 


sqlServer = 


ssisApplication = New Application() 
" Get packages stored in MSDB. 
sqlFolder = "MSDB" 
sqlPackages = ssisApplication.GetDtsServerPackageInfos(sqlFolder, sqlServer) 
If sqlPackages.Count > @ Then 

Console.WriteLine("Packages stored in MSDB:") 

For Each sqlPackage In sqlPackages 

Console.WriteLine(sqlPackage.Name) 

Next 

Console.WriteLine() 
End If 
" Get packages stored in the File System. 
sqlFolder = "File System" 
sqlPackages = ssisApplication.GetDtsServerPackageInfos(sqlFolder, sqlServer) 
If sqlPackages.Count > @ Then 

Console.WriteLine("Packages stored in the File System:") 

For Each sqlPackage In sqlPackages 

Console.WriteLine(sqlPackage.Name) 

Next 

End If 


Console. Read() 


End Sub 


End Module 


using System; 
using Microsoft.SqlServer.Dts.Runtime; 


namespace EnumeratePackagesSSIS_ CS 


{ 


class Program 


{ 


static void Main(string[] args) 


{ 


string sqlFolder; 
string sqlServer; 


Application ssisApplication; 
PackageInfos sqlPackages; 


sqlServer = 
ssisApplication = new Application(); 


// Get packages stored in MSDB. 
sqlFolder = "MSDB"; 
sqlPackages = ssisApplication.GetDtsServerPackageInfos(sqlFolder, sqlServer) ; 
if (sqlPackages.Count > 0) 
{ 

Console.WriteLine("Packages stored in MSDB:"); 

foreach (PackageInfo sqlPackage in sqlPackages) 

{ 

Console.WriteLine(sqlPackage.Name) ; 


} 


Console.WriteLine(); 


// Get packages stored in the File System. 

sqlFolder = "File System"; 

sqlPackages = ssisApplication.GetDtsServerPackageInfos(sqlFolder, sqlServer) ; 
if (sqlPackages.Count > 0) 

{ 


Console.WriteLine("Packages stored in the File System:"); 
foreach (PackageInfo sqlPackage in sqlPackages) 


{ 


Console.WriteLine(sqlPackage.Name) ; 


Console.Read(); 


Back to top 


Example (SQL Server) 


Use the GetPackagelnfos method to list Integration Services packages that are stored in an instance of SQL 


Server. 


Imports Microsoft.SqlServer.Dts.Runtime 
Module Module1 
Sub Main() 
Dim sqlFolder As String 
Dim sqlServer As String 
Dim sqlUser As String 
Dim sqlPassword As String 
Dim ssisApplication As Application 
Dim sqlPackages As PackageInfos 
Dim sqlPackage As PackageInfo 
sqlFolder = String.Empty 
sqlServer = "(local)" 
sqlUser = String.Empty 
sqlPassword = String.Empty 
ssisApplication = New Application() 
sqlPackages = ssisApplication.GetPackageInfos(sqlFolder, sqlServer, sqlUser, sqlPassword) 
For Each sqlPackage In sqlPackages 
Console.WriteLine(sqlPackage.Name) 

Next 
Console. Read() 


End Sub 


End Module 


using System; 
using Microsoft.SqlServer.Dts.Runtime; 


namespace EnumeratePackagesSql_ CS 


{ 


class Program 


{ 


static void Main(string[] args) 
{ 

string sqlFolder; 

string sqlServer; 

string sqlUser; 


string sqlPassword; 


Application ssisApplication; 
PackageInfos sqlPackages; 


sqlFolder = String.Empty; 

sqlServer = "(local)"; 

sqlUser = String.Empty; 

sqliPassword = String.Empty; 

ssisApplication = new Application(); 

sqlPackages = ssisApplication.GetPackageInfos(sqlFolder, sqlServer, sqlUser, sqlPassword) ; 
foreach (PackageInfo sqlPackage in sqlPackages) 


{ 


Console.WriteLine(sqlPackage.Name) ; 


Console.Read(); 


Back to top 


See Also 


Package Management (SSIS Service) 


Managing Packages and Folders Programmatically 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


As you work programmatically with Integration Services packages, you may want to determine whether an 
individual package or folder exists, or to manage the folders in which packages are stored. The Application class 
of the Microsoft.SqlServer.Dts.Runtime namespace provides a variety of methods to satisfy these requirements. 


Determining Whether a Package or Folder Exists 


To determine programmatically whether a saved package exists, call one of the following methods before 
attempting to load and run the package: 


STORAGE LOCATION METHOD TO CALL 
SSIS Package Store ExistsOnDtsServer 
SQL Server ExistsOnSqlServer 


To determine programmatically whether a folder exists, call one of the following methods before attempting to 
list the packages stored in the folder, : 


STORAGE LOCATION METHOD TO CALL 

SSIS Package Store FolderExistsOnDtsServer 

SQL Server FolderExistsOnSq|Server 
Back to top 


Managing Packages and Folders 


The Application class of the Microsoft.SqlServer.Dts.Runtime namespace provides additional methods for 
managing packages and the folders in which they are stored. 


Removing a Package 


To remove a saved package programmatically, call one of the following methods: 


STORAGE LOCATION METHOD TO CALL 

SSIS Package Store RemoveFromDtsServer 

SQL Server RemoveFromSq|Server 
Back to top 


Creating a Folder 


To create a storage folder programmatically, call one of the following methods: 


STORAGE LOCATION METHOD TO CALL 


SSIS Package Store CreateFolderOnDtsServer 
SQL Server CreateFolderOnSq|Server 
Back to top 


Removing a Folder 


To remove a storage folder programmatically, call one of the following methods: 


STORAGE LOCATION METHOD TO CALL 

SSIS Package Store RemoveFolderFromDtsServer 

SQL Server RemoveFolderFromSq|Server 
Back to top 


Renaming a Folder 


To rename a storage folder programmatically, call one of the following methods: 


STORAGE LOCATION METHOD TO CALL 
SSIS Package Store RenameFolderOnDtsServer 
SQL Server RenameFolderOnSq|Server 
Back to top 
See Also 


Package Management (SSIS Service) 
Enumerating Available Packages Programmatically 


Managing Running Packages Programmatically 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


As you work programmatically with Integration Services packages, you may want to determine which packages 
are currently running. The Application class of the Microsoft.SqlServer.Dts.Runtime namespace provides 
methods and classes to satisfy these requirements. 


For more information about monitoring packages, see Package Management (SSIS Service). 


All the methods discussed in this topic require a reference to the Microsoft.SqlServer.ManagedDTS 
assembly. After you add the reference in a new project, import the Microsoft.SqiServer.Dts.Runtime namespace 
with a using or Imports statement. 





IMPORTANT 


The methods of the Application class for working with the SSIS Package Store support only ".", localhost, or the server 
name for the local server. You cannot use "(local)". 











Determining Which Packages Are Currently Running 


To determine which packages are currently running on the specified server, call the GetRunningPackages 
method. This method returns a RunningPackages collection of RunningPackage objects. 


NOTE 


Administrators see all packages that are currently executing on the computer; other users see only those packages that 


they have launched. 





Working with Running Packages 


After you have determined which packages are currently running, you can retrieve information about the 
packages and request that a package be stopped. 


Getting Information about a Running Package 


As you iterate through the RunningPackages collection, you can use the properties of the RunningPackage 
object to locate a package or to obtain additional information about the packages that are running: 


e ExecutionDuration 
e ExecutionStartTime 
@ InstancelD 

e PackageDescription 
e PackagelD 

e PackageName 


e UserName 


Stopping a Running Package 


You can call the Stop method of a RunningPackage object to request that the package be stopped. There may be 
a delay between the time that a stop request is issued and the time that the package actually stops. 


See Also 


Package Management (SSIS Service) 
Enumerating Available Packages Programmatically 


Managing Package Roles Programmatically (SSIS 


Service) 
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Applies to: Q sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


As you work programmatically with Integration Services packages, you may want to determine which roles are 
available to apply to packages, or to determine or set the roles applied to an individual package. The Application 
class of the Microsoft.SqlServer.Dts.Runtime namespace provides a variety of methods to satisfy these 
requirements. 


Roles apply only to packages stored in the SQL Server msdb database. For more information about package 
roles, see Integration Services Roles (SSIS Service). 


All the methods discussed in this topic require a reference to the Microsoft.SqlServer.ManagedDTS 
assembly. After you add the reference in a new project, import the Microsoft.SqlServer.Dts.Runtime namespace 
by using a using or Imports statement. 


IMPORTANT 


The methods of the Application class for working with the SSIS Package Store support only ".", localhost, or the server 


name for the local server. You cannot use "(local)". 





Determining Which Roles Are Available 


To determine which roles are available for the packages stored on a particular server, call the GetDtsServerRoles 
method of the Application class. 


Determining Which Roles Are Assigned 


To determine which roles have already been assigned to a particular package, call the GetPackageRoles method. 
To assign roles to a package, call the SetPackageRoles method. 


See Also 


Integration Services Roles (SSIS Service) 


Integration Services Language Reference 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 
Applies to: @sal Server (all supported versions) 


This section describes the Transact-SQL API for administering Integration Services projects that have been 
deployed to an instance of SQL Server. 


Integration Services stores objects, settings, and operational data in a database referred to as the Integration 
Services catalog. The default name of the Integration Services catalog is SSISDB. The objects that are stored in 
the catalog include projects, packages, parameters, environments, and operational history. 


The Integration Services catalog stores its data in internal tables that are not visible to users. However it exposes 
the information that you need through a set of public views that you can query. It also provides a set of stored 
procedures that you can use to perform common tasks on the catalog. 


Typically you manage Integration Services objects in the catalog by opening SQL Server Management Studio. 
However you can also use the database views and stored procedures directly, or write custom code that calls the 
managed API. Management Studio and the managed API query the views and call the stored procedures that are 
described in this section to perform many of their tasks. 


In This Section 


Views (Integration Services Catalog) 
Query the views to inspect Integration Services objects, settings, and operational data. 


Stored Procedures (Integration Services Catalog) 
Call the stored procedures to add, remove, or modify Integration Services objects and settings. 


Functions (Integration Services Catalog) 
Call the functions to administer Integration Services projects. 


Azure Feature Pack for Integration Services (SSIS) 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


SQL Server Integration Services (SSIS) Feature Pack for Azure is an extension that provides the components 
listed on this page for SSIS to connect to Azure services, transfer data between Azure and on-premises data 
sources, and process data stored in Azure. 


Download 


e For SQL Server 2019 - Microsoft SQL Server 2019 Integration Services Feature Pack for Azure 
e@ For SQL Server 2017 - Microsoft SQL Server 2017 Integration Services Feature Pack for Azure 
e For SQL Server 2016 - Microsoft SQL Server 2016 Integration Services Feature Pack for Azure 
e For SQL Server 2014 - Microsoft SQL Server 2014 Integration Services Feature Pack for Azure 
e@ For SQL Server 2012 - Microsoft SQL Server 2012 Integration Services Feature Pack for Azure 


The download pages also include information about prerequisites. Make sure you install SQL Server before you 
install the Azure Feature Pack on a server, or the components in the Feature Pack may not be available when you 
deploy packages to the SSIS Catalog database, SSISDB, on the server. 


Components in the Feature Pack 


e Connection Managers 
o Azure Data Lake Analytics Connection Manager 
o Azure Data Lake Store Connection Manager 
o Azure HDInsight Connection Manager 


o Azure Resource Manager Connection Manager 


° 


Azure Storage Connection Manager 

o Azure Subscription Connection Manager 
@ Tasks 

o Azure Blob Download Task 

o Azure Blob Upload Task 

o Azure Data Lake Analytics Task 

o Azure Data Lake Store File System Task 

o Azure HDinsight Create Cluster Task 

o Azure HDinsight Delete Cluster Task 

o Azure HDInsight Hive Task 

o Azure HDInsight Pig Task 


o Azure Synapse Analytics Task 


o Flexible File Task 
e Data Flow Components 
o Azure Blob Source 
o Azure Blob Destination 
o Azure Data Lake Store Source 


Azure Data Lake Store Destination 


° 


o Flexible File Source 


Flexible File Destination 


° 


e Azure Blob, Azure Data Lake Store, and Data Lake Storage Gen2 File Enumerator. See Foreach Loop 
Container 


Use TLS 1.2 


The TLS version used by Azure Feature Pack follows system .NET Framework settings. To use TLS 1.2, adda 
REG_DWORD value named SchUseStrongcrypto with data 1 under the following two registry keys. 


1. HKEY_LOCAL_MACHINE \SOFTWARE \WOW6432Node\Microsoft\ .NETFramework\v4.@.30319 


2. HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\ .NETFramework\v4.0. 30319 


Dependency on Java 


Java is required to use ORC/Parquet file formats with Azure Data Lake Store/Flexible File connectors. 
The architecture (32/64-bit) of Java build should match that of the SSIS runtime to use. The following Java 
builds have been tested. 


e Zulu's OpenJDK 8u192 


e Oracle's Java SE Runtime Environment 8u192 


Set Up Zulu's OpenJDK 

1. Download and extract the installation zip package. 

. From the Command Prompt, run sysdm.cpl . 

. On the Advanced tab, select Environment Variables. 
. Under the System variables section, select New. 


. Enter JavA_HomE for the Variable name. 
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. Select Browse Directory, navigate to the extracted folder, and select the jre subfolder. Then select OK, and 


the Variable value is populated automatically. 


—N 


. Select OK to close the New System Variable dialog box. 
8. Select OK to close the Environment Variables dialog box. 


9. Select OK to close the System Properties dialog box. 





TIP 


If you use Parquet format and hit error saying "An error occurred when invoking java, message: 
java.lang-OutOfMemoryError:Java heap space", you can add an environment variable _jav4_opTrons to adjust 


the min/max heap size for JVM. 


Edit System Variable x 


Variable name: JAVA_OPTIONS 
Variable value: -Xms256m -Xmx1 6g 


cone 





| Browse Directory... Browse File... 





Example: set variable _java_options with value -xms256m -xmx16g . The flag Xms specifies the initial memory allocation 
pool for a Java Virtual Machine JVM), while Xmx specifies the maximum memory allocation pool. This means that JVM 
will be started with xms amount of memory and will be able to use a maximum of xmx amount of memory. The default 


values are min 64MB and max 1G. 





Set Up Zulu's OpenJDK on Azure-SSIS Integration Runtime 


This should be done via custom setup interface for Azure-SSIS Integration Runtime. Suppose 
zulu8.33.@.1-jdk8.0.192-win_x64.zip is used. The blob container could be organized as follows. 


main.cmd 
install_openjdk.ps1 
zulu8.33.0.1-jdk8.0.192-win_x64.zip 


As the entry point, main.cmd triggers execution of the PowerShell script install_openjdk.ps1 which in turn 
extracts zulu8.33.0.1-jdk8.0.192-win_x64.zip andsets JAVA_HOME accordingly. 


main.cmd 


powershell.exe -file install_openjdk.ps1 


TIP 
If you use Parquet format and hit error saying "An error occurred when invoking java, message: 
java.lang.OutOfMemoryError:Java heap space", you can add command in main.cmd to adjust the min/max heap 


size for JVM. Example: 


setx /M _JAVA_OPTIONS "-Xms256m -Xmx16g" 


The flag Xms specifies the initial memory allocation pool for a Java Virtual Machine JVM), while Xmx specifies the 
maximum memory allocation pool. This means that JVM will be started with xms amount of memory and will be able to 


use amaximum of xmx amount of memory. The default values are min 64MB and max 1G. 














install_openjdk.ps1 


Expand-Archive zulu8.33.@.1-jdk8.@.192-win_x64.zip -DestinationPath C:\ 
[Environment]: :SetEnvironmentVariable("JAVA_HOME", "C:\zulu8.33.0.1-jdk8.0.192-win_x64\jre", "Machine") 


Set Up Oracle's Java SE Runtime Environment 


1. Download and run the exe installer. 


2. Follow the installer instructions to complete setup. 


Scenario: Processing big data 
Use Azure Connector to complete following big data processing work: 
1. Use the Azure Blob Upload Task to upload input data to Azure Blob Storage. 


2. Use the Azure HDInsight Create Cluster Task to create an Azure HDInsight cluster. This step is optional if 


you want to use your own cluster. 


3. Use the Azure HDInsight Hive Task or Azure HDInsight Pig Task to invoke a Pig or Hive job on the Azure 
HDInsight cluster. 


4. Use the Azure HDInsight Delete Cluster Task to delete the HDInsight Cluster after use if you have created 
an on-demand HDInsight cluster in step #2. 


5. Use the Azure HDInsight Blob Download Task to download the Pig/Hive output data from the Azure Blob 
Storage. 


Ck’ Azure Blob Upload Task 


| 


& Azure HDInsight Pig Task $e FP Azure HDInsight Create Cluster Task 


iP Azure HDInsight Hive Task > rod Azure HDInsight Delete Cluster Task 


> Azure Blob Download Task 


Scenario: Managing data in the cloud 


Use the Azure Blob Destination in an SSIS package to write output data to Azure Blob Storage, or use the Azure 
Blob Source to read data from an Azure Blob Storage. 
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Data Flow Task: | gig Data Flow -Read “Customer” tat 


= OLE DB Source 


Al Conditional Split - Filter out expired data 
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Use the Foreach Loop Container with the Azure Blob Enumerator to process data in multiple blob files. 


iw Data Flow i Parameters Event Har 
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a a Data Flow Task - Process Blob File 


Release Notes 


Version 1.20.0 


Improvements 
1. Updated target INET Framework version from 4.6 to 4.7.2. 
2. Renamed "Azure SQL DW Upload Task" to "Azure Synapse Analytics Task”. 


Bugfixes 


1. When accessing Azure blob storage and the machine running SSIS is in a non en-US locale, package 
execution will fail with error message "String not recognized as a valid DateTime value". 


2. For Azure Storage Connection Manager, secret is required (and unused) even when Data Factory managed 
identity is used to authenticate. 


Version 1.19.0 


Improvements 


1. Added support for shared access signature authentication to Azure Storage connection manager. 


Version 1.18.0 

Improvements 

1. For Flexible File task, three are three improvements: (1) wildcard support for copy/delete operations is 
added; (2) user can enable/disable recursive searching for delete operation; and (3) the file name of 
Destination for copy operation can be empty to keep the source file name. 


Version 1.17.0 


This is a hotfix version released for SQL Server 2019 only. 


Bugfixes 
1. When executing in Visual Studio 2019 and targeting SQL Server 2019, Flexible File Task/Source/Destination 
may fail with the error message Attempted to access an element as a type incompatible with the array. 


2. When executing in Visual Studio 2019 and targeting SQL Server 2019, Flexible File Source/Destination using 
ORC/Parquet format may fail with the error message 


Microsoft.DataTransfer.Common.Shared.HybridDeliveryException: An unknown error occurred. 
JNI.JavaExceptionCheckException. 


Version 1.16.0 
Bugfixes 
1. In certain cases, package execution reports "Error: Could not load file or assembly ‘NewtonsoftJson, 


Version=11.0.0.0, Culture=neutral, PublickeyToken=30ad4fe6b2a6aeed’ or one of its dependencies." 


Version 1.15.0 

Improvements 

1. Add delete folder/file operation to Flexible File Task 

2. Add External/Output data type convert function in Flexible File Source 


Bugfixes 


1. In certain cases, test connection malfunctions for Data Lake Storage Gen2 with the error message "Attempted 
to access an element as a type incompatible with the array" 


2. Bring back support for Azure Storage Emulator 


Hadoop and HDFS Support in Integration Services 


(SIRS) 
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Applies to: @sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


SQL Server 2016 Integration Services (SSIS) includes the following components that provide support for 
Hadoop and HDFS on premises. 


For info about the Integration Services components that support HDInsight and other features of Microsoft 
Azure, see Azure Feature Pack for Integration Services (SSIS). 


e@ Connection manager 


o Hadoop Connection Manager 


© Control flow - Tasks 
© Hadoop File System Task 
© Hadoop Hive Task 
o Hadoop Pig Task 
e Data flow - Data source and destination 
o HDFS File Source 


o HDFS File Destination 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Microsoft Connector for Oracle enables the ability to export data from and load data into Oracle data source in 
an SSIS package. 


Version support 
The following Microsoft SQL Server products are supported by Microsoft Connector for Oracle: 


e Since SQL Server 2019 CU1 
e SQL Server Data Tools (SSDT) 15.9.3 or later for Visual Studio 2017 
e Microsoft SQL Server Data Tools (SSDT) for Visual Studio 2019 


The following Oracle database versions of data source are supported: 


e@ Oracle 10.x 
e@ Oracle 11.x 
e@ Oracle 12c 
e@ Oracle 18c (without Windows Authentication support) 


e@ Oracle 19c (without Windows Authentication support) 


The Oracle database is supported on all operating systems and platforms. 





NOTE 


Oracle client is not required for Microsoft Connector for Oracle database in SQL Server 2019. 





Installation 


To install the connector for Oracle database, download and run the installer from the latest version of Microsoft 
connector for Oracle. Then follow the directions in the installation wizard. 


After you install the Connector, you must restart the SQL Server Integration Service to be sure that the Oracle 
source and destination can work correctly. 


To execute SSIS package targeting SQL Server 2017 and below, in addition to Microsoft Connector for 
Oracle, you will need to install Oracle client and Microsoft Connector for Oracle by Attunity with 
corresponding version from below links: 


e SQL Server 2017: Microsoft Connector Version 5.0 for Oracle by Attunity 
e SQL Server 2016: Microsoft Connector Version 4.0 for Oracle by Attunity 
e SQL Server 2014: Microsoft Connector Version 3.0 for Oracle by Attunity 
e@ SQL Server 2012: Microsoft Connector Version 2.0 for Oracle by Attunity 


Limitations and known issues 


e Views are not listed under Oracle source Name of the table or the view. As work-around, use the SQL 
command and do a select * from view, or set view name to property [Oracle Source].[TableName] in 


Advanced Editor. 


Uninstallation 


You can run uninstall wizard to remove Microsoft Connector for Oracle database from SQL Server. 


Next steps 


e Configure Oracle Connection Manager. 
e Configure Oracle Source. 
e Configure Oracle Destination. 


e If you have questions, visit TechCommunity. 


Oracle Connection Manager 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


An Oracle Connection Manager is used to enable a package to extract data from Oracle Databases and load data 
into Oracle Databases. 


The ConnectionManagerType property for the Oracle Connection Manager is set to ORACLE. 


Configuring the Oracle Connection Manager 


Oracle Connection Manager configuration changes will be resolved by Integration Services at runtime. Use the 
Oracle Connection Manager Editor dialog box to add a connection to an Oracle data source. 


*P Oracle Connection Manager Editor 


Connection manager infomation 


Name: Oracle Connection Manager 
Description: 











TNS service name: 
Connection manager logging 


© Use Windows Authentication 


@ Use Oracle Authentication 





User name: 





Password: 





Test Connection 


[ae] oe 











Options 
Connection manager information 


Enter information about the Oracle connection. 

Name 

Input a name for the Oracle connection. The default name is Oracle Connection Manager. 
Description 

Input a description of the connection. This input is optional. 

TNS service name 

Input the name of the Oracle database you work with. The TNS service name could be: 


e@ The connect descriptor name defined in the tnsnames.ora file that located in the admin folder of the 


Oracle client. 
e@ EzConnect format: [//Jhost[:port][/service_name] 


For more information, see the Oracle documentation. 
Connection Manager logging 
Select one of the below options: 


e Use Windows Authentication: Select this to use Windows authentication. 


e Use Oracle Authentication: Select this to use Oracle database authentication. If you use this 
authentication, enter your Oracle credentials as follows: 
User name: Type the user name used to connect to the Oracle database. 
Password: Type the Oracle database password for the user entered in the user name field. 


NOTE 


Windows Authentication is not supported for Oracle Server 18c. 





Test Connection 


Click Test Connection to verify if the information provided is correct. You will receive the message Test 
connection succeeded, if the information entered is able to connect to the Oracle database. 





NOTE 


If you wanna specify ConnectionString directly, here is the sample with Oracle Authentication: 


SERVER= < YourOracleServerName or EzConnect format>;USERNAME= < YourUserName>;PWD= 
<YourPassword>;WINAUTH=0 








Custom properties 


There are following custom connection manager properties in the Oracle connection manager: 
e EnableDetailedTracing: Not Used. 
e OracleHome: Specify 32-bit Oracle Home name or folder to be used by the connector. (Optional) 


e OracleHome64: Specify 64-bit Oracle Home name or folder to be used by the connector when running 
in 64-bit mode. (Optional) 


Custom properties are not listed in Oracle Connection Manager Editor. To set the OracleHome and 
OracleHome64 properties: 


1. From the Connection Manager area, right-click the Oracle connection manager you are working with and 
select Properties. 


2. In the Properties pane, set the OracleHome or OracleHome64 property with the full path to the 
Oracle home directory. 


Next steps 


e Configure Oracle Source. 
e Configure Oracle Destination. 


e If you have questions, visit TechCommunity. 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 
The Oracle source extracts data from Oracle Database with below modes: 

e A table or view. 

e The results of an SQL statement. 


The source uses an Oracle Connection Manager to connect to Oracle source. For more information, see Oracle 
Connection Manager. 


Error output 


Error output includes the following columns: 
e Error Code: A number that represents error type of the current error. The error code could be from: 


o Oracle server. See detail error description in Oracle database documentation. 
o SSIS runtime. For a list of SSIS error codes, see the SSIS Error Code and Message Reference. 


e Error Column: The source column number that causes the conversion errors. 
e Error Data Columns: The data which causes the error. 


The Oracle source returns errors occurred during loading and extraction process in the error output. For more 
information, see Oracle Source Editor (Error Output Page). 


Troubleshooting the Oracle source 


You can log the ODBC calls that the Oracle source makes to Oracle data sources to troubleshoot the data 
exporting. To log the ODBC calls that the Oracle source makes to Oracle data sources, enable the ODBC driver 
manager trace. For more information, see the Microsoft documentation on How To Generate an ODBC Trace 
with ODBC the Data Source Administrator. 


Oracle source custom properties 


The custom properties of the Oracle source are as below. All properties are read/write. 


PROPERTY NAME DATA TYPE DESCRIPTION 


AccessMode Integer (enumeration) The mode used to access the database. 
The possible values are Table Name 
and SQL Command. The default is 
Table Name. 


BatchSize Integer The size of the batch for bulk loading. 
This is the number of records extracted 
as an array. 

This property is set by Advanced 
Editor only 


PROPERTY NAME 


DefaultCodePage 


PreFetchCount 


SqlCommand 


TableName 


DATA TYPE 


Integer 


Integer 


String 


String 


Configuring the Oracle source 


DESCRIPTION 


The code page to use when data 
source does not have code page 
information. 

This property is set by Advanced 
Editor only. 


The number of pre-fetched rows. 
This property is set by Advanced 
Editor only. 


The SQL command to be executed 
when AccessMode is set to SQL 
Command. 


The name of the table with the data to 
be used when AccessMode is set to 
Table Name. 


You can configure the Oracle Source programmatically or through the SSIS Designer. 


The Oracle Source Editor is shown in below picture. It contains Connection Manager Page, Columns Page, and 


Error Output Page. 
For more information, see one of the following sections: 


e@ Oracle Source Editor (Connection Manager Page) 


e@ Oracle Source Editor (Columns Page) 


@ Oracle Source Editor (Error Output Page) 





j LL Oracle Source Editor oO x 


Configure the properties used by a data flow to obtain data from any Oracle provider. 





Connection Manager Specify an Oracle connection manager, a data source, or a data source view, and select the data access mode. If using 


Coben the SQL command access mode, specify the SQL command by typing the query. 
olumns 


Error Output 


Oracle connection manager: 


Oracle Connection Manager v New... 


Data access mode: 


Table Name v 


Name of the table or the view: 






























| db Select a table or view from the list. 








The Advanced Editor dialog box contains the properties that can be set programmatically. 


To open the Advanced Editor dialog box: 


e Inthe Data Flow screen of your Integration Services project, right-click the Oracle source and select Show 
Advanced Editor. 


For more information about the properties that you can set in the Advanced Editor dialog box, see Oracle 
Source Custom Properties. 


Oracle Source Editor (Connection Manager page) 


On Connection Manager page, Oracle Source Editor dialog box is to select Oracle Database as source, 
table, or view from the database. 


To open the Oracle Source Editor Connection Manager Page 


e@ In SQL Server Data Tools, open the SQL Server Integration Services (SSIS) package that has the Oracle 
source. 


e@ On the Data Flow tab, double-click the Oracle source. 


Options 


Connection manager 


Select an existing connection manager from the list or click New to create a new Oracle connection manager. 
New 


Click New. The Oracle Connection Manager Editor dialog box opens where you can create a new 


connection manager. 
Data Access Mode 


Select the method for selecting data from the source. The options are shown in the following table: 
OPTION DESCRIPTION 


Table or view Retrieve data from a table or view in the Oracle data source. 
When this option is selected, select an available table or view 
from the list for Name of the table or the view. 


SQL command Retrieve data from the Oracle data source by using an SQL 
query. When this option is selected, enter a query in one of 
the following ways: 

Enter the text of the SQL query in the SQL command text 
field. 

Click Browse to load the SQL query from a text file. 

Click Parse query to verify the syntax of the query text. 


Preview 


Click Preview to view up to the first 200 rows of the data extracted from the table or view you selected. 


Oracle Source Editor (Columns page) 


On Columns page, Oracle Source Editor dialog box is used to map an output column to each external 


(source) column. 
To open the Oracle Source Editor Columns Page 


e In SQL Server Data Tools, open the SQL Server Integration Services (SSIS) package that has the Oracle 


source. 
e On the Data Flow tab, double-click the Oracle source. 
e Inthe Oracle Source Editor, click Columns. 


Options 


Available External Columns 


A list of available external columns that can be selected to add to External Column list in the order they are 
selected. This table cannot be used to add or delete columns. 


Select the Select All check box to select all the columns. 
External Columns 


The external (source) columns that you selected is listed in order. To change the order, first clear **Available 
External Column’ list, and then select the column(s) with a different order. 


Output Column 


The name of the selected external (source) column is the default output name. While you can input any unique 


name. 





NOTE 


If there are columns with unsupported data types, there will be a warning shown the data types are not supported, and 


related columns will be removed from mapping columns. 











Oracle Source Editor (Error Output page) 
Use the Error Output page of the Oracle Source Editor dialog box to select error handling options. 
To open the Oracle Source Editor Error Output Page 


e@ In SQL Server Data Tools, open the SQL Server Integration Services (SSIS) package that has the Oracle 


source. 
e On the Data Flow tab, double-click the Oracle source. 
e Inthe Oracle Source Editor, click Error Output. 


Options 


Error behavior 


Select how the Oracle source should handle errors in a flow: ignore the failure, redirect the row, or fail the 
component. Related section: Error Handling in Data 


Truncation 


Select how the Oracle source should handle truncation in a flow: ignore the failure, redirect the row, or fail the 


component. 


Next steps 


e Configure Oracle Destination. 


e If you have questions, visit TechCommunity. 


Oracle destination 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 
The Oracle destination bulk loads data into Oracle Database. 


The destination uses the Oracle Connection Manager to connect to a data source. For more information, see 
Oracle Connection Manager. 


An Oracle destination includes mappings between input columns and columns in the destination data source. 
You do not have to map input columns to all destination columns, but depending on the properties of the 
destination columns, errors can occur if no input columns are mapped to the destination columns. For example, 
if a destination column does not allow null values, an input column must be mapped to that column. In addition, 
if the input data is not compatible for the destination column type, an error occurs at runtime. Depending on the 
error behavior setting, the error will be ignored, cause a failure, or the row is redirected to the error output. 


The Oracle destination has one regular input and one error output. 


Columns of unsupported data types are deleted from columns with a warning before mapping. For more 
information, see Data Type Support. 


Load options 


Two access load modes are supported. The mode can be set in the Oracle Destination Editor (Connection 
Manager Page). The two modes are: 


e Batch load: This mode is to load data into Oracle table in batches and the entire batch is inserted under 
the same transaction. Details on how to configure this mode, see Oracle Destination Editor (Connection 
Manager Page) and Oracle Destination Custom Properties. 


e Fast load using Direct Path: This mode is to use the direct path mode of the driver for loading Oracle 
table. There are restrictions when using this mode, refer to Oracle documentation for details. 
Details on how to configure this mode, see Oracle Destination Editor (Connection Manager Page) and 
Oracle Destination Custom Properties. 


Error handling 
The Oracle destination has an error output. The component error output includes the following output columns: 
e Error Code: A number that represents error type of the current error. The error code could be from: 


o Oracle server. See detail error description in Oracle database documentation. 
o SSIS runtime. For a list of SSIS error codes, see the SSIS Error Code and Message Reference. 


e Error Column: The source column number that causes the conversion errors. 


e Error Data Columns: The data that causes the error. 


Types of output errors during the loading process supported are: data conversion, truncation, or constraint 
violation and so on. See Oracle Destination Editor (Error Output Page). 


Maximum number of errors (MaxErrors) property sets the maximum number of errors that can occur. 
Execution stops and returns errors when maximum number is reached. And only execution records before the 


maximum error number reaches are included in target table. see Oracle Destination Editor (Connection Manager 


Page) for detail configuration. 


Parallelism 


In batch loading mode, there is no restriction on configuration of parallel run, but the performance might be 
impacted by standard record locking mechanism. The amount of performance loss depends on the data and 


table organization. 


In direct path protocol (fast load), only one Oracle destination can be configured to run against the same table at 


the same time, but can use Parallel mode. 


A parallel direct path allows multiple direct path loads, with which multiple Oracle destinations can be 
configured to run concurrently against the same table at the same time. Oracle does not lock the target table 
exclusively to use in the fast load session, which allows running additional fast load destination components to 
load the same target table in parallel. The parallel direct path is more restrictive, any use of parallelism that 
should be planned in advance. 


There is no reason to use a single Parallel session. 
See Oracle documentation regarding restrictions when using Parallel direct path loads. 


For more information, see Oracle Destination Custom Properties. 


Troubleshooting the Oracle destination 


You can log the ODBC calls that the Oracle source makes to Oracle data sources to troubleshoot the data 
exporting. To log the ODBC calls that the Oracle source makes to Oracle data sources, enable the ODBC driver 
manager trace. For more information, see the Microsoft documentation on How To Generate an ODBC Trace 
with ODBC the Data Source Administrator. 


Oracle destination custom properties 


The following table describes the custom properties of the Oracle destination. All properties are read/write. 
PROPERTY NAME DATA TYPE DESCRIPTION LOADING MODE 


BatchSize Integer The size of the batch for Used only in batch mode. 
bulk loading. This is the 
number of rows loaded as a 
batch. 


DefaultCodePage Integer The code page to use when Use for both modes. 
data source does not have 
code page information. 
Note: This property is set 
by Advanced Editor only.. 


FastLoad Boolean Whether Fast Loading is Use for both modes. 
used. The default value is 
false. This can also be set in 
the Oracle Destination 
Editor (Connection 
Manager Page). 


PROPERTY NAME 


MaxErrors 


NoLogging 


Parallel 


TableName 


TableSubName 


TransactionSize 


TransferBufferSize 


Configuring the Oracle destination 


Oracle destination can be configured programmatically or through the SSIS Designer. 


DATA TYPE 


Integer 


Boolean 


Boolean 


String 


String 


Integer 


Integer 


DESCRIPTION 


The number of errors that 
can occur before the data 
flow is stopped. The default 
value is 0, which means no 
limit of error number. 

If Redirect flow is selected 
in the Error handling 
page. Before the error 
number limit reaches, all 
errors are returned in the 
error output. For more 
information, see Error 
Handling. 


Whether database logging 
is disabled. The default 
value is False, which means 
that logging is enabled. 


Whether parallel loading is 
allowed. True indicates that 
other loading sessions are 
allowed to run against the 
same target table. 

For more information, see 
in Parallelism. 


The name of the table with 
the data that is being used. 


The subname or 
subpartition. This value is 
optional. 

Note: This property can 
only be set in Advanced 
Editor. 


The number of inserts that 
can be made in a single 
transaction. The default is 
the BatchSize. 


The size of the transfer 
buffer. The default value is 
64 KB. 


LOADING MODE 


Used only in Fast Load 
mode. 


Use for both modes. 


Used only in Fast Load 
mode. 


Used for both modes. 


Used only in Fast Load 
mode. 


Used only in batch mode. 


Used only in Fast Load 
mode. 


The Oracle Destination Editor is shown in below picture. It contains Connection Manager Page, Mappings Page, 


and Error Output Page. 


For more information, see one of the following sections: 


e Oracle Destination Editor (Connection Manager Page) 


e Oracle Destination Editor (Mappings Page) 


@ Oracle Destination Editor (Error Output Page) 


















|| Oracle Destination Editor O x 


Configure the properties used to insert data into a relational database using an Oracle provider. 





Specify an Oracle connection manager, a data source, or a data source view, and select the data access mode. 
Mappings 
Error Output 


Oracle connection manager: 


| Oracle Connection Manager v | New... 


Data access mode: 


Table Name v 


Name of the table or the view: 





























Maximum number of errors: 0 
Transaction Size: 1000 
Rows per batch: 1000 




















| A Select a table or view from the list. 
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The Advanced Editor dialog box contains the properties that can be set programmatically. To open the 


Advanced Editor dialog box: 


e Inthe Data Flow screen of your Integration Services project, right-click the Oracle destination and select 
Show Advanced Editor. 


For more information about the properties that you can set in the Advanced Editor dialog box, see Oracle 
Destination Custom Properties. 


Oracle Destination Editor (Connection Manager page) 


Use the Connection Manager page of the Oracle Destination Editor dialog box to select the Oracle 
connection manager for the destination. This page also lets you select a table or view from the database. 


To open the Oracle Destination Editor Connection Manager Page 


e@ In SQL Server Data Tools, open the SQL Server Integration Services (SSIS) package that has the Oracle 
destination. 


e On the Data Flow tab, double-click the Oracle destination. 
e Inthe Oracle Destination Editor, click Connection Manager. 


Options 


Connection manager 
Select an existing connection manager from the list, or click New to create a new Oracle connection manager. 
New 


Click New. The Oracle Connection Manager Editor dialog box opens where you can create a new 
connection manager. 


Data access mode 


Select the method for selecting data from the source. The options are shown in the following table: 


OPTION DESCRIPTION 
Table Name Configure Oracle destination to work in batch mode. 
Options: 


Name of the table or the view: Select an available table 
or view from the database from the list. 


Transaction size: Input the number of inserts that can be 
in a single transaction. The default is the BatchSize. 


Batch size: Type the size (number of rows loaded) of the 
batch for bulk loading. 


Table Name — Fast Load Configure the Oracle destination to work in fast (Direct Path) 
load mode. 


Options are available: 


Name of the table or the view: Select an available table 
or view from the database from the list. 


Parallel load: Whether parallel loading is enabled. For more 
information, see Parallelism. 


No logging: This check box to disable database logging. 
This logging is Oracle database used for recovery purpose, 
not related to tracing. 

Maximum number of errors: Maximum number of errors 
that can occur before the data flow is stopped. The default 
value is 0, which means there is no number limit. 


All errors can occur are returned in the error output. 


Transfer buffer size (KB): Input the size of the transfer 
buffer. The default size is 64 KB. 


View Existing Data 


Click View Existing Data to view up to 200 rows of data for the table that you selected. 


Oracle Destination Editor (Mappings page) 


Use the Mappings page of the Oracle Destination Editor dialog box to map input columns to destination 
columns. 


To open the Oracle Destination Editor Mappings Page 


e In SQL Server Data Tools, open the SQL Server Integration Services (SSIS) package that has the Oracle 
destination. 


e On the Data Flow tab, double-click the Oracle destination. 
e Inthe Oracle Destination Editor, click Mappings. 


Options 


Available Input Columns 


The list of available input columns. Drag-and-drop an input column to an available destination column to map 


the columns. 
Available Destination Columns 


The list of available destination columns. Drag-and-drop a destination column to an available input column to 


map the columns. 
Input Column 


View the input columns that you selected. You can remove mappings by selecting < ignore > to exclude 


columns from the output. 
Destination Column 


View all available destination columns, both mapped and unmapped. 





NOTE 


Columns of unsupported data types will be deleted from mapping with a warning. 





Oracle Destination Editor (Error Output page) 
Use the Error Output page of the Oracle Destination Editor dialog box to select error handling options. 
To open the Oracle Destination Editor Error Output Page 


e In SQL Server Data Tools, open the SQL Server Integration Services (SSIS) package that has the Oracle 
destination. 


e@ On the Data Flow tab, double-click the Oracle destination. 
e In the Oracle Destination Editor, click Error Output. 


Options 


Error behavior 


Select how the Oracle source should handle errors in a flow: ignore the failure, redirect the row, or fail the 
component. Related Section: Error Handling in Data 


Truncation 


Select how the Oracle source should handle truncation in a flow: ignore the failure, redirect the row, or fail the 


component. 


Next steps 


e Configure Oracle Connection Manager. 


e Configure Oracle Source. 


e Configure Oracle Destination. 


e If you have questions, visit TechCommunity. 


Microsoft Connector for Oracle data type support 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


SSIS components for Oracle do not support all Oracle data types. Columns with unsupported data types will 
have a warning when designing packages in SSDT and will be deleted from mapping columns. Data cannot be 


loaded to a column with an unsupported data type. 


Data type mapping 


The following table shows the Oracle database data types and their default mapping to SSIS data types. It also 
shows the unsupported Oracle data types. 


ORACLE DATABASE DATA TYPE 


VARCHAR2 


NVARCHAR2 


CHAR 


NUMBER 


NUMBER(P S) 


DATE 


TIMESTAMP 

TIMESTAMP WITH TIME ZONE 
INTERVAL YEAR TO MONTH 
INTERVAL DAY TO SECOND 
TIMESTAMP WITH LOCAL TIME 
ZONE 


RAW 


CLOB 


SSIS DATA TYPE COMMENTS 

DT_STR 

DT_WSTR 

DT_STR 

DT_R8& This can be changed to DT_.NUMERIC 


with specific precision and scale. 
Precision and scale are defined by user 
per the need. The output will be the 
column data as a number with fixed 
precision and scale. 


When the scale is 0, according to the 
precision (P) 

e DT!1 

e DT_l2 

e DT_l4 

e DT_NUMBERIC(PO) 


DT_NUMERIC(PS) 
DT_DBTIMESTAMP 


DT_STR 


DT_BYTES 


DT_TEXT CLOB, NCLOB, and BLOB data types 
are supported only in array mode, not 
in Fast Load mode. 


ORACLE DATABASE DATA TYPE 


NCLOB 


BLOB 


UROWID 


REF 


BFILE 


LONG 


LONG RAW 


ROWID 


User-defined type (object type, 
VARRAY, Nested Table) 


Next steps 


SSIS DATA TYPE 


DT_NTEXT 


DT_IMAGE 


Not Supported 


Not Supported 


Not Supported 


Not Supported 


Not Supported 


Not Supported 


Not Supported 


Configure Oracle Connection Manager. 


Configure Oracle Source. 


Configure Oracle Destination. 


If you have questions, visit TechCommunity. 


COMMENTS 


Microsoft connector for Teradata 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Microsoft connector for Teradata enables to export data from and load data into Teradata databases in an SSIS 
package. 


This new connector supports databases with 1MB-enabled tables. 


Version support 
The following Microsoft SQL Server products are supported by Microsoft Connector for Teradata: 


e Microsoft SQL Server 2019 
e Microsoft SQL Server Data Tools (SSDT) 15.8.1 or later for Visual Studio 2017 
e Microsoft SQL Server Data Tools (SSDT) for Visual Studio 2019 


Microsoft connector for Teradata uses Teradata Parallel Transporter Application Programming Language 
Interface to load into and export data from the Teradata database. The following versions are supported: 


e Teradata Parallel Transporter (Teradata PT) 16.10 
e Teradata Parallel Transporter (Teradata PT) 16.20 


The following Teradata database versions of data source are supported: 


e Teradata Database 16.20 
e Teradata Database 16.10 
e Teradata Database 15.10 
e Teradata Database 15.00 


Check Teradata documentation for details of Teradata Parallel Transporter Application programming interface 
programmer guide. 


Installation 


On 32-bit computers, install the following drivers from Teradata Tools and Utilities - Windows Installation 
Package: 


e Teradata ODBC driver (32-bit) 
e Teradata PT API (32-bit) 


On 64-bit computers, install the following drivers: 


e Teradata ODBC driver (64-bit) 
e Teradata PT API (64-bit) 


To install the connector for Teradata database, download and run the installer from the latest version of 
Microsoft connector for Teradata. Then follow the directions in the installation wizard. 


After you install the connector, you must restart the SQL Server Integration Service to be sure that the Teradata 
source and destination works correctly. 


Design and execute SSIS packages 


Microsoft Connector for Teradata provides similar user experience with Attunity Teradata Connector. User can 
design new packages based on previous experience, using SSDT for VS 2017 or VS 2019, with targeting SQL 
server 2079. 


Teradata source and destination are under Common category. 


4 Common 
&® Aggregate 
H§ Balanced Data Distributor 
B Conditional Split 


} a 
‘on Data Conversion 


7 Data Streaming Destination 


Derived Column 
2 HDFS File Destination 
5 HDFS File Source 
1 Lookup 
Merge 
Merge Join 
Multicast 
OData Source 
OOBC Destination 
ODBC Source 
OLE DB Command 
li Oracle Destination 
U® Oracle Source 
BE Power Query Source 
BB Row Count 
fag Script Component 
LZ Slowly Changing Dimension 
4T Son 
lu Teradata Destination 





¥ Union All 


Teradata connection manager is displayed as "TERADATA". 


@ Add S825 Connection Manager 


Select the type of conmection manager to add to the package 


Connection maruger type 


type description 
f.? Connection anager fee FIP connections 
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Existing SSIS packages that have been designed with Attunity Teradata Connector will be automatically 
upgraded to use Microsoft Connector for Teradata. The icons will be changed as well. 


To execute SSIS package targeting SQL Server 2017 and below, you will need to install Microsoft Connector 
for Teradata by Attunity with corresponding version from below link: 


e SQL Server 2017: Microsoft Connector Version 5.0 for Teradata by Attunity 
e SQL Server 2016: Microsoft Connector Version 4.0 for Teradata by Attunity 
e SQL Server 2014: Microsoft Connector Version 3.0 for Teradata by Attunity 
e SQL Server 2012: Microsoft Connector Version 2.0 for Teradata by Attunity 


To design SSIS package in SSDT targeting SQL Server 2017 and below, you will need to have Microsoft 
Connector for Teradata and install Microsoft Connector for Teradata by Attunity with corresponding 
version. 


Limitations and known issues 


e Teradata Source/Destination Editor, Default database property does not take effective. As work- 
around, type database name in dropdown box to filter table or view. 


e Teradata Source/Destination Editor, Mapping step does not work when type <database>. 
<table/view>. As work-around, type <database>.<table/view>, then click the drop-down button. 


e Teradata Source Editor, view cannot be displayed when Data access mode is "Table Name — TPT Export". 
As work-around, use Advanced Editor of Teradata Source. 


e Teradata Destination, attribute ‘PackMaximum’ cannot be set to ‘True’. Otherwise, error will occur. 


Uninstallation 


You can run uninstall wizard to remove Microsoft connector for Teradata. 


Next steps 


e Configure Teradata connection manager 
e Configure Teradata source 
e Configure Teradata destination 


e If you have questions, visit Tech Community. 


Use the Teradata connection manager 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


With the Teradata connection manager, you can enable a package to extract data from Teradata databases and 
load data into Teradata databases. 


You set the Teradata connection manager ConnectionManagerType property to TERADATA. 


Configure the Teradata connection manager 


Connection manager configuration changes are resolved by Integration Services at runtime. To add a connection 
to a Teradata data source, complete the information in the Teradata Connection Manager Editor pane. 





* Teradata Connection Manager Editor x 


Connection manager information 











Name: [Teradata Connection Manager 
Description: Po” 
Server info 
Authentication 


O Use Windows Authentication 


@ Use Teradata Authentication 


Mechanism: | 
Parameter: 


User name: 
Password: 


Default database: 


Account: | 














Option 











Test Connection 








1. In the Name box, enter a name for the connection. The default name is Teradata Connection 
Manager. 


2. (Optional) In the Description box, enter a description of the connection. 
3. Inthe Server name box, enter the name of the Teradata server to connect to. 
4. Under Authentication, do either of the following: 


e To use Windows authentication, select Use Windows Authentication. 


e To use Teradata database authentication, select Use Teradata Authentication, and then enter the 
following credentials for this type of authentication: 


o Inthe Mechanism box, enter the security checking mechanism you want to use. Valid 
mechanism values include TD1, TD2, LDAP KRB5, KRB5C, NTLM, and NTLMC. 


o Inthe Parameter box, enter the types of parameters that are required for the security checking 
mechanism you've entered. 


o Inthe User name box, enter the username that you use to connect to the Teradata database. 
o Inthe Password box, enter the Teradata database password of the user. 


5. (Optional) In the Default database drop-down list, select the Teradata database to connect to. If this 
database-access permission is incorrect, an error is displayed, and you can then manually enter the 
database name. 


6. (Optional) In the Account box, enter the name of the account that corresponds to the user name. If this 
value is empty, the account for the immediate owner of the database is used. 


7. Select OK. 


Custom property 
The custom property UseUTF8CharSet specifies whether the UTF-8 character set is used. The default value is ue. 
To set the property: 


1. Open SQL Server Data Tools (SSDT). 
2. Inthe Connection Manager area, right-click Teradata Connection Manager, and then select Properties. 


3. In the Properties pane, for the UseUTF8Charset property, select either ue or False. 


Troubleshoot the Teradata connection manager 


To log Teradata connection manager calls to the Teradata Open Database Connectivity (ODBC) driver, enable 
Windows ODBC tracing in the Windows ODBC Data Source Administrator. 


Next steps 


e Configure the Teradata source. 
e Configure the Teradata destination. 


e If you have questions, visit the Tech Community. 


Connect to the Teradata source 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 
The Teradata source extracts data from Teradata databases by using: 


e Atable or a view. 


e The results of an SQL statement. 


The source uses the Teradata connection manager to connect to the Teradata source. For more information, see 
Use the Teradata connection manager. 


Troubleshoot the Teradata source 


You can log the calls that the Teradata source makes to the Teradata Parallel Transporter (TPT) API. To do so, 
enable package logging and then select the Diagnostic event at the package level. 


You can log the Open Database Connectivity (ODBC) calls that the Teradata source makes to the Teradata ODBC 
driver by enabling the ODBC driver manager trace. For more information, see How to generate an ODBC trace 
with the ODBC Data Source Administrator. 


Parallelism 


The Teradata source supports parallelism, wherein export jobs can access the same table or different tables at 
same time. A database variable called maxLoadtasks sets the limit of the number of export jobs that can run at 


the same time. You can define this maximum number by using the MaxLoadtasks variable. 


Teradata source custom properties 


The custom properties of the Teradata source are listed in the following table. All properties are read/write. 


PROPERTY NAME DATA TYPE DESCRIPTION 


AccessMode Integer (enumeration) The mode used to access the database. 
The possible values are Zable Name 
and SQL Command. The default value 
is Table Name. 


BlockSize Integer The block size, in bytes, that's used 
when returning data to the client. The 
default value is 1048576 (1 MB). The 
minimum value is 256 bytes. The 
maximum value is 16775168 bytes. 
This property is in the Advanced 
Editor pane. 


PROPERTY NAME 


BufferMaxSize 


BufferMode 


DataEncryption 


DefaultCodePage 


DetailedTracingLevel 


DetailedTracingFile 


DiscardLargeRow 


DATA TYPE 


Integer 


Boolean 


Boolean 


Integer 


Integer (enumeration) 


String 


Boolean 


DESCRIPTION 


The total maximum size of the data 
buffer returned by the GetBuffer 
function. This size must be large 
enough to hold at least one row of 
data, including the row header, the 
actual row of data, and the buffer 
trailer. The default total maximum size 
of the data buffer is 16775552 bytes. 
For more information, see Export data 
from a Teradata database by using 
GetBuffer. 


Default value is ue. The value must 
be True if the PutBuffer feature is used. 
This property is in the Advanced 
Editor pane. 


Default value is Fa/se. Full security 
encryption is used if the value is 7rue. 


The code page to use when the data 
source doesn't have code page 
information. This property is in the 
Advanced Editor pane. 


Select one of the following options for 
advanced tracing: 

Off No advanced logging. 

Generat Driver-specific activities 
general tracing is logged. 

CLI CLlv2-related activities tracing is 
logged. 

Notify Method: Notify feature-related 
activities tracing is logged. 

Common Library. opcommon library 
activities tracing is logged. 

Alt All the preceding activity tracing is 
logged. 

The advanced tracing log file is defined 
inthe DetailedTracingFile 
property. 

The DetailedTracingFile property 
must be set if the option is not Off 
This property is in the Advanced 
Editor pane. 


The path of the log file that is 
generated automatically when 
DetailedTracingLevel is not Off This 
property is in the Advanced Editor 
pane. 


Default value is Fa/se. Discard large 
rows (greater than 64 KB) if the value 
is True. 


PROPERTY NAME 


ExtendedStringColumnsAllocation 


JobMaxRowSize 


MaxSessions 


MinSessions 


QueryBandSessInfo 


SpoolMode 


SqlCommand 


TableName 


DATA TYPE 


Boolean 


Integer 


Integer 


Integer 


Varchar 


Varchar 


String 


String 


DESCRIPTION 


Maximal Transfer Character Allocation 
Factor is used if the value is ue. 
This value should be set to 7rue if the 
Teradata database 

Export Width Table ID property is 
set to Maximal Defaults. 
Default value is False. 


Maximum row size can be supported. 

This value is needed if 
DiscardLargeRow value is 7rue. 

Valid values: 

64 (default value): 2-byte row lengths 

can be supported. 

7024. 4-byte row lengths can be 

supported. 


The maximum number of sessions that 
are logged in. This value must be 
greater than one. The default value is 
one session for each available Access 
Module Processor (AMP). 


The minimum number of sessions that 
are logged in. This value must be 
greater than one. The default value is 
one session for each available AMP. 


A user-defined, session-based query 
band expression in a connection-string 
format. You use this property for 
charge-back monitoring and 
governance. This property is in the 
Advanced Editor pane. 


Valid values are: 

Spoot Use the default value Spool 
NoSpoolt Do not use Spool This value 
is valid only if the database server 
(DBS) supports NoSpool 
NoSpoolOnly. Do not use Spoo/in any 
case. The job will be terminated with 
an error if the DBS does not support 
NoSpool. 


The SQL command to be executed 
when AccessMode_ is set to SQL 
Command. 


The name of the table containing the 
data to be used when AccessMode_ is 


set to Table Name. 


PROPERTY NAME DATA TYPE 


TenacityHours Integer 
TenacitySleep Integer 
UnicodePassThrough Boolean 


Configure the Teradata source 


DESCRIPTION 


The number of hours the TPT driver 
attempts to log in when the maximum 
number of load/export operations are 
already running. The default value is 4 
hours. This property is in the 
Advanced Editor pane. 


The number of minutes the TPT driver 
pauses before attempting to log in 
when the limit is reached. The limit is 
defined by the MaxSessions and 

TenacityHours properties. Default 
value is 6 minutes. This property is in 
the Advanced Editor pane. 


Off (default value): Disable Unicode 
pass-through. 
On: Enable Unicode pass-through. 


You can configure the Teradata source programmatically or by using SQL Server Integration Services (SSIS) 


Designer. 


The Teradata Source Editor pane is shown in the following image. For more information, go to each of the 


following Teradata Source Editor sections: 


e@ The Connection Manager pane 
e The Columns pane 


e The Error Output pane 


a Teradata Source Editor 


Configure the properties used by a data flow to obtain data from any Teradata provider. 





Connection Manager Specify an Teradata connection manager, a data source, or a data source view, and select 
orem the data access mode. If using the SQL command access mode, specify the SOL command 


Error Output connection manager: 


Teradata Connection Manager v | 


Data access mode: 
Table Name - TPT Export 


Name of the table or the view: 











The Advanced Editor pane contains properties that can be set programmatically. To open the pane: 





e@ On the Data Flow page of your Integration Services project, right-click the Oracle source, and then select 
Show Advanced Editor. 


For more information about the properties that you can set in the Advanced Editor pane, see Teradata source 
custom properties. 


The Connection Manager pane 


Use the Connection Manager pane to select the Teradata connection manager instance for the source. In this 
pane, you can also select a table or a view from the database. To open the pane: 


1. In SQL Server Data Tools, open the SSIS package that contains the Teradata source. 
2. On the Data Flow tab, double-click the Teradata source. 
3. In Teradata Source Editor, select the Connection Manager tab. 


Options 


Connection manager 


e Select an existing connection manager from the list, or select New to create a new Teradata connection 
manager instance. 


New 


e Select New. The Teradata Connection Manager Editor pane opens. From this pane, you can create a new 
connection manager. 


Data Access Mode 


e Choose a method for selecting data from the source. The options are shown in the following table: 
OPTION DESCRIPTION 


Table name - TPT Export Retrieve data from a table or a view in the Teradata data 
source. When this option is selected, select an available 
table or view from the list for Name of the table or 
the view. 


SQL command - TPT Export Retrieve data from the Teradata data source by using an 
SQL query. When this option is selected, enter a query in 
one of the following ways: 

e Enter the text of the SQL query in the SQL 
command text field. 


e Select Browse to load the SQL query from a text 
file. 


e Select Parse query to verify the syntax of the 
query text. 


Preview 


e Select Preview to view up to the first 200 rows of the data that's extracted from the table or view you 
selected. 


The Columns pane 


Use the Columns pane to map an output column to each external (source) column. To open the pane: 
1. In SQL Server Data Tools, open the SSIS package that contains the Teradata source. 

2. On the Data Flow tab, double-click the Teradata source. 

3. In Teradata Source Editor, select the Columns tab. 


Options 


Available External Columns 


This table lists the available external columns that you can select to add to the External Column list. You can list 
the columns in the order you choose. You can't use this table to add or delete columns. 


e To choose all columns, select the Select All check box. 


External Columns 


The external (source) columns that you selected are listed in order. To change the order, first clear the Available 


External Column list, and then select the columns in a different order. 
Output Column 


Although the name of the selected external (source) column is the default output name, you can enter any 


unique name. 





NOTE 


If there are columns that contain unsupported data types, you'll receive a warning that displays those unsupported 
data types, and the relevant columns will be removed from the mapping columns. 











The Error Output pane 

Use the Error Output pane to select error-handling options. To open the pane: 

1. In SQL Server Data Tools, open the SSIS package that contains the Teradata source. 
2. On the Data Flow tab, double-click the Teradata source. 

3. In Teradata Source Editor, select the Error Output tab. 


Options 

Error behavior 

e Select how the Teradata source should handle errors in a flow: 
o Ignore the failure 


o Redirect the row 


o Fail the component 
Related topics: See Error handling in data. 
Truncation 


e Select how the Teradata source should handle truncation in a flow: 
o Ignore the failure 
o Redirect the row 


o Fail the component 


Next steps 


e Configure the Teradata destination. 


e If you have questions, visit the tech community. 


Teradata destination 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 
The Teradata destination bulk loads data into Teradata Database. 


The destination uses the Teradata connection manager to connect to a data source. For more information, see 
Teradata connection manager. 


Load options 
Teradata destination supports two data load modes: 
e TPT Stream: This mode uses the TPT API Stream operator (Teradata TPump protocol). 


e TPT Load (fast bulk-load): This mode uses the TPT API Load operator (Teradata FastLoad protocol) for 
fast bulk loading. 


Fast load mode has below restrictions: 
@ The limit of sessions for Teradata database is determined by whichever below factor is encountered first: 


o Session limits set using the SESSIONS command 
o The Teradata Database limit of one session per AMP 


© The platform limit on maximum number of sessions per application: Defined by MaxSess variable in 
the communications processor (COP) Interface software file, CLISPB.DAT. You can use the TDP SET 
MAXSESSIONS command to specify a platform limit. The default limit is equal to the server MAXSESS. 


@ Join indexes are not supported. 

e Foreign key references in target tables are not supported. 

e Target tables defined with a secondary index are not supported. 

For more information on the Teradata fast load restrictions, see Teradata’s fast load reference. 


You can set the mode in the Teradata Destination Editor (Connection Manager Page). 


Error handling 


Errors returned during the load process are written to temporary error tables that are locked during loading 
process. Maximum number of errors (MaxErrors) property in Advanced Editor sets the maximum number 
of errors that can be written to these tables. 


If the Maximum number of errors is greater than zero, error tables with unique names are generated, and 
informational message is printed to package log. The errors can be retrieved by standard SSIS component error 
output. 


The temporary tables are dropped once the loading process is completed. If the temporal tables cannot be read 
by Teradata destination, they are not dropped unless Always drop error table property is checked. If the 
loading process is stopped before completion, you need to manually drop these tables if needed. These tables 
are located in the same database with the destination table. 


When the Maximum number of errors is reached, the target table state depends on the mode being used. 


e In fast load mode, the target table is not usable. To execute again, you must truncate or drop and recreate the 
target table. Rollback is not supported. 

e In TPT Steam operator mode, Teradata destination executes via buffered row mechanism. If job fails, all the 
changes that were completed (buffers were sent) at the time of failure are permanent in target table(s). There 
is no rollback concept. Error tables will be dropped. 


The Teradata destination has an error output. For more information, see Teradata Destination Editor (Error 
Output Page). 


Parallelism 


Parallelism is restricted in fast load mode, multiple independent fast load jobs cannot access the same table at 
the same time. Also the number of concurrent fast load jobs is limited by database variable MaxLoadTasks. 


There is no restriction of parallelism in TPT Stream mode. It is possible to run multiple Teradata destinations 
concurrently against the same table, while this may reduce the performance per Teradata. See Teradata 


documentation for more information. 


Troubleshooting the Teradata destination 


You can log the calls that the Teradata source makes to the Teradata Parallel Transporter API (TPT API). You can 
enable package logging and select the Diagnostic event at the package level to log the calls. 


You can log the ODBC calls that the Teradada source makes to the Teradata ODBC driver by enabling the ODBC 
driver manager trace. For more information, see the Microsoft documentation on How To Generate an ODBC 
Trace with ODBC the Data Source Administrator. 


Teradata destination custom properties 


The following table describes the custom properties of the Teradata destination. All properties are read/write. 


PROPERTY NAME DATA TYPE DESCRIPTION 

AlwaysDropErrorTable Boolean Default is False. Drop all error tables if 
True, even if the Teradata destination 
fails read. 

ArraySupport Boolean Default is True. DML Groups use 


ArraySupport if True. Only applicable 
for TPT Stream. This property is in 
Advanced Editor. 


Buffers Integer The number of request buffers to be 
increased, value can be set from 2 to 
64. Only applicable for TPT Stream. 
This property is in Advanced Editor. 


BufferMode Boolean Default is True. Must be True if 
PutBuffer feature is used. This property 
is in Advanced Editor. 


BufferSize Integer The output buffer size (in KB) used for 
sending load parcels. The default value 
is 1024. Only applicable for TPT Load. 
This property is in Advanced Editor. 


PROPERTY NAME 


DataEncryption 


DefaultCodePage 


DetailedTracingLevel 


DetailedTracingFile 


DiscardLargeRow 


ErrorTableName 


ExtendedStringColumnsAllocation 


FastLoad 


DATA TYPE 


Boolean 


Integer 


Integer (Enumeration) 


String 


Boolean 


String 


Boolean 


Boolean 


DESCRIPTION 


Default is False. Full security 
encryption is used if True. 


The code page to use when data 
source does not have code page 
information. 

Note: This property is in Advanced 
Editor. 


Select one of the following options for 
advanced tracing: 

Off: No advanced logging. 

General: Driver-specific activities 
general tracing is logged. 

CLI: CLlv2-related activities tracing is 
logged. 

Notify Method: Notify feature- 
related activities tracing is logged. 
Common Library: opcommon library 
activities tracing is logged. 

All: All of the above activities tracing is 
logged. 

The advanced tracing log file is defined 
in the DetailedTracingFile property. 
DetailedTracingFile property must 
be set if option is not Off 

This property is in Advanced Editor. 


The path of log file that is generated 
automatically when 
DetailedTracingLevel is not Off. This 
property is in Advanced Editor. 


Default is False. Discard large rows 
(greater than 64K) if True 


Error table name. Default is the target 
table name 


Maximal Transfer Character 
Allocation Factor is use if True. 
This value should be set to True if the 
Teradata database Export Width 
Table ID property is set to Maximal 
Defaults. 

Default is False. 


Fast Loading is used if True. The 
default value is false. This can also be 
set in the Teradata Destination Editor 
(Connection Manager Page). 


PROPERTY NAME 


MaxErrors 


MaxSessions 


MinSessions 


Pack 


PackMaximum 


QueryBandSessInfo 


ReplicationOveride 


Robust 


DATA TYPE 


Integer 


Integer 


Integer 


Integer 


Boolean 


Varchar 


Integer (enumeration) 


Boolean 


DESCRIPTION 


The number of errors that can occur 
before the data flow is stopped. The 
default value is 0, which means no 
limit of error number. 

If Redirect flow is selected in the 
Error handling page. Before the error 
number limit reaches, all errors are 
returned in the error output. For more 
information, see Teradata Destination 
Editor (Error Output Page). 


The maximum number of sessions that 
are logged on. This value must be 
greater than one. The default value is 
one session for each available AMP. 


The minimum number of sessions that 
are logged on. This value must be 
greater than one. The default value is 
one session for each available AMP. 


The number of statements to pack into 
a multi-statement request. Default is 
20, maximum allowed is 2400. Only 
applicable for TPT Stream. This 
property is in Advanced Editor. 


Dynamically determine the maximum 
pack factor for the current Stream job 
if True. Only applicable for TPT Stream. 
This property is in Advanced Editor. 


A user defined, session-based query 
band expression, to enable charge- 
back monitoring and governance. This 
property must be in connection-string 
format. This property is in Advanced 
Editor. 


Options: 

Default: No SET SESSION OVERRIDE 
REPLICATION statement is sent to the 
database. The database default 
settings are used. 

On: The normal replication service 
controls are overridden. 

Off: The normal replication service 
controls are used. 

This property is only applicable for TPT 
Stream. 

This property is in Advanced Editor. 


Robust restart logic is used for 
recovery and restart operations if 
True. This property is only applicable 
for TPT Stream. This property is in 
Advanced Editor. 


PROPERTY NAME DATA TYPE 


TableName String 

TenacityHours Integer 
TenacitySleep Integer 
UnicodePassThrough Boolean 


Configuring the Teradata destination 


DESCRIPTION 


The name of the table with the data 
that is being used. 


The number of hours the TPT driver 
attempts to log on when the 
maximum number of load/export 
operations are already running. The 
default is 4 hours. This property is in 
Advanced Editor 


Minutes the TPT driver pauses before 
attempting to log on when limit is 
reached. Limit is defined by the 
MaxSessions and TenacityHours 
properties. Default is six minutes. This 
property is in Advanced Editor 


Off (default): Disable the Unicode Pass 
Through. 
On: Enable the Unicode Pass Through. 


Teradata destination can be configured programmatically or through the SSIS Designer. 


The Teradata Destination Editor is shown in below picture. It contains Connection Manager Page, Mappings Page, 


and Error Output Page. 
For more information, see one of the following topics: 


e Teradata Destination Editor (Connection Manager Page) 
e Teradata Destination Editor (Mappings Page) 
e Teradata Destination Editor (Error Output Page) 


a Teradata Destination Editor 


Configure the properties used to insert data into a relational database using Teradata provider. 





Connection Manager Specify an Teradata connection manager, a data source, or a data source view, and select 


3 the data access mode. 
Mappings 


sasmalis ta connection manager: 


Teradata Connection Manager v | 


Data access mode: 
Table Name - TPT Load 


Name of the table or the view: 


L] Data encryption (_] Always drop error table 





Error table 








Minimum number of sessions 








Maximum number of sessions 














Maximum number of errors 





Preview... 


| A Map the columns on the Mappings page. 
He 














The Advanced Editor dialog box contains the properties that can be set programmatically. To open the 
Advanced Editor dialog box: 


e Inthe Data Flow screen of your Integration Services project, right click the Teradata destination and select 
Show Advanced Editor. 


For more information about the properties that you can set in the Advanced Editor dialog box, see Teradata 
destination custom properties. 


Teradata Destination Editor (Connection Manager Page) 


Use the Connection Manager page of the Teradata Destination Editor dialog box to select the Teradata 
connection manager for the destination. This page also lets you select a table or view from the database. 


To open the Teradata Destination Editor Connection Manager Page 


e@ In SQL Server Data Tools, open the SQL Server Integration Services (SSIS) package that has the Teradata 
destination. 


e@ On the Data Flow tab, double-click the Teradata destination. 
e Inthe Teradata Destination Editor, click Connection Manager. 


Options 


Connection manager 


Select an existing connection manager from the list, or click New to create a new Teradata connection manager. 


New 


Click New. The Teradata Connection Manager Editor dialog box opens where you can create a new 


connection manager. 
Data access mode 


Select the method for selecting data from the source. The options are shown in the following table: 
OPTION DESCRIPTION 


Table Name - TPT Stream Incremental mode using the TPT Stream operator. 
Name of the table or the vie: Select an existing table or 
view from the list. This list only shows the first 1000 tables. 
You can type table name prefix or use any part of the name 
with the (*) wildcard to list the table or tables you want to 
use. 


Table Name — TPL Load Fast (Direct Path) load mode using the TPT API Load 
operator (Teradata FastLoad protocol), which requires target 
table to be empty. 

Name of the table or the view: Select an existing table 
or view from the list. This list only shows the first 1000 
tables. You can type table name prefix or use any part of the 
name with the (*) wildcard to list the table or tables you 
want to use. 

Data encryption Check box to enable data encryption. Default is not selected. 

Always drop error table Check box to drop error tables in all instances. 


Error table Name of the table that errors are written to. 


Minimum number of sessions The minimum number of sessions that are logged on. The default value is one 


session for each available AMP. The value must be greater than one. 


Maximum number of sessions The maximum number of sessions that are logged on. The default value is 


one session for each available AMP. The value must be greater than one. 


Maximum number of errors The maximum number of errors that can be returned before the data flow is 


stopped or redirected. 


Teradata Destination Editor (Mappings Page) 


Use the Mappings page of the Teradata Destination Editor dialog box to map input columns to destination 


columns. 
To open the Teradata Destination Editor Mappings Page 


e In SQL Server Data Tools, open the SQL Server Integration Services (SSIS) package that has the Teradata 


destination. 
e On the Data Flow tab, double-click the Teradata destination. 
e Inthe Teradata Destination Editor, click Mappings. 


Options 


Available Input Columns 


The list of available input columns. Drag-and-drop an input column to an available destination column to map 


the columns. 


Available Destination Columns 


The list of available destination columns. Drag-and-drop a destination column to an available input column to 
map the columns. 


Input Column 


View the input columns that you selected. You can remove mappings by selecting < ignore > to exclude 
columns from the output. 


Destination Column 


View all available destination columns, both mapped and unmapped. 





NOTE 


Columns of unsupported data types will be deleted from mapping with a warning. 











Teradata Destination Editor (Error Output Page) 
Use the Error Output page of the Teradata Destination Editor dialog box to select error handling options. 
To open the Teradata Destination Editor Error Output Page 


e@ In SQL Server Data Tools, open the SQL Server Integration Services (SSIS) package that has the Teradata 
destination. 


e@ On the Data Flow tab, double-click the Teradata destination. 
e Inthe Teradata Destination Editor, click Error Output. 


Options 


Error behavior 


Select how the Teradata destination should handle errors in a flow: ignore the failure, redirect the row, or fail the 
component. 


Related Topics: Error Handing in Data 
Truncation 


Select how the Teradata destination should handle truncation in a flow: ignore the failure, redirect the row, or fail 
the component. 


Next steps 


e Configure Teradata connection manager 
e Configure Teradata source 
e Configure Teradata destination 


e If you have questions, visit Tech Community. 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


SSIS components use Teradata Parallel Transporter API (TPT API) to load and transfer data from and to Teradata 
Database, thus only TPT API supported data type can be used in SSIS. 





NOTE 


TIME, TIMESTAMP and INTERVAL data types in Teradata are handled by TPT API as fixed-sized character strings. They are 
handled by the SSIS components for Teradata as a string. 








Data type mapping 


The following table shows the Teradata database data types and their default mapping to SSIS data types. It also 
shows the unsupported Teradata data types. 


SQL DATA TYPE SSIS DATA TYPE 
DECIMAL/NUMERIC DT_NUMERIC 
BYTEINT DT_I1 
SMALLINT DT_I2 

INTEGER DT_l4 
FLOAT/REAL/DOUBLE PRECISION DT_R8 

DATE DT_DBDATE 
TIME DT_STR 

TIME(n) 

TIMESTAMP DT_STR 


TIMESTAMP (n) 


TIME WITH TIMEZONE DT_STR 
TIME(n) WITH TIMEZONE 


TIMESTAMP WITH TIMEZONE DT_STR 
TIMESTAMP(n) WITH TIMEZONE 


INTERVAL YEAR DT_STR 
INTERVAL YEAR (n) 
INTERVAL YEAR TO MONTH DT_STR 


INTERVAL YEAR (n) TO MONTH 


SQL DATA TYPE 


INTERVAL MONTH 
INTERVAL MONTH (n) 


INTERVAL DAY 
INTERVAL DAY (n) 


INTERVAL DAY TO HOUR 
INTERVAL DAY (n) TO HOUR 


INTERVAL DAY TO MINUTE 
INTERVAL DAY (n) TO MINUTE 


INTERVAL DAY TO SECOND 
INTERVAL DAY (n) TO SECOND 
INTERVAL DAY TO SECOND (m) 
INTERVAL DAY (n) TO SECOND (m) 


INTERVAL HOUR 
INTERVAL HOUR (n) 


INTERVAL HOUR TO MINUTE 
INTERVAL HOUR (n) TO MINUTE 


INTERVAL HOUR TO SECOND 
INTERVAL HOUR (n) TO SECOND 
INTERVAL HOUR TO SECOND (m) 
INTERVAL HOUR (n) TO SECOND (m) 


INTERVAL MINUTE 
INTERVAL MINUTE (n) 


INTERVAL MINUTE TO SECOND 
INTERVAL MINUTE (n) TO SECOND 
INTERVAL MINUTE TO SECOND (m) 
INTERVAL MINUTE (n) TO SECOND (m) 


INTERVAL SECOND 
INTERVAL SECOND (n) 
INTERVAL SECOND (n,m) 


PERIOD(DATE) 


PERIOD(TIME) 


NUMBER 


CHARACTER 


VARCHAR 


SSIS DATA TYPE 


DT_STR 


DT_STR 


DT_STR 


DT_STR 


DT_STR 


DT_STR 


DT_STR 


DT_STR 


DT_STR 


DT_STR 


DT_STR 


DT_STR 


DT_STR 


DT_STR 


DT_STR 


DT_STR (DT_WSTR for Unicode character set) 

Notes: 

Maximum length of VARCHAR supported is 32000. 
Maximum allowed length of DT_STR is 8000 characters, 
DT_WSTR is 4000 characters. Data is truncated if exceeds. 


SQL DATA TYPE SSIS DATA TYPE 


LONG VARCHAR Not supported 
CLOB Not supported 
BYTE DT_BYTES 


Note: Maximum allowed length is 8000 bytes. Data is 
truncated if exceeds. 


VARBYTE DT_BYTES 
Note: Maximum allowed length is 8000 bytes. Data is 
truncated if exceeds. 


BLOB Not supported 


Next steps 


Configure Teradata connection manager 


Configure Teradata source 


Configure Teradata destination 


If you have questions, visit Tech Community. 


Microsoft Connectors for Oracle and Teradata by 


Attunity for Integration Services (SSIS) 
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Applies to: Q sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


NOTE 
Atunity Connectors for Oracle and Teradata support SQL Server 2017 and below. 


From SQL Server 2019, get latest connectors for Oracle and Teradata here: 


® Microsoft connector for Oracle 


© Microsoft connector for Teradata 











You can download connectors for Integration Services by Attunity that optimize performance when loading data 
to or from Oracle or Teradata in an SSIS package. 


Download the latest Attunity connectors 


Get the latest version of the connectors here: 
Microsoft Connectors v5.0 for Oracle and Teradata 


Issue - The Attunity connectors aren't visible in the SSIS Toolbox 


To see the Attunity connectors in the SSIS Toolbox, you always have to install the version of the connectors that 
targets the same version of SQL Server as the version of SQL Server Data Tools (SSDT) installed on your 
computer. (You may also have earlier versions of the connectors installed.) This requirement is independent of 
the version of SQL Server that you want to target in your SSIS projects and packages. 


For example, if you've installed the latest version of SSDT, you have version 17 of SSDT with a build number that 
starts with 14. This version of SSDT adds support for SQL Server 2017. To see and use the Attunity connectors in 
SSIS package development - even if you want to target an earlier version of SQL Server - you also have to install 
the latest version of the Attunity connectors, version 5.0. This version of the connectors also adds support for 
SQL Server 2017. 


Check the installed version of SSDT in Visual Studio from Help | About Microsoft Visual Studio, or in 
Programs and Features in the Control Panel. Then install the corresponding version of the Attunity 
connectors from the following table. 


TARGET SQL SERVER REQUIRED VERSION OF 
SSDT VERSION SSDT BUILD NUMBER VERSION CONNECTORS 
17 Starts with 14 SQL Server 2017 Microsoft Connectors v5.0 


for Oracle and Teradata 


16 Starts with 13 SQL Server 2016 Microsoft Connectors v4.0 
for Oracle and Teradata 


Download the latest SQL Server Data Tools (SSDT) 


Get the latest version of SSDT here: 
Download SQL Server Data Tools (SSDT) 


Import and Export Data with the SQL Server 


Import and Export Wizard 
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Applies to: Q sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


SQL Server Import and Export Wizard is a simple way to copy data from a source to a destination. This overview 
describes the data sources that the wizard can use as sources and destinations, as well as the permissions you 
need to run the wizard. 


Get the wizard 


If you want to run the wizard, but you don't have Microsoft SQL Server installed on your computer, you can 
install the SQL Server Import and Export Wizard by installing SQL Server Data Tools (SSDT). For more info, see 
Download SQL Server Data Tools (SSDT). 


What happens when | run the wizard? 


e See the list of steps. For a description of the steps in the wizard, see Steps in the SQL Server Import and 
Export Wizard. There's also a separate page of documentation for each page of the wizard. 
-or- 

e See an example. For a quick look at the several screens you see in a typical session, take a look at this 
simple example on a single page - Get started with this simple example of the Import and Export Wizard. 


What sources and destinations can | use? 


The SQL Server Import and Export Wizard can copy data to and from the data sources listed in the following 
table. To connect to some of these data sources, you may have to download and install additional files. 


DATA SOURCE DO | HAVE TO DOWNLOAD ADDITIONAL FILES? 


DATA SOURCE 


Enterprise databases 
SQL Server, Oracle, DB2, and others. 


Text files (flat files) 


Microsoft Excel and Microsoft Access files 


Azure data sources 
Currently only Azure Blob Storage. 


Open source databases 
PostgreSQL, MySql, and others. 


DO | HAVE TO DOWNLOAD ADDITIONAL FILES? 


SQL Server or SQL Server Data Tools (SSDT) installs the files 
that you need to connect to SQL Server. But SSDT doesn't 
install all the files that you need to connect to other 
enterprise databases such as Oracle or IBM DB2. 


To connect to an enterprise database, you typically have to 
have two things: 


1. Client software. If you already have the client software 
installed for your enterprise database system, then you 
typically have what you need to make a connection. If you 
don't have the client software installed, ask the database 
administrator how to install a licensed copy. 


2. Drivers or providers. Microsoft installs drivers and 
providers to connect to Oracle. To connect to IBM DB2, get 
the MicrosoftA@®) OLEDB Provider for DB2 v5.0 for 
Microsoft SQL Server from the Microsoft SQL Server 2016 
Feature Pack. 


For more info, see Connect to a SQL Server Data Source or 
Connect to an Oracle Data Source. 


No additional files required. 


For more info, see Connect to a Flat File Data Source. 


Microsoft Office doesn't install all the files that you need to 
connect to Excel and Access files as data sources. Get the 
following download - Microsoft Access Database Engine 
2016 Redistributable. 


For more info, see Connect to an Excel Data Source or 
Connect to an Access Data Source. 


SQL Server Data Tools don't install the files that you need to 
connect to Azure Blob Storage as a data source. Get the 
following download - Microsoft SQL Server 2016 Integration 
Services Feature Pack for Azure. 


For more info, see Connect to Azure Blob Storage. 


To connect to these data sources, you have to download 
additional files. 


- For PostgreSQL, see Connect to a PostgreSQL Data 
Source. 
- For MySql, see Connect to a MySQL Data Source. 


DATA SOURCE 


Any other data source for which a driver or provider 
is available 


How do | connect to my data? 


DO | HAVE TO DOWNLOAD ADDITIONAL FILES? 


You typically have to download additional files to connect to 
the following types of data sources. 


- Any source for which an ODBC driver is available. For 
more info, see Connect to an ODBC Data Source. 

- Any source for which a.Net Framework Data Provider 
is available. 

- Any source for which an OLE DB Provider is available. 


Third-party components that provide source and destination 
capabilities for other data sources are sometimes marketed 
as add-on products for SQL Server Integration Services 
(SSIS). 


For info about how to connect to a commonly used data source, see one of the following pages: 


® Connect to SQL Server 

e Connect to Oracle 

e Connect to flat files (text files) 
e Connect to Excel 

e Connect to Access 

e Connect to Azure Blob Storage 
e Connect with ODBC 

e Connect to PostgreSQL 

e Connect to MySQL 


For info about how to connect to a data source that's not listed here, see The Connection Strings Reference. This 


third-party site contains sample connection strings and more info about data providers and the connection info 


they require. 


What permissions do | need? 


To run the SQL Server Import and Export Wizard successfully, you have to have at least the following 


permissions. If you already work with your data source and destination, you probably already have the 


permissions that you need. 


YOU NEED PERMISSIONS TO DO THESE THINGS 


Connect to the source and destination databases or file 
shares. 


Export or read data from the source database or file. 


Import or write data to the destination database or file. 


Create the destination database or file, if applicable. 


Save the SSIS package created by the wizard, if applicable. 


IF YOU'RE CONNECTING TO SQL SERVER, YOU NEED THESE 
SPECIFIC PERMISSIONS 


Server and database login rights. 


SELECT permissions on the source tables and views. 


INSERT permissions on the destination tables. 


CREATE DATABASE or CREATE TABLE permissions. 


If you want to save the package to SQL Server, permissions 
sufficient to save the package to the msdb database. 


Get help while the wizard is running 





TIP 


Tap the F1 key from any page or dialog box of the wizard to see documentation for the current page. 





The wizard uses SQL Server Integration Services (SSIS) 


The wizard uses SQL Server Integration Services (SSIS) to copy data. SSIS is a tool for extracting, transforming, 
and loading data (ETL). The pages of the wizard use some of the language of SSIS. 


In SSIS, the basic unit is the package. The wizard creates an SSIS package in memory as you move through the 
pages of the wizard and specify options. 


At the end of the wizard, if you have SQL Server Standard Edition or higher installed, you can optionally save the 
SSIS package. Later you can reuse the package and extend it by using SSIS Designer to add tasks, 
transformations, and event-driven logic. The SQL Server Import and Export Wizard is the simplest way to create 
a basic Integration Services package that copies data from a source to a destination. 


For more info about SSIS, see SQL Server Integration Services. 


What's next? 


Start the wizard. For more info, see Start the SQL Server Import and Export Wizard. 


See also 


Get started with this simple example of the Import and Export Wizard 
Data Type Mapping in the SQL Server Import and Export Wizard 


Get started with this simple example of the Import 


and Export Wizard 
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Applies to: Q sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Learn what to expect in the SQL Server Import and Export Wizard by walking through a common scenario - 
importing data from an Excel spreadsheet to a SQL Server database. Even if you plan to use a different source 
and a different destination, this topic shows you most of what you need to know about running the wizard. 


Prerequisite - Is the wizard installed on your computer? 


If you want to run the wizard, but you don't have Microsoft SQL Server installed on your computer, you can 
install the SQL Server Import and Export Wizard by installing SQL Server Data Tools (SSDT). For more info, see 
Download SQL Server Data Tools (SSDT). 


Here's the Excel source data for this example 


Here's the source data that you're going to copy - a small two-column table in the WizardWalkthrough 
worksheet of the WizardWalkthrough.xlsx Excel workbook. 
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Here's the SQL Server destination database for this example 


Here (in SQL Server Management Studio) is the SQL Server destination database to which you're going to copy 
the source data. The destination table isn't there - you're going to let the wizard create the table for you. 


i Microsoft SQL Server Management Studio 
File Edit View Debug Tools Window 
£@-0|®@-o-o | DNwa 
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Step 1 - Start the wizard 


You start the wizard from the Microsoft SQL Server 2016 group on the Windows Start menu. 


Microsoft SQL Server 2016 


Te Deployment Wizard 


SQL Server 2016 Error and Usag... 


SQL Server 2016 Import and Export Data (32-bit) 


& SQL Server wre Import and Exp... 


& SQL Server 2016 Import and Exp... 








NOTE 


For this example, you pick the 32-bit wizard because you have the 32-bit version of Microsoft Office installed. As a result, 
you have to use the 32-bit data provider to connect to Excel. For many other data sources, you can typically pick the 64- 
bit wizard. 


To use the 64-bit version of the SQL Server Import and Export Wizard, you have to install SQL Server. SQL Server Data 
Tools (SSDT) and SQL Server Management Studio (SSMS) are 32-bit applications and only install 32-bit files, including the 
32-bit version of the wizard. 











For more info, see Start the SQL Server Import and Export Wizard. 


Step 2 - View the Welcome page 


The first page of the wizard is the Welcome page. 


You probably don't want to see this page again, so go ahead and click Do not show this starting page again. 





Welcome to SQL Server |mportand Export 
Wizard 


This wizard helps you to create simple packages that import and export data 
between many popular data formats including databases, spreadsheets, and text 
files. The wizard can also create the destination database and the tables into which 


the data is inserted 
1. To move or copy databases and their objects from one server instance to another, 
cancel this wizard and use the Copy Database Wizard instead. The Copy Database 
ji “ Wizard is available in SQL Server Management Studio. 


eo. 


T~ Do not show this starting page again. 





Help < Back Next > 











Step 3 - Pick Excel as your data source 


On the next page, Choose a Data Source, you pick Microsoft Excel as your data source. Then you browse to 
pick the Excel file. Finally you specify the Excel version that you used to create the file. 


IMPORTANT 


For detailed info about connecting to Excel files, and about limitations and known issues for loading data from or to Excel 
files, see Load data from or to Excel with SQL Server Integration Services (SSIS). 





Choose a Data Source PS 
Select the source from which to copy data. i 





Data source: [ae Microsoft Excel os | 


Excel connection settings 





Excel file path: 


[D\Wizard Walkthrough \WizardWalkthrough xisx Browse... | 


Excel version: 


Microsoft Excel 2013 ¥ 


IV First row has column names 




















Help < Back |[__Net> | Finish >>| | Cancel | 





For more info about this page of the wizard, see Choose a Data Source. 


Step 4 - Pick SQL Server as your destination 


On the next page, Choose a Destination, you pick Microsoft SQL Server as your destination by picking one of 
the data providers in the list that connects to SQL Server. In this example, you pick the .Net Framework Data 
Provider for SQL Server. 


The page displays a list of provider properties. Many of these are unfriendly names and unfamiliar settings. 
Fortunately, to connect to any enterprise database, you typically have to provide only three pieces of 
information. You can ignore the default values for the other settings. 


-NET FRAMEWORK DATA PROVIDER FOR SQL SERVER 


REQUIRED INFO PROPERTY 
Server name Data Source 
Authentication (login) info Integrated Security; or User ID and Password 


If you want to see a dropdown list of databases on the 
server, you first have to provide valid login info. 


Database name Initial Catalog 


Choose a Destination 
Specify where to copy data to. 


b ut 














211 |S) 
|v Security 
Authentication Not Specified 








Persist Security Info False 
TrustServerCertificate False 
User ID 

v Source 
AttachDbFilename 





User Instance False 








Integrated Security 
Whether the connection is to be a secure connection or not. 




















Help < Back [Next>] Finish >> | Cancel | 


For more info about connecting to SQL Server, see Connect to a SQL Server Data Source. For more info about 
this page of the wizard, see Choose a Destination. 


Step 5 - Copy a table instead of writing a query 


On the next page, Specify Table Copy or Query, you specify that you want to copy the entire table of source 
data. You don't want to write a query in the SQL language to select the data to copy. 









Specify whether to copy one or more tables and views or to copy the results of a query from the data 
source. 


Specify Table Copy or Query R 





Copy data from one or more tables or views 
Use this option to copy all the data from the existing tables or views in the source database. 


© Write a query to specify the data to transfer 
Use this option to write an SQL query to manipulate or to restrict the source data for the copy operation. 








For more info about this page of the wizard, see Specify Table Copy or Query. 


Step 6 - Pick the table to copy 


On the next page, Select Source Tables and Views, you pick the table or tables that you want to copy from 
the data source. Then you map each selected source table to a new or existing destination table. 


In this example, by default the wizard has mapped the WizardWalkthrough$ worksheet in the Source column 
to a new table with the same name at the SQL Server destination. (The Excel workbook only contains a single 
worksheet.) 


e The dollar sign ($) on the name of the source table indicates an Excel worksheet. (A named range in Excel is 
represented by its name alone.) 


e The starburst on the destination table icon indicates that the wizard is going to create a new destination table. 


Select Source Tables and Views 
Choose one or more tables and views to copy. 





Tables and views: 
Source: D:\WizardWalkthrough\WizardWalkthrough.... | Destination: localhost 











You probably want to remove the dollar sign ($) from the name of the new destination table. 





Select Source Tables and Views ; 
Choose one or more tables and views to copy. i 


6? 











For more info about this page of the wizard, see Select Source Tables and Views. 


Optional step 7 - Review the column mappings 


Before you leave the Select Source Tables and Views page, optionally click the Edit Mappings button to 


open the Column Mappings dialog box. Here, in the Mappings table, you see how the wizard is going to map 


columns in the source worksheet to columns in the new destination table. 





Source: “WizardWalkthroughS® 
Destination: “dbo”."WizardWalkthrough” 


(© Create destination table Edit SQL... | 


© Delete rows in destination table |” Drop and re-create destination table 
(© Append rows to the destination table [7 Enable identity insert 





Source column: ID Double (15) 











For more info about this page of the wizard, see Column Mappings. 


Optional step 8 - Review the CREATE TABLE statement 


While the Column Mappings dialog box is open, optionally click the Edit SQL button to open the Create 
Table SQL Statement dialog box. Here you see the CREATE TABLE statement generated by the wizard to 
create the new destination table. Typically you don't have to change the statement. 


You can customize the default CREATE TABLE statement. However, after you 
have customized the statement, yf must manually maintain any subsequent 
changes to the column mappings MS editing the statement. 











For more info about this page of the wizard, see Create Table SQL Statement. 


Optional step 9 - Preview the data to copy 


After you click OK to close the Create Table SQL Statement dialog box, then click OK again to close the 
Column Mappings dialog box, you're back on the Select Source Tables and Views page. Optionally click 
the Preview button to see a sample of the data that the wizard is going to copy. In this example, it looks OK. 





Source: SELECT * FROM ‘WizardWalkthrough$” 








For more info about this page of the wizard, see Preview Data. 


Step 10 - Yes, you want to run the import-export operation 


On the next page, Save and Run Package, you leave Run immediately enabled to copy the data as soon as 
you click Finish on the next page. Or you can skip the next page by clicking Finish on the Save and Run 
Package page. 





Save and Run Package 
Indicate whether to save the SSIS package. 





IV Run immediately 


[~ Save SSIS Package 
@ SQL Server 


© File system 


Package protection level: 


[Encrypt sensitive data with user key 7 | 








Help < Back |[__Net> | Finish >>I_| Cancel | 








For more info about this page of the wizard, see Save and Run Package. 


Step 11 - Finish the wizard and run the import-export operation 


If you clicked Next instead of Finish on the Save and Run Package page, then on the next page, Complete 


the Wizard, you see a summary of what the wizard is going to do. Click Finish to run the import-export 


operation. 





Complete the Wizard 
wz Verify the choices made in the wizard and click Finish. 





{Click Finish to perform the following actions: 












Source Location : D:\WizardWalkthrough\WizardWalkthrough xlsx 
Source Provider : Microsoft. ACE.OLEDB.15.0 
Destination Location : localhost 


© Copy rows from “WizardWalkthrough$" to “dbo".""WizardWalkthrough” 
The new target table will be created. 


* — The package will not be saved. 
le ~—- The package will be run immediately. 


Provider mapping file : C:\Program Files &86)\\Microsoft SQL Server\130\DTS\MappingFiles Jet ToMSSq/9 xml 








Help < Back | Next > [Finish | Cancel | 





For more info about this page of the wizard, see Complete the Wizard. 


Step 12 - Review what the wizard did 


On the final page, watch as the wizard finishes each task, then review the results. The highlighted line indicates 
that the wizard copied your data successfully. You're finished! 


The execution was successful v 





@ 11 Total 0 Error 
11 Success 0 Warning 


Details: 














@ Initializing Data Flow Task Ss 
@ Initializing Connections Success 
@ Setting SQL Command Success 
@ Setting Source Connection Success 
@ Setting Destination Connection Success 
@ Validating Success 
@ Prepare for Execute Success 
@ Pre-execute Success 
2 Executinc Success 


| ® Copying to “dbo”. "WizardWalkthrough” Success _ 3 rows transferred 











For more info about this page of the wizard, see Performing Operation. 


Here's the new table of data copied to SQL Server 


Here (in SQL Server Management Studio) you see the new destination table that the wizard created in SQL 


Server. 


en Microsoft SOL Server Management Studio 
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See dbo. WizardWalkthrough 
=] Columns 


[2] ID (float, null) 

[2] Name (nvarchar(255), null) 
[ay Keys 
Constraints 





Here (again in SSMS) you see the data that the wizard copied to SQL Server. 











Learn more 


Learn more about how the wizard works. 


e Learn more about the wizard. If you're looking for an overview of the wizard, see Import and Export 
Data with the SQL Server Import and Export Wizard. 


e Learn about the steps in the wizard. If you're looking for info about the steps in the wizard, select the 
page you want from the list here - Steps in the SQL Server Import and Export Wizard. There's also a 
separate page of documentation for each page of the wizard. 


e Learn how to connect to data sources and destinations. If you're looking for info about how to 
connect to your data, select the page you want from the list here - Connect to data sources with the SQL 
Server Import and Export Wizard. There's a separate page of documentation for each of several 
commonly used data sources. 


e Learn more about loading data from and to Excel. If you're looking for info about connecting to 
Excel files, and about limitations and known issues for loading data from or to Excel files, see Load data 
from or to Excel with SQL Server Integration Services (SSIS). 


Start the SQL Server Import and Export Wizard 
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Applies to: Q@ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Start the SQL Server Import and Export Wizard in one of the ways that is described in this topic to import data 
from and export data to any supported data source. 





IMPORTANT 


This topic describes only how to start the wizard. If you're looking for something else, see Related tasks and content. 











You can start the wizard: 


e@ From the Start menu. 

e From the command prompt. 

e From SQL Server Management Studio (SSMS). 

e From Visual Studio with SQL Server Data Tools (SSDT). 


Prerequisite - Is the wizard installed on your computer? 


If you want to run the wizard, but you don't have Microsoft SQL Server installed on your computer, you can 
install the SQL Server Import and Export Wizard by installing SQL Server Data Tools (SSDT). For more info, see 
Download SQL Server Data Tools (SSDT). 


NOTE 


To use the 64-bit version of the SQL Server Import and Export Wizard, you have to install SQL Server. SQL Server Data 
Tools (SSDT) and SQL Server Management Studio (SSMS) are 32-bit applications and only install 32-bit files, including the 
32-bit version of the wizard. 











Start menu 


Start the SQL Server Import and Export Wizard from the Start menu 
1. On the Start menu, find and expand Microsoft SQL Server 20xx. 


2. Click one of the following options. 


e SQL Server 20xx Import and Export Data (64-bit) 
e SQL Server 20xx Import and Export Data (32-bit) 


Run the 64-bit version of the wizard unless you know that your data source requires a 32-bit data 
provider. 


a Veet geyso) taps @] MSY= at7=) a0 


SQL Server 2017 Data Quality Client 


lic} SQL Server 2017 Data Quality Serv... 


fs] SQL Server 2017 Error and Usage R... 


SQL Server 2017 Import and Export Data (64-bit) 


SQL Server 2017 Import and Expo... 


Command prompt 





Start the SQL Server Import and Export Wizard from the command prompt 


In a Command Prompt window, run DTSWizard.exe from one of the following locations. 
e C:\Program Files\Microsoft SQL Server\140\DTS\Binn for the 64-bit version. 


o 740 = SQL Server 2017. This value depends on the version of SQL Server you have. 
e C:\Program Files (x86)\Microsoft SQL Server\140\DTS\Binn for the 32-bit version. 


o 740 = SQL Server 2017. This value depends on the version of SQL Server you have. 


Run the 64-bit version of the wizard unless you know that your data source requires a 32-bit data provider. 





GE Administrator: Command Prompt aa LJ x 
D:\Program Files\Microsoft SQL Server\140\DTS\Binn>dtswizard 








SQL Server Management Studio (SSMS) 


Start the SQL Server Import and Export Wizard from SQL Server Management Studio (SSMS) 


1. In SQL Server Management Studio, connect to an instance of the SQL Server Database Engine. 
2. Expand Databases. 
3. Right-click a database. 
4. Point to Tasks. 
5. Click one of the following options. 
e Import Data 


e Export Data 


ane | Server New Query 
H Ga Replice Script Database as » 



















Detach... 





Take Offline 


Bring Online 

Stretch » 
Encrypt Columns... 

Shrink > 


Back Up... 
Restore > 





Mirror 
Launch Database Mirroring Monitor 
Ship Transaction Logs... 


Generate Scripts... 
Generate In-Memory OLTP Migration Checklists 


Extract Data-tier Application... 

Deploy Database to Microsoft Azure SOL Database... 
Deploy Database to a Microsoft Azure VM... 

Export Data-tier Application... 

Register as Data-tier Application... 

Upgrade Data-tier Application... 


Delete Data-tier Application 


import Data... 
Export Data... 


Copy Database... 





Manage Database Encryption... 


If you don't have SQL Server installed, or you have SQL Server but don't have SQL Server Management Studio 
installed, see Download SQL Server Management Studio (SSMS). 


Visual Studio 


Start the SQL Server Import and Export Wizard from Visual Studio with SQL Server Data Tools (SSDT) 


In Visual Studio with SQL Server Data Tools (SSDT), with an Integration Services project open, do one of the 
following things. 


e@ On the Project menu, click SSIS Import and Export Wizard. 


SSIS Import and Export Wizard 


nent Model 


All Packages 





-or- 


e In Solution Explorer, right-click the SSIS Packages folder, and then click SSIS Import and Export 
Wizard. 


Solution ‘Start import Export’ (1 project) 
4 «& Start import Export (SQL Server 2017) 
 Project.params 
wa) Connection Managers 





If you don't have Visual Studio installed, or you have Visual Studio but don't have SQL Server Data Tools 
installed, see Download SQL Server Data Tools (SSDT). 


Get the wizard 


If you want to run the wizard, but you don't have Microsoft SQL Server installed on your computer, you can 
install the SQL Server Import and Export Wizard by installing SQL Server Data Tools (SSDT). For more info, see 
Download SQL Server Data Tools (SSDT). 


Get help while the wizard is running 





TIP 


Tap the F1 key from any page or dialog box of the wizard to see documentation for the current page. 





What's next? 


When you start the wizard, the first page is Welcome to SQL Server Import and Export Wizard. You don't 


have to take any action on this page. For more info, see Welcome to SQL Server Import and Export Wizard. 


Related tasks and content 


Here are some other basic tasks. 


e See a quick example of how the wizard works. 


If you prefer to see screen shots. Look at this simple example on a single page - Get started 
with this simple example of the Import and Export Wizard. 


If you prefer to watch a video. Watch this four-minute video from YouTube that demonstrates 
the wizard and explains clearly and simply how to export data to Excel - Using the SQL Server 
Import and Export Wizard to Export to Excel. 


Learn more about how the wizard works. 


Learn more about the wizard. If you're looking for an overview of the wizard, see Import and 
Export Data with the SQL Server Import and Export Wizard. 


Learn about the steps in the wizard. If you're looking for info about the steps in the wizard, 
see Steps in the SQL Server Import and Export Wizard. There's also a separate page of 
documentation for each page of the wizard. 


Learn how to connect to data sources and destinations. If you're looking for info about how 
to connect to your data, select the page you want from the list here - Connect to data sources with 
the SQL Server Import and Export Wizard. There's a separate page of documentation for each of 


several commonly used data sources. 


Connect to Data Sources with the SQL Server 


Import and Export Wizard 
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Applies to: Q sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


The topics in this section show you how to connect to many commonly used data sources when you run the 
SQL Server Import and Export Wizard. You have to provide connection info for your data sources on the 
Choose a Data Source and Choose a Destination pages of the wizard. 


The topics in this section describe only how to connect to data sources from the Choose a Data Source 
and Choose a Destination pages of the wizard. If you're looking for something else, see Related tasks and 
content. 


Connect to a commonly used data source 


Click a link to learn more about connecting to one of the following commonly used data sources. 


e SQL Server 

e Oracle 

e Flat files (text files) 
e Excel 

e Access 

e Azure Blob Storage 
e ODBC 

e PostgreSQL 

e MySQL 


Connect to other data providers 


For info about how to connect to a data source that's not listed here, see The Connection Strings Reference. This 
third-party site contains sample connection strings and more info about data providers and the connection info 
they require. 


Related tasks and content 


Here are some other basic tasks. 
e See a quick example of how the wizard works. 


o If you prefer to see screen shots. Take a look at this simple end-to-end example on a single 
page - Get started with this simple example of the Import and Export Wizard. 


o If you prefer to watch a video. Watch this four-minute video from YouTube that demonstrates 
the wizard and explains clearly and simply how to export data to Excel - Using the SQL Server 
Import and Export Wizard to Export to Excel. 


e Learn more about how the wizard works. 


o Learn more about the wizard. If you're looking for an overview of the wizard, see Import and 
Export Data with the SQL Server Import and Export Wizard. 


o Learn about the steps in the wizard. If you're looking for info about the steps in the wizard, 
see Steps in the SQL Server Import and Export Wizard. There's also a separate page of 


documentation for each page of the wizard. 


e Start the wizard. If you're ready to run the wizard and just want to know how to start it, see Start the 


SQL Server Import and Export Wizard. 


@ Get the wizard. If you want to run the wizard, but you don't have Microsoft SQL Server installed on 
your computer, you can install the SQL Server Import and Export Wizard by installing SQL Server Data 
Tools (SSDT). For more info, see Download SQL Server Data Tools (SSDT). 


See also 


Choose a Data Source 
Choose a Destination 


Connect to a SQL Server Data Source (SQL Server 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


This topic shows you how to connect to a Microsoft SQL Server data source from the Choose a Data 
Source or Choose a Destination page of the SQL Server Import and Export Wizard. There are several data 
providers that you can use to connect to SQL Server. 





TIP 


If you're on a network with multiple servers, it may be easier to enter the server name rather than expand the drop-down 
list of servers. If you click the drop-down list, it may take a lot of time to query the network for all available servers, and 


the results may not even include the server you want. 











Connect to SQL Server with the .NET Framework Data Provider for 
SQL Server 


After you select .NET Framework Data Provider for SQL Server on the Choose a Data Source or 
Choose a Destination page of the wizard, the page displays a grouped list of options for the provider. Many of 
these are unfriendly names and unfamiliar settings. Fortunately, to connect to any enterprise database, you 
typically have to provide only a few pieces of information. You can ignore the default values for the other 
settings. 


NOTE 


The connection options for this data provider are the same whether SQL Server is your source or your destination. That is, 
the options you see are the same on both the Choose a Data Source and the Choose a Destination pages of the 











wizard. 
-NET FRAMEWORK DATA PROVIDER FOR SQL SERVER 

REQUIRED INFO PROPERTY 

Authentication Default NotSpecified as “Integrated Security”, or choose 
other authentication mode. “Interactive Active Directory 
Authentication” is not supported. 

Server name Data Source 

Authentication (login) info Integrated Security; or, User ID and Password 


If you want to see a drop-down list of databases on the 
server, you first have to provide valid login info. 


Database name Initial Catalog 


Choose a Data Source RS 
Select the source from which to copy data. 














'y Security — | 





True 
c org x 
Persist Security Info False 
TrustServerCertificate False 
User ID 














WideW orldimporters =| 
MultiSubnetFatlover alse 
TransparentNetwork|PResolution True 
User Instance False 
v 
Initial Catalog 


The name of the initial catalog or database in the data source. 














Help < Back [Next>] Finish > | Cancel | 








Options to specify (.NET Framework Data Provider for SQL Server) 





NOTE 


The connection options for this data provider are the same whether SQL Server is your source or your destination. That is, 
the options you see are the same on both the Choose a Data Source and the Choose a Destination pages of the 
wizard. 





Data Source 
Enter the name or IP address of the source or destination server, or select a server from the drop-down list. 


To specify a non-standard TCP port, enter a comma after the server name or IP address, then enter the port 
number. 


Initial Catalog 
Enter the name of the source or destination database, or select a database from the drop-down list. 


Integrated Security 
Specify True to connect with Windows integrated authentication (recommended), or False to connect with SQL 
Server authentication. If you specify False, you must enter a user ID and password. The default value is False. 


User ID 
Enter a user name if you're using SQL Server authentication. 


Password 
Enter the password if you're using SQL Server authentication. 


Connect to SQL Server with the ODBC driver for SQL Server 


ODBC drivers aren't listed in the drop-down list of data sources. To connect with an ODBC driver, start by 





selecting the .NET Framework Data Provider for ODBC as the data source. This provider acts as a wrapper 
around the ODBC driver. 





TIP 
Get the latest driver. Download the Microsoft ODBC Driver for SQL Server. 





Here's the generic screen that you see immediately after selecting the INET Framework Data Provider for ODBC. 


Choose a Data Source PP 
Select the source from which to copy data. N Pe 


‘Y_Net Framework Data Provider for Odbc A 




















Driver 
The name of the ODBC Driver to use when connecting to the Data Source. 

















Help < Back [Next> | Finish >> | Cancel | 





Options to specify (ODBC driver for SQL Server) 





NOTE 
The connection options for the ODBC driver are the same whether SQL Server is your source or your destination. That is, 
the options you see are the same on both the Choose a Data Source and the Choose a Destination pages of the 


wizard. 





To connect to SQL Server with the latest ODBC driver, assemble a connection string that includes the following 
settings and their values. The format of a complete connection string immediately follows the list of settings. 





TIP 
Get help assembling a connection string that's just right. Or, instead of providing a connection string, provide an existing 
DSN (data source name) or create a new one. For more info about these options, see Connect to an ODBC Data Source. 








Driver 
The name of the ODBC driver. The name is different for different versions of the driver. 








Server 
The name of the SQL Server. 


Database 
The name of the database. 


Trusted_Connection; or, Uid and Pwd 
Specify Trusted_Connection=Yes to connect with Windows integrated authentication; or, specify Uid (user id) 
and Pwd (password) to connect with SQL Server authentication. 


Connection string format 


Here's the format of a connection string that uses Windows integrated authentication. 
Driver={ODBC Driver 13 for SQL Server};server=<server>;database=<database>;trusted_connection=Yes; 


Here's the format of a connection string that uses SQL Server authentication instead of Windows integrated 
authentication. 


Driver={ODBC Driver 13 for SQL Server}; server=<server>;database=<database>;uid=<user id>;pwd=<password>; 


Enter the connection string 


Enter the connection string in the ConnectionString field, or enter the DSN name in the Dsn field, on the 
Choose a Data Source or Choose a Destination page. After you enter the connection string, the wizard 
parses the string and displays the individual properties and their values in the list. 


The following example uses this connection string. 
Driver={ODBC Driver 13 for SQL Server};server=localhost;database=wideWorldImporters;trusted_connection=Yes; 
Here's the screen that you see after entering the connection string. 


Choose a Data Source P 
Select the source from which to copy data. 


Data source: @ .Net Framework Data Provider for Odbe | 




















Driver={ODBC Driver 13 for SQL Server}:serversocalt 
Vv Misc 

database WideWorldImporters 

server localhost 

trusted_connection Yes 
vy Named ConnectionString 

Dsn 
v Source 

Driver {ODBC Driver 13 for SQL Server} 
ConnectionString 
The connection string used to connect to the Data Source. 














Help < Back [Next>] Finish >> | Cancel D 
Lei 


Connect to SQL Server with the Microsoft OLE DB Provider for SQL 
Server or SQL Server Native Client 


Microsoft OLE DB Provider for SQL Server is the current OLE DB provider for SQL Server. 


Other data providers and more info 


For info about how to connect to SQL Server with a data provider that's not listed here, see SQL Server 
connection strings. This third-party site also contains more info about the data providers and the connection 
parameters described on this page. 


See also 


Choose a Data Source 
Choose a Destination 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


This topic shows you how to connect to an Oracle data source from the Choose a Data Source or Choose a 
Destination page of the SQL Server Import and Export Wizard. There are several data providers that you can 
use to connect to Oracle. 





IMPORTANT 


The detailed requirements and prerequisites for connecting to an Oracle database are beyond the scope of this Microsoft 
article. This article assumes that you already have Oracle client software installed and that you can already connect 
successfully to the target Oracle database. For more info, consult your Oracle database administrator or the Oracle 


documentation. 





Connect to Oracle with the .Net Framework Data Provider for Oracle 


After you select .NET Framework Data Provider for Oracle on the Choose a Data Source or Choose a 
Destination page of the wizard, the page presents a grouped list of options for the provider. Many of these are 
unfriendly names and unfamiliar settings. Fortunately, you only have to provide two or three pieces of 
information. You can ignore the default values for the other settings. 








NOTE 


The connection options for this data provider are the same whether Oracle is your source or your destination. That is, the 
options you see are the same on both the Choose a Data Source and the Choose a Destination pages of the 





wizard. 

REQUIRED INFO .NET FRAMEWORK DATA PROVIDER FOR ORACLE PROPERTY 
Server name Data Source 

Authentication (login) info User ID and Password; or, Integrated Security 


You don't have to enter the connection string in the ConnectionString field of the list. After you enter 
individual values for the Oracle server name (Data Source) and login info, the wizard assembles the 
connection string from the individual properties and their values. 





Choose a Data Source 
Select the source from which to copy data. 




















Data source: 
41 |5 
v Data 
ConnectionString Data Source= = ae = 
Vv Initialization 
Omit Oracle Connection Name False 
Unicode False 
v_ Pooling 
Enlist True 
Load Balance Timeout 0 
Max Pool Size 100 bs 
Min Pool Size 0 
Pooling True 
vy Secumity 


Integrated 
































Data Source 
Indicates the name of the database to connect to. 











Help | <Back |[ Next> | Finish») | Cancel _| 








Connect to Oracle with the Microsoft ODBC driver for Oracle 


ODBC drivers aren't listed in the drop-down list of data sources. To connect with an ODBC driver, start by 
selecting the .NET Framework Data Provider for ODBC as the data source on the Choose a Data Source 
or Choose a Destination page. This provider acts as a wrapper around the ODBC driver. 


Here's the generic screen that you see immediately after selecting the INET Framework Data Provider for ODBC. 


Choose a Data Source 
Select the source from which to copy data. Rs. 
\ 


‘Y_Net Framework Data Provider for Odbc ’ 




















Driver 
The name of the ODBC Driver to use when connecting to the Data Source. 




















Help < Back | Next > 





Options to specify (ODBC Driver for Oracle) 





NOTE 

The connection options for this data provider and ODBC driver are the same whether Oracle is your source or your 
destination. That is, the options you see are the same on both the Choose a Data Source and the Choose a 
Destination pages of the wizard. 








To connect to Oracle with the ODBC Driver for Oracle, assemble a connection string that includes the following 
settings and their values. The format of a complete connection string immediately follows the list of settings. 


TIP 


Get help assembling a connection string that's just right. Or, instead of providing a connection string, provide an existing 


DSN (data source name) or create a new one. For more info about these options, see Connect to an ODBC Data Source. 





Driver 
The name of the ODBC driver, Microsoft ODBC for Oracle. 


Server 
The name of the Oracle server. 


Uid and Pwd 
The user id and password to connect. 


Connection string format 


Here's the format of a typical connection string. 


Driver={Microsoft ODBC for Oracle};Server=myServerAddress ;Uid=myUsername ; Pwd=myPassword ; 


Enter the connection string 


Enter the connection string in the ConnectionString field, or enter the DSN name in the Dsn field, on the 
Choose a Data Source or Choose a Destination page. After you enter the connection string, the wizard 
parses the string and displays the individual properties and their values in the list. 


Here's the screen that you see after entering the connection string. 


Choose a Data Source ; 
Select the source from which to copy data. i... 

















Driver={Microsoft ODAC for Orace server 


O— ——_ -« = -_- 
—) 





{Microsoft ODBC for Oracle} 











ConnectionString 
The connection string used to connect to the Data Source. 











. Help | <Back |[ Next>] Finish >>| | Cancet__| 








What's my Oracle server name? 

Run one of the following queries to get the name of your Oracle server. 
SELECT host_name FROM v$instance 

or 


SELECT sys_context('USERENV', 'SERVER_HOST') FROM dual 


Other data providers and more info 


For info about how to connect to Oracle with a data provider that's not listed here, see Oracle connection strings. 


This third-party site also contains more info about the data providers and the connection parameters described 
on this page. 


See also 


Choose a Data Source 
Choose a Destination 


Connect to a Flat File Data Source (SQL Server 
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Applies to: Q sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


This topic shows you how to connect to a flat file (text file) data source from the Choose a Data Source or 
Choose a Destination page of the SQL Server Import and Export Wizard. For flat files, these two pages of the 
wizard present different sets of options, so this topic describes the flat file source and the flat file destination 
separately. 


An alternative for simple text import 


If you have to import a text file into SQL Server, and you don't need all the configuration options available in the 
Import and Export Wizard, consider using the Import Flat File Wizard in SQL Server Management Studio 
(SSMS). For more info, see the following articles: 


e What's new in SQL Server Management Studio 17.3 
e Introducing the new Import Flat File Wizard in SSMS 17.3 


Connect to a flat file source 


There are four pages of options for flat file data sources. That's a lot of pages! But you don't have to spend a lot 
of time on each page. Here are the tasks to consider. 


PAGE RECOMMENDATION TYPE 


Make sure you update the options in Recommended 
the Format section. 


Make sure you check the column and Recommended 
row delimiters (for a Delimited file) or 

mark the columns (for a Fixed Width 

file). 


Optionally, check the data types and Optional 
other properties assigned by default 
to the columns. 


Optionally, preview a sample of the Optional 
data, using the settings that you 
specified. 


General page (source) 


On the General page, browse to select the file, then verify the settings in the Format section. 





4 SQL Server import and Export Wizard - Oo x 


Choose a Date Source re 
Select the source from which to copy data 


ow soa (SE -] 

General Select a file and specify the file properties and the file format 

Couns Filename [D\testop\TeaDsabt —————SSCS:*Cmne. | 

co [Engen Uieed Sates) oe] Uric 
Code page: fi22@nsi-lenDtst—“‘“‘SéSOSOCO*;*;*;*”CSY 
Format Delented ° 


Text qualifier. [enone > 
Header row delimiter: CRLF) =] 
Header rows to skip fo =a 


Column names in the first data row 





! 


<Back _|[ Net >] Fish | Cancet_| 





Options to specify (General page) 
File name 
Enter the path and file name of the flat file. 


Browse 
Locate the flat file. 


Locale 


Specify the locale to provide language-specific information for sorting and for date and time formats. 


Unicode 


Specify whether the file uses Unicode. If you use Unicode, you can't specify a code page. 


Code page 
Specify the code page for non-Unicode text. 


Format 
Select whether the file uses delimited, fixed width, or ragged right formatting. 


VALUE DESCRIPTION 


Delimited Columns are separated by delimiters. You specify the 
delimiter on the Columns page. 


Fixed width Columns have a fixed width. 


Ragged right Ragged right files are files in which every column has a fixed 
width, except for the last column, which is delimited by the 
row delimiter. 


Text qualifier 
Specify the text qualifier, if any, used by the file. For example, you can specify that text fields are enclosed in 
quotation marks. (This property only applies to Delimited files.) 





NOTE 


After you select a text qualifier, you can't re-select the None option. Type None to de-select the text qualifier. 





Header row delimiter 


Select from the list of delimiters for header rows, or enter the delimiter text. 


VALUE DESCRIPTION 

{CR}{LF} The header row is delimited by a carriage return-line feed 
combination. 

{CR} The header row is delimited by a carriage return. 

{LF} The header row is delimited by a line feed. 

Semicolon {;} The header row is delimited by a semicolon. 

Colon {:} The header row is delimited by a colon. 

Comma {,} The header row is delimited by a comma. 

Tab {t} The header row is delimited by a tab. 

Vertical bar {|} The header row is delimited by a vertical bar. 


Header rows to skip 
Specify the number of rows to skip at the top of the file, if any. 


Column names in the first data row 
Specify whether the first row (after any skipped rows) contains column names. 


Columns page - Format = Delimited (source) 


On the Columns page, verify the list of columns and the delimiters that the wizard has identified. The following 
screen shot shows the page when you've selected Delimited as the flat file format. 


Choose a Data Source 
sacar ance ie «= 





[3 Flat File Source | 


Specify the characters that delimit the source file: 
Row delimiter: [iCRXLF} ~) 
Column delimiter: [Comat sst—<“‘i‘s;s*sSsYS 





Preview rows 2-4: 
ID Name 
1 Doug 
2 Carla 
3 Jennie 


Refresh | Reset Columns | 
Help | < Back |[__Next> | Finish >>| Cancel | 











di 


Options to specify (Columns page - Format = Delimited) 
Row delimiter 


Select from the list of available row delimiters, or enter the delimiter text. 


VALUE DESCRIPTION 

{CR}{LF} Rows are delimited by a carriage return-line feed 
combination. 

{CR} Rows are delimited by a carriage return. 

{LF} Rows are delimited by a line feed. 

Semicolon {;} Rows are delimited by a semicolon. 

Colon {:} Rows are delimited by a colon. 

Comma {,} Rows are delimited by a comma. 


Tab {t} Rows are delimited by a tab. 


VALUE DESCRIPTION 


Vertical bar {|} Rows are delimited by a vertical bar. 


Column delimiter 


Select from the list of available column delimiters, or enter the delimiter text. 


VALUE DESCRIPTION 

{CR}{LF} Columns are delimited by a carriage return-line feed 
combination. 

{CR} Columns are delimited by a carriage return. 

{LF} Columns are delimited by a line feed. 

Semicolon {;} Columns are delimited by a semicolon. 

Colon {:} Columns are delimited by a colon. 

Comma {,} Columns are delimited by a comma. 

Tab {t} Columns are delimited by a tab. 

Vertical bar {|} Columns are delimited by a vertical bar. 


Preview rows 
View sample data in the flat file, divided into columns and rows by using the options selected. 


Refresh 
View the effect of changing the delimiters to skip by clicking Refresh. This button only becomes visible after 
you have changed other connection options. 


Reset Columns 
Restore the original columns. 


Columns page - Format = Fixed Width (source) 


On the Columns page, verify the list of columns and the delimiters that the wizard has identified. The following 
screen shot shows the page when you've selected Fixed Width as the flat file format. 


Choose a Data Source 
Select the source from which to copy data. ee 
\ 


Data source: | => Flat File Source y| 


General Create column markers by clicking the ruler. Right-click a marker and select Delete, or double-click 
@ marker to remove it. Move a marker by dragging it. 





Font: Courier New v 
Source data columns: 





< > 


Row width: 18 = Reset Columns | 
Ve 


Options to specify (Columns page - Format = Fixed Width) 


Font 
Select the font in which to display the preview data. 


Source data columns 
Adjust the width of the row by sliding the vertical red row marker, and adjust the width of the columns by 
clicking the ruler at the top of the preview window 


Row width 
Specify the length of the row before adding delimiters for individual columns. Or, drag the vertical red line in the 
preview window to mark the end of the row. The row width value is automatically updated. 


Reset Columns 
Restore the original columns. 


Columns page - Format = Ragged Right (source) 


On the Columns page, verify the list of columns and the delimiters that the wizard has identified. The following 
screen shot shows the page when you've selected Ragged Right as the flat file format. 





NOTE 


Ragged right files are files in which every column has a fixed width, except for the last column, which is delimited by the 
row delimiter. 











Choose a Data Source 
Select the source from which to copy data. og 


Data source: | ES Flat File Source x 


General Create column markers by clicking the ruler. Right-click a marker and select Delete, or double-click 
Col @ marker to remove it. Move a marker by dragging it. 





Font: Courier New Y 
Source data columns: > 





< > 
Row delimiter: [{CRHLF) 7 Reset Columns | 
ZL 


Options to specify (Columns page - Format = Ragged Right) 
Font 
Select the font in which to display the preview data. 


Source data columns 
Adjust the width of the row by sliding the vertical red row marker, and adjust the width of the columns by 
clicking the ruler at the top of the preview window 


Row delimiter 
Select from the list of available row delimiters, or enter the delimiter text. 


VALUE DESCRIPTION 
{CR}{LF} Rows are delimited by a carriage return-line feed 
combination. 


{CR} Rows are delimited by a carriage return. 


VALUE 


{LF} 


Semicolon {;} 


Colon {:} 


Comma {,} 


Tab {t} 


Vertical bar {|} 


Reset Columns 
Restore the original columns. 


Advanced page (source) 


DESCRIPTION 


Rows are delimited by a line feed. 


Rows are delimited by a semicolon. 


Rows are delimited by a colon. 


Rows are delimited by a comma. 


Rows are delimited by a tab. 


Rows are delimited by a vertical bar. 


The Advanced page shows detailed info about each column in the data source, including its data type and size. 


The following screen shot shows the Advanced page for the first column in a delimited flat file. 


Choose a Data Source 
Select the source from which to copy data. 







Columns 


Advanced 


©) Preview Name 


iy 


[+ Flat File Source | 


General Configure the properties of each column. 











v Misc 
Name ID 
ColumnDelimiter Comma {.} 
ColumnType Delimited 
InputColumnWidth 0 
DataPrecision 0 
DataScale 0 
DataType string [DT_STR] 
OutputColumnWidth 50 
TextQualified True 

Name 





New >| Delete | Suggest Types... | 





Help | 


_<eet_| roots |__| 
LL 


In the screen shot, notice that the id column, which contains numbers, initially has a data type of string. 


Options to specify (Advanced page) 


Configure the properties of each column 

Select a column in the left pane to view its properties in the right pane. See the following table for a description 
of column properties. Some of the properties listed are configurable only for certain flat file formats and for 
columns of certain data types. 


PROPERTY DESCRIPTION 


Name Provide a descriptive column name. If you do not enter a 
name, Integration Services automatically creates a name in 
the format Column 0, Column 1, and so forth. 


ColumnDelimiter Select from the list of available column delimiters. Choose 
delimiters that are not likely to occur in the text. This value is 
ignored for fixed-width columns. 


{CR}{LF}. Columns are delimited by a carriage return-line 
feed combination. 


{CR}. Columns are delimited by a carriage return. 
{LF}. Columns are delimited by a line feed. 
Semicolon {;}. Columns are delimited by a semicolon. 
Colon {:}. Columns are delimited by a colon. 

Comma {,}. Columns are delimited by a comma. 

Tab {t}. Columns are delimited by a tab. 


Vertical bar {|}. Columns are delimited by a vertical bar. 


ColumnType Denotes whether the column is delimited, fixed width, or 
ragged right. This property is read-only. Ragged right files 
are files in which every column has a fixed width, except for 
the last column. It is delimited by the row delimiter. 


InputColumnWidth Specify a value to be stored as a count of bytes; for Unicode 
files, this value is a count of characters. This value is ignored 
for delimited columns. 


Note In the object model, the name of this property is 
ColumnWidth. 


DataPrecision Specify the precision of numeric data. Precision refers to the 
number of digits. 


DataScale Specify the scale of numeric data. Scale refers to the number 
of decimal places. 


DataType Select from the list of available data types. 
For more information, see Integration Services Data Types. 


PROPERTY DESCRIPTION 


OutputColumnWidth Specify a value to be stored as a count of bytes; for Unicode 
files, this value corresponds to a count of characters. In the 
Data Flow task, this value is used to set the output column 
width for the Flat File source. In the object model, the name 
of this property is MaximumWidth. 


Text Qualified Indicate whether text data is surrounded by text qualifier 
characters such as quote characters. 


True: Text data in the flat file is qualified. False: Text data in 
the flat file is NOT qualified. 


New 
Add a new column by clicking New. By default, the New button adds a new column at the end of the list. The 
button also has the following options, available in the drop-down list. 


VALUE DESCRIPTION 

Add Column Add a new column at the end of the list. 

Insert Before Insert a new column before the selected column. 

Insert After Insert a new column after the selected column. 
Delete 


Select a column, and then remove it by clicking Delete. 


Suggest Types 
Use the Suggest Column Types dialog box to evaluate sample data in the file and to obtain suggestions for 
the data type and length of each column. 


Click Suggest types to display the Suggest Column Types dialog box. 





Suggest Column Types 


Flat File Connection Manager Editor can suggest the data type of columns 
You can specify the sample size to use. the data types to replace. and the 
percentage of padding to add to columns that contain character data 





Number of rows {boo = 
[¥ Suggest the smallest integer data type 
I¥ Suggest the smallest real data type 


I¥ Identify Boolean columns using the following values 


True False 
[” Pad string columns 
Percent padding =4 


Lo} _ Concet_| 








After you choose options in the Suggest Column Types dialog box and click OK, the wizard may change the 
data types of some of the columns. 


The following screen shot shows that, after you click Suggest types, the wizard has recognized that the id 
column in the data source is in fact a number and not a text string, and has changed the data type of the column 
from a string to an integer. 


4 SQL Server import and Export Wizard - Oo x 


Choose a Date Source 
Select the source from which to copy data. 


Data source: [= Fiat File Source x] 
General Configure the properties of each column. 
Columns 
Advanced v Misc 
1 Preview name Name id 
ColumnDelimiter Comma {.} 
ColumaType Delmted 
InputColumal\idth 0 
DataPrecision 0 
DataType single-byte signed integer [D 
TextQualified Troe 
Name 








For more info, see Suggest Column Types Dialog Box UI Reference. 


Preview page (source) 


On the Preview page, verify that the list of columns and the sample data are what you expect. 


Choose a Data Source 
Select the source from which to copy data. = 





[3 Flat File Source v| 
S 


The preview shows the source file divided into the specified columns. Initial data 
rows that are skipped when the file is parsed during runtime, are not shown. 





Be Preven] 


Data rows to skip: fo = 


Preview rows 2-4: 
iD Name 
1 Doug 
2 Carla 
3 Jennie 


Refresh | 
Help _| < Back [Next> | Finish >>| Cancel ly 
La 





Options to specify (Preview page) 
Data rows to skip 
Specify how many rows to skip at the beginning of the flat file. 


Preview rows 


View sample data in the flat file, divided into columns and rows according to the options you have selected. 


Refresh 


View the effect of changing the number of rows to skip by clicking Refresh. This button only becomes visible 
after you have changed other connection options. 


For more info about the Preview page, see the following Integration Services reference page - Flat File 
Connection Manager Editor (Preview Page). 
Connect to a flat file destination 


For a flat file destination, there's only a single page of options, as shown in the following screen shot. Browse to 
select the file, then verify the settings in the Format section. 





DestonSone (i) FatrieDesineion SSSCSCSC~S~S 

Select a file and specify the file properties and the file format. 

File name: [D\Desktop\TestDatabt == t—<“‘éSOSOSO™O™*S*;*;*;*”*”!O”””O~O~*;*#@Rowse.. | 
wii [Engish (United States) #8 «| JF Unicode 
Code page: [izs2 ANSI'lam)——=~SC~S~S~S~S~SSSSSSSSSSS 


—_ 
Text qualifier: [enone> 


IV Column names in the first data row 








te eet |[TT] fo | coe | 
La 


Options to specify (Choose a Destination page) 
File name 
Enter the path and file name of the flat file. 


Browse 
Locate the flat file. 


Locale 


Specify the locale to provide language-specific information for sorting and for date and time formats. 


Unicode 


Specify whether the file uses Unicode. If you use Unicode, you can't specify a code page. 


Code page 
Specify the code page for non-Unicode text. 


Format 
Select whether the file uses delimited, fixed width, or ragged right formatting. 


VALUE DESCRIPTION 


Delimited Columns are separated by delimiters. You specify the 
delimiter on the Columns page. 


VALUE DESCRIPTION 
Fixed width Columns have a fixed width. 


Ragged right Ragged right files are files in which every column has a fixed 
width, except for the last column, which is delimited by the 
row delimiter. 


Text qualifier 


Specify the text qualifier, if any, used by the file. For example, you can specify that text fields are enclosed in 
quotation marks. (This property only applies to Delimited files.) 


NOTE 


After you select a text qualifier, you can't reselect the None option. Type None to de-select the text qualifier. 





See also 


Choose a Data Source 
Choose a Destination 


Connect to an Excel Data Source (SQL Server 
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Applies to: Q sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


This article shows you how to connect to a Microsoft Excel data source from the Choose a Data Source or 
Choose a Destination page of the SQL Server Import and Export Wizard. 


The following screen shot shows a sample connection to a Microsoft Excel workbook. 





4 SQL Server import and Export Wizard - Oo x 


Choose a Data Source rb 
Select the source from which to copy data Ay 
\ 


Excel file path: 


fo \Desktop \Test Data xdsx Browse. 


Excel version: 


(Microsoft Excel 2016 5 


First row has column names 








__Helo_| <Back _|[Newt>] fish») | Cancet_| 





You may have to download and install additional files to connect to Excel files. For more info, see Get the files 
you need to connect to Excel. 


IMPORTANT 


For detailed info about connecting to Excel files, and about limitations and known issues for loading data from or to Excel 


files, see Load data from or to Excel with SQL Server Integration Services (SSIS). 





Options to specify 


NOTE 


The connection options for this data provider are the same whether Excel is your source or your destination. That is, the 
options you see are the same on both the Choose a Data Source and the Choose a Destination pages of the 
wizard. 











Excel file path 
Specify the path and file name for the Excel file. For example: 


e Fora file on the local computer, C:\MyData.xlsx. 


e Fora file on a network share, \\Sales\Database\Northwind.xlsx. 
Or, click Browse. 


Browse 
Locate the spreadsheet by using the Open dialog box. 





NOTE 


The wizard can't open a password-protected Excel file. 





Excel version 


Select the version of Excel that's used by the source or destination workbook. 


First row has column names 
Indicate whether the first row of the data contains column names. 


e Ifthe data doesn't contain column names but you enable this option, the wizard treats the first row of source 
data as the column names. 
e Ifthe data contains column names but you disable this option, the wizard treats the row of column names as 


the first row of data. 


If you specify that the data doesn't have column names, the wizard uses F1, F2, and so forth, as column 


headings. 


| don't see Excel in the list of data sources 


If you don't see Excel in the list of data sources, are you running the 64-bit wizard? The providers for Excel and 
Access are typically 32-bit and aren't visible in the 64-bit wizard. Run the 32-bit wizard instead. 


NOTE 
To use the 64-bit version of the SQL Server Import and Export Wizard, you have to install SQL Server. SQL Server Data 
Tools (SSDT) and SQL Server Management Studio (SSMS) are 32-bit applications and only install 32-bit files, including the 


32-bit version of the wizard. 











See also 


Load data from or to Excel with SQL Server Integration Services (SSIS) 
Choose a Data Source 
Choose a Destination 


Connect to an Access Data Source (SQL Server 


Import and Export Wizard) 
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Applies to: Q@ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


This topic shows you how to connect to a Microsoft Access data source from the Choose a Data Source or 
Choose a Destination page of the SQL Server Import and Export Wizard. 


The following screen shot shows a sample connection to a Microsoft Access database. In this example, you don't 
have to enter a user name and password, because the target database doesn't use a workgroup information file. 





Choose a Data Source 
Select the source from which to copy data. ese 
Data source: @ Microsoft Access (Microsoft ACE.OLEDB.15.0) ’ | 
To connect, select a database and provide a user name and password. You may need to specify advanced options. 
File name: 
[D.\Desktop\ Test Data mdb . 
User name: ee 


Password: ee 





| Help | < Back | Next > | Finish | Cancel ly 


Options to specify 





NOTE 


The connection options for this data provider are the same whether Access is your source or your destination. That is, the 
options you see are the same on both the Choose a Data Source and the Choose a Destination pages of the 
wizard. 








Data source 
The list of data providers may contain several entries for Microsoft Access. Select the latest installed version, or 
the version that corresponds to the version of Access that created the database file. 


DATA SOURCE OFFICE VERSION 

Microsoft Access (Microsoft.ACE.OLEDB.16.0) Office 2016 

Microsoft Access (Microsoft.ACE.OLEDB.15.0) Office 2013 

Microsoft Access (Microsoft Access Database Engine) Office 2010 and Office 2007 

Microsoft Access (Microsoft Jet Database Engine) Office versions earlier than Office 2007 


IMPORTANT 


You may have to download and install additional files to connect to Access databases. See Get the files you need to 


connect to Access on this page for more info. 





File name 
Specify the path and file name for the Access file. For example, C:\MyData.mdb for a file on the local computer, 
or \\Sales\Database\Northwind.mdb for a file on a network share. Or, click Browse. 





NOTE 


If you click Browse to locate the Access file, the Open dialog box filters for files with the older .MDB format and file 


extension by default. However the data provider can also open files with the newer .ACCDB format and file extension. 











Browse 
Locate the database file by using the Open dialog box. 


User name 
If a workgroup information file is associated with the database, provide a valid user name. 


Password 
If a workgroup information file is associated with the database, provide the user's password here. 


If the database is protected with a single password for all users, see Is the database file password-protected?. 


Advanced 
Specify advanced options, such as the database password or a non-default workgroup information file, in the 
Data Link Properties dialog box. 


| don't see Access in the list of data sources 


If you don't see Access in the list of data sources, are you running the 64-bit wizard? The providers for Excel and 
Access are typically 32-bit and aren't visible in the 64-bit wizard. Run the 32-bit wizard instead. 





NOTE 


To use the 64-bit version of the SQL Server Import and Export Wizard, you have to install SQL Server. SQL Server Data 
Tools (SSDT) and SQL Server Management Studio (SSMS) are 32-bit applications and only install 32-bit files, including the 


32-bit version of the wizard. 





Get the files you need to connect to Access 


You may have to download the connectivity components for Microsoft Office data sources, including Access and 
Excel, if they're not already installed. Download the latest version of the connectivity components for both 
Access and Excel files here: Microsoft Access Database Engine 2016 Redistributable. 


The latest version of the components can open files created by earlier versions of Access. 


If the computer has a 32-bit version of Office, then you have to install the 32-bit version of the components, and 
you also have to ensure that you run the package in 32-bit mode. 


If you have a Microsoft 365 subscription, make sure that you download the Access Database Engine 2016 
Redistributable and not the Microsoft Access 2016 Runtime. When you run the installer, you may see an error 
message that you can't install the download side-by-side with Office click-to-run components. To bypass this 
error message, run the installation in quiet mode by opening a Command Prompt window and running the .EXE 
file that you downloaded with the /quiet switch. For example: 


c:\Users\<user name>\Downloads\AccessDatabaseEngine.exe /quiet 


Is the database file password-protected? 


In some cases, an Access database is password-protected, but isn't using a workgroup information file. All users 
have to provide the same password, but don't have to enter a user name. To provide a database password, do 
the following. 


1. On the Choose a Data Source or Choose a Destination page, click the Advanced button to open the 
Data Link Properties dialog box. 


2. Inthe Data Link Properties dialog box, select the All tab. 


3. In the list of properties and values, select Jet OLEDB:Database Password. 





Connection Advanced All 


These are the initialization properties for this type of data. To edit a 
value, select a property, then choose Edit Value below. 


Name Value A 
Data Source D:\Desktop \Tes 
Extended Properties 


Jet OLEDB:Bypass ChoiceField Valida... False 
Jet OLEDB:Bypass Userinfo Validation False 
Jet OLEDB:Compact Without Replica... False 
Jet OLEDB:Create System Database False 








Jet OLEDB:Database Password 
Jet OLEDB:Encrypt Database False 
Jet OLEDB:Engine Type 0 
Jet OLEDB:Global Bulk Transactions 1 v 
< > 
Edit Value... 





4. Click Edit Value to open the Edit Property Value dialog box. 


Property Descriot 


Jet OLEDB:Database Password 


Property Value 


— EEE 
Reset Value [0K] | cance | 


5. In the Edit Property Value dialog box, enter the database password. 


6. Click OK in each dialog box to return to the Choose a Data Source or Choose a Destination page of 
the wizard and continue. 


Keep your autonumber values when you export from Access 


To allow existing identity values in the source data to be inserted into an identity column in the destination table, 
choose the Enable identity insert option in the Column Mappings dialog box. By default, the destination 
identity column typically doesn't let you insert existing values. To show the Column Mappings dialog box, 
select Edit mappings when you reach the Select Source Tables and Views page of the wizard. To look at 
these pages, see Select Source Tables and Views and Column Mappings. 


If your existing primary keys are in an identity column, an autonumber column, or the equivalent, you typically 
have to select this option to keep your existing primary key values. Otherwise the destination identity column 


typically assigns new values. 


See also 


Choose a Data Source 
Choose a Destination 


Connect to Azure Blob Storage (SQL Server Import 


and Export Wizard) 


11/23/2021 + 2 minutes to read * Edit Online 





Applies to: Q@saQl Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


This topic shows you how to connect to an Azure Blob Storage data source from the Choose a Data Source 
or Choose a Destination page of the SQL Server Import and Export Wizard. 


NOTE 


To use the Azure Blob Source or Destination, you have to install the Azure Feature Pack for SQL Server Integration 
Services. 


© To download the Feature Pack, see Microsoft SQL Server 2016 Integration Services Feature Pack for Azure. 


e For more info, see Azure Feature Pack for Integration Services (SSIS). 











The following screen shot shows the options to configure for a connection to Azure Blob Storage. 





4 SQL Server import and Export Wizard - Oo x 
Choose a Data Source 
Select the source from which to copy data 
Data source: 
Susthentication 
@ Use Azure account 
Storage account name 
Account key : 
Use HTTPS 


Blob container name | =] Refresh | 
Format 
Blob file format : [Tex Ad 


I Use first row as column names 


ee 


__ Helo _| <Back _|[_ Nets] Finish» | _Cancet_| 








Options to specify 





NOTE 


The connection options for this data provider are the same whether Azure Blob Storage is your source or your 
destination. That is, the options you see are the same on both the Choose a Data Source and the Choose a 
Destination pages of the wizard. 








Use Azure account 
Specify whether to use an online account. 


Storage account name 
Enter the name of the Azure storage account. 


Account key 
Enter the key for the Azure storage account. 


Use HTTPS 
Specify whether to use HTTP or HTTPS to connect to the storage account. 


Use local developer account 
Specify whether to use the Azure Storage Emulator on the local computer. 


Blob container name 
Select from the list of storage containers available in the specified storage account. 


Blob file format 


Select Text or Avro file format. 


Column delimiter character 
If you selected Text format, enter the column delimiter character. 


Use first row as column names 


Specify whether the first row of data contains column names. 


See also 


Choose a Data Source 
Choose a Destination 
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Applies to: Q sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


This topic shows you how to connect to an ODBC data source from the Choose a Data Source or Choose a 
Destination page of the SQL Server Import and Export Wizard. 


You may have to download the ODBC driver you need from Microsoft or from a third party. 


You may also have to look up the required connection info that you have to provide. This third-party site - The 
Connection Strings Reference - contains sample connection strings and more info about data providers and the 
connection info they require. 


Make sure the driver you want is installed 


1. Search for or browse to the ODBC Data Sources (64-bit) applet in the Start Menu or Control Panel. If 
you only have a 32-bit driver, or you know that you have to use a 32-bit driver, search for or browse to 
ODBC Data Sources (32-bit) instead. 


2. Launch the applet. The ODBC Data Source Administrator window opens. 


3. On the Drivers tab, you can find a list of all the ODBC drivers installed on your computer. (The names of 
some of the drivers may be listed in multiple languages.) 


Here's an example of the list of installed 64-bit drivers. 





& ODBC Data Source Administrator (64-bit) x 


User DSN System DSN File DSN Drivers Tracing Connection Pooling About 
ODBC Drivers that are installed on your system: 





Name Version Company File Date 


ODBC Driver 11 for SQL Server 2014.120.4219.00 Microsoft Corporation MSODBCSQL11.DLL 12/21/2015 
08) ee me iom ele aig 2015.131.811.168 Microsoft Corporation MSODBCSQL13.DLL 7/28/2016 
SQL Server 10.00.14393.00 Microsoft Corporation SQLSRV32.DLL 7/16/2016 
SQL Server Native Client 11.0 2011.110.6518.00 Microsoft Corporation SQLNCLI11.DLL 1/7/2016 











. An ODBC driver allows ODBC-enabled programs to get information from ODBC data sources. To install 
EE] cae cas cides 





[ok] | cancet | | Aon Hee 








TIP 


If you know that your driver's installed and you don't see it in the 64-bit applet, look in the 32-bit applet instead. This also 
tells you whether you have to run the 64-bit or 32-bit SQL Server Import and Export Wizard. 


To use the 64-bit version of the SQL Server Import and Export Wizard, you have to install SQL Server. SQL Server Data 
Tools (SSDT) and SQL Server Management Studio (SSMS) are 32-bit applications and only install 32-bit files, including the 
32-bit version of the wizard. 





Step 1 - Select the data source 


The ODBC drivers installed on your computer aren't listed in the drop-down list of data sources. To connect with 
an ODBC driver, start by selecting the .NET Framework Data Provider for ODBC as the data source on the 
Choose a Data Source or Choose a Destination page of the wizard. This provider acts as a wrapper around 
the ODBC driver. 


Here's the generic screen that you see immediately after selecting the INET Framework Data Provider for ODBC. 
































Choose a Data Source Ee 
Select the source from which to copy data. ; re 
CR 
Dat source C7 Net Framework Daa ProndertrOde 
:4)|S 
v Data 
ConnectionString 
vy Named ConnectionSting 
Dsn 
v Source 
Driver 
Driver 
The name of the ODBC Driver to use when connecting to the Data Source. 
Help < Back [Next> | Finish >>| | Cancel _| 








Step 2 - Provide the connection info 


The next step is to provide the connection info for your ODBC driver and your data source. You have two 
options. 


1. Provide a DSN (data source name) that already exists or that you create with the ODBC Data Source 
Administrator applet. A DSN is the saved collection of settings required to connect to an ODBC data 


source. 


If you already know the DSN name, or know how to create a new DSN now, you can skip the rest of this 
page. Enter the DSN name in the Dsn field on the Choose a Data Source or Choose a Destination 





page, then continue to the next step of the wizard. 
Provide a DSN 


2. Provide a connection string, which you can look up online, or create and test on your computer with 
the ODBC Data Source Administrator applet. 


If you already have the connection string or know how to create it, you can skip the rest of this page. 
Enter the connection string in the ConnectionString field on the Choose a Data Source or Choose a 
Destination page, then continue to the next step of the wizard. 


Provide a connection string 


If you provide a connection string, the Choose a Data Source or Choose a Destination page displays all the 
connection info that the wizard is going to use to connect to your data source, such as server and database 
name and authentication method. If you provide a DSN, this information isn't visible. 


Option 1 - Provide a DSN 


If you want to provide the connection information with a DSN (data source name), use the ODBC Data Source 
Administrator applet to find the name of the existing DSN, or to create a new DSN. 


1. Search for or browse to the ODBC Data Sources (64-bit) applet in the Start Menu or Control Panel. If 
you only have a 32-bit driver, or have to use a 32-bit driver, search for or browse to ODBC Data 
Sources (32-bit) instead. 


2. Launch the applet. The ODBC Data Source Administrator window opens. Here's what the applet looks 


like. 


£4 ODBC Data Source Administrator (64-bit) 


User DSN System DSN File DSN Drivers Tracing Connection Pooling About 





User Data Sources: b> 
Name Platform Driver Add... 
Excel Files 32-bit Microsoft Excel Driver ("2ds, *xdsx, “adsm, “2d 
MS Access Database 32bit Microsoft Access Driver (*.mdb, *.accdb) Remove 
TestOracle 32-it Microsoft ODBC for Oracle 
TestSqlODBC13 32/64bit ODBC Driver 13 for SQL Server Configure... 


Visio Database Samples 32-bit Microsoft Access Driver (“.mdb, *.accdb) 











The driver of this User DSN only has a 32-bit version available. It can only be removed or configured 
E==p | with the 32-bit ODBC Data Source Administrator 


[oT] [cnet] a 








3. If you want to use an existing DSN for your data source, you can use any DSN that you see on the 
User DSN, System DSN, or File DSN tab. Check the name, then go back to the wizard and enter it in 
the Dsn field on the Choose a Data Source or Choose a Destination page. Skip the rest of this page 
and continue to the next step of the wizard. 


4. If you want to create a new DSN, decide whether you want it to be visible only to you (User DSN), 
visible to all users of the computer including Windows services (System DSN), or saved in a file (File 
DSN). This example creates a new System DSN. 


5. On the System DSN tab, click Add. 


£5 ODBC Data Source Administrator (64-bit) N 


User DSN System DSN File DSN Drivers Tracing Connection Pooling About 











System Data Sources: 
Name Platform Driver Add... 
Remove 


», An ODBC System data source stores information about how to connect to the indicated data provider. 
A System data source is visible to all users on this machine, including NT services. 








Lok) {concer | Ae) [Hee | 


6. Inthe Create a New Data Source dialog box, select the driver for your data source, then click Finish. 


Create New Data Source 


Select a driver for which you want to set up a data source. 





Name ‘aa 
ODBC Driver 13 for SQL Server 2015.131.811.168 
SQL Server 10.00.14393.00 





SQL Server Native Client 11.0 2011.110.6518.00 
SQL Server Native Client RDA 11.0 2011.110.5069.55 














<Back —|__Finish | | Cancel 

















7. The driver now displays one or more driver-specific screens where you enter the info needed to connect 
to your data source. (For the SQL Server driver, for example, there are four pages of custom settings.) 
After you finish, the new system DSN appears in the list. 


£8 ODBC Data Source Administrator (64-bit) 


User DSN System DSN File DSN Drivers Tracing Connection Pooling About 


System Data Sources: 


64bit ODBC Driver 13 for SQL Server 

















. An ODBC System data source stores information about how to connect to the indicated data provider. 
0 | A System data source is visible to all users of this computer, including NT services. 








8. Go back to the wizard and enter the DSN name in the Dsn field on the Choose a Data Source or 
Choose a Destination page. Continue to the next step of the wizard. 


Option 2 - Provide a connection string 


If you want to provide your connection information with a connection string, the rest of this topic helps you get 
the connection string you need. 


This example is going to use the following connection string, which connects to Microsoft SQL Server. The 
database example that is used is WideWorldImporters and we're connecting to the SQL Server on the local 


machine. 


Driver={ODBC Driver 13 for SQL Server};server=localhost;database=wideWorldImporters;trusted_connection=Yes; 


Enter the connection string in the ConnectionString field on the Choose a Data Source or Choose a 
Destination page. After you enter the connection string, the wizard parses the string and displays the individual 
properties and their values in the list. 


Here's the screen that you see after entering the connection string. 


Choose a Data Source 
Select the source from which to copy data. 


Data source: @ .Net Framework Data Provider for Odbe | 




















Data 

Driver={ODBC Driver 13 for SQL Server}:serversocalt 
Vv Misc 

database WideWorldImporters 

server localhost 

trusted_connection Yes 
Vv Named ConnectionSting 

Dsn 
v Source 

Driver {ODBC Driver 13 for SQL Server} 
ConnectionSting 
The connection string used to connect to the Data Source. 
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NOTE 

The connection options for an ODBC driver are the same whether you're configuring your source or your destination. 
That is, the options you see are the same on both the Choose a Data Source and the Choose a Destination pages 
of the wizard. 





Get the connection string online 


To find connection strings for your ODBC driver online, see The Connection Strings Reference. This third-party 
site contains sample connection strings and more info about data providers and the connection info they 
require. 


Get the connection string with an app 


To build and test the connection string for your ODBC driver on your own computer, you can use the ODBC 
Data Source Administrator applet in the Control Panel. Create a File DSN for your connection, then copy 
settings out of the File DSN to assemble the connection string. This requires several steps, but helps to make 
sure you have a valid connection string. 


1. Search for or browse to the ODBC Data Sources (64-bit) applet in the Start Menu or Control Panel. If 
you only have a 32-bit driver, or have to use a 32-bit driver, search for or browse to ODBC Data 
Sources (32-bit) instead. 


2. Launch the applet. The ODBC Data Source Administrator window opens. 
3. Now go to the File DSN tab of the applet. Click Add. 


For this example, create a File DSN rather than a User DSN or System DSN, because the File DSN saves 





the name-value pairs in the specific format required for the connection string. 


E43 ODBC Data Source Administrator (64-bit) IN x 
User DSN System DSN FileDSN Drivers Tracing Connection Pooling About 


Look in: Documents v| Pal 





|_| Custom Office Templates S| TestOracle.dsn a 
__ Fiddler2 | TestSqlODBC13.dsn = 





|_| SQL Server Management Studio Set Directory 
|_| Visual Studio 2015 











An ODBC File data source allows you to connect to a data provider. File DSNs can be shared by users 
EE) who have the same drivers installed. 





Lok] | Cancel Aly 





4. Inthe Create New Data Source dialog box, select your driver in the list, and then click Next. This 


example is going to create a DSN that contains the connection string arguments we need to connect to 
Microsoft SQL Server. 


Create New Data isi» 


Select a driver for which you want to set up a data source. 





Name Version 


ODBC Driver 11 for SQL Server 2014.120.4219.00 
ODBC Driver 13 for SQL Server 2015.131.811.168 
SQL Server 10.00.14393.00 

SQL Server Native Client 11.0 2011.110.6518.00 


SQL Server Native Client RDA 11.0 2011.110.5069.55 








hens] [tes 








5. Select a location and enter a filename for the new File DSN, and then click Next. Remember where you 
save the file so you can find it and open it in a subsequent step. 


Create New Data Source 


Type the name of the file data source you want to save 
this connection to. Or, find the location to save to by 








6. Review the summary of your selections, and then click Finish. 


7. After you click Finish, the driver that you selected displays one or more proprietary screens to gather the 
info it needs to connect. Typically this info includes server, login info, and database for server-based data 


sources, and file, format, and version for file-based data sources. 


8. After you configure your data source and click Finish, you typically see a summary of your selections 


and have an opportunity to test them. 





ODBC Microsoft SQL Server Setup dS x 


Anew ODBC data source will be created with the following configuration: 





Microsoft ODBC Driver for SQL Server Version 13.01.0811 
Data Source Name: TestSQLODBC.dsn 
Source Description: 


Regional Settings: 
Use ANSI Quoted Identifiers: Yes 
Use ANSI Null, Paddings and Wamings: Yes 








9. After you test your data source and close the dialog boxes, find the File DSN where you saved it in the file 
system. If you didn't change the file extension, the default extension is .DSN. 


10. Open the saved file with Notepad or another text editor. Here are the contents of our SQL Server 


example. 


[ODBC] 

DRIVER=ODBC Driver 13 for SQL Server 
TrustServerCertificate=No 
DATABASE=WideWorldImporters 

WSID=<local computer name> 

APP=MicrosoftA® WindowsA® Operating System 
Trusted_Connection=Yes 

SERVER=localhost 


11. Copy and paste the necessary values into a connection string in which the name-value pairs are 
separated by semi-colons. 


After you assemble the necessary values from the sample file DSN, you have the following connection 
string. 


DRIVER=ODBC Driver 13 for SQL 
Server ; SERVER=Localhost ; DATABASE=WideWorldImporters; Trusted_Connection=Yes 


You don't typically need all the settings in a DSN created by the ODBC Data Source Administrator to 
create a connection string that works. 


e You always have to specify the ODBC driver. 


e For aserver-based data source like SQL Server, you typically need Server, Database, and login 
information. In the sample DSN, you don't need TrustServerCertificate, WSID, or APP. 


e Fora file-based data source, you need at least file name and location. 


12. Paste this connection string into the ConnectionString field on the Choose a Data Source or Choose 
a Destination page of the wizard. The wizard parses the string and you're ready to continue! 


Choose a Data Source 
Select the source from which to copy data. 




















Driver={ODBC Driver 13 for SQL Server}:serversocalt 
Vv Misc 

database WideWorldImporters 

server localhost 

trusted_connection Yes 
vy Named ConnectionString 

Dsn 
v Source 

Driver {ODBC Driver 13 for SQL Server} 
C ionSti 
The connection string used to connect to the Data Source. 
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See also 


Choose a Data Source 
Choose a Destination 


Connect to a PostgreSQL Data Source (SQL Server 
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Applies to: Q sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


This topic shows you how to connect to a PostgreSQL data source from the Choose a Data Source or 
Choose a Destination page of the SQL Server Import and Export Wizard. 


IMPORTANT 


The detailed requirements and prerequisites for connecting to a PostgreSQL database are beyond the scope of this 
Microsoft article. This article assumes that you already have PostgreSQL client software installed and that you can already 
connect successfully to the target PostgreSQL database. For more info, consult your PostgreSQL database administrator 
or the PostgreSQL documentation. 











Get the PostgreSQL ODBC driver 


Install the ODBC driver with Stack Builder 
Run Stack Builder to add the PostgreSQL ODBC driver (psqlODBC) to your installation of PostgreSQL. 


Stack Builder 4.0.0 






Please select the applications you would like to install. 


ae 


4) Add-ons, tools and utilities 






















7 Npgsql v3.0.8-1 (installed) 
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T- psqloDBc (32 bit) v09.05.0400-1 
“lf psglODBC (64 bit) v09.05.0400-1 (installed) 
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Or, download the latest ODBC driver 


Or, download the Windows installer for the latest version of the PostgreSQL ODBC driver (psqlODBC) directly 
from this FTP site - https://www.postgresql.org/ftp/odbc/versions/msi/. Extract the files from the .zip file and run 
the .msi file. 


Connect to PostgreSQL with the PostgreSQL ODBC driver (psqlODBC) 


ODBC drivers aren't listed in the drop-down list of data sources. To connect with an ODBC driver, start by 
selecting the .NET Framework Data Provider for ODBC as the data source on the Choose a Data Source 


or Choose a Destination page. This provider acts as a wrapper around the ODBC driver. 


Here's the generic screen that you see immediately after selecting the INET Framework Data Provider for ODBC. 


Choose a Data Source 
Select the source from which to copy data. N 




















Driver 
The name of the ODBC Driver to use when connecting to the Data Source. 
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Options to specify (PostgreSQL ODBC driver) 





NOTE 


The connection options for this data provider and ODBC driver are the same whether PostgreSQL is your source or your 
destination. That is, the options you see are the same on both the Choose a Data Source and the Choose a 


Destination pages of the wizard. 





To connect to PostgreSQL with the PostgreSQL ODBC driver, assemble a connection string that includes the 
following settings and their values. The format of a complete connection string immediately follows the list of 


settings. 








TIP 


Get help assembling a connection string that's just right. Or, instead of providing a connection string, provide an existing 
DSN (data source name) or create a new one. For more info about these options, see Connect to an ODBC Data Source. 





Driver 
The name of the ODBC driver - either PostgreSQL ODBC Driver(UNICODE) or PostgreSQL ODBC 
Driver(ANSI). 


Server 
The name of the PostgreSQL server. 


Port 





The port to use to connect to the PostgreSQL server. 


Database 
The name of the PostgreSQL database. 


Uid and Pwd 
The Uid (user id) and Pwd (password) to connect. 


Connection string format 


Here's the format of a typical connection string. 


Driver={PostgreSQL ODBC Driver(UNICODE) };Server=<server>;Port=<port>;Database=<database>;UID=<user id>;PWD= 
<password> 


Enter the connection string 


Enter the connection string in the ConnectionString field, or enter the DSN name in the Dsn field, on the 
Choose a Data Source or Choose a Destination page. After you enter the connection string, the wizard 
parses the string and displays the individual properties and their values in the list. 


The following example uses this connection string. 


Driver={PostgreSQL ODBC 
Driver (UNICODE) };Server=127.0.0.1;Port=5432;Database=postgres ;UID=postgres ; PWD=******** 


Here's the screen that you see after entering the connection string. 


B SOL Server Import and Export Wizard = Oo x 
Choose a Data Source ~~ 
Select the source from which to copy data. ; ‘4 > 




















Data source: @ Net Framework Data Provider for Odbe | 
a2 2) |S 
|v Data iN 
Driver={PostgreSQL ODBC Driver(UNICODE)}:server= 
v_ Misc 
database postgres 
port 5432 
server 127.0.0.1 
uid postgres 
vy Named ConnectionSting 
Dsn 
Vv Security 
pwd eecccccce 
Vv Source 
Driver {PostgreSQL ODBC Driver({UNICODE)} 
ConnectionSting 
The connection string used to connect to the Data Source. 
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Other data providers and more info 


For info about how to connect to PostgreSQL with a data provider that's not listed here, see PostgreSQL 
connection strings. This third-party site also contains more info about the data providers and the connection 
parameters described on this page. 


See also 


Choose a Data Source 
Choose a Destination 


Connect to a MySQL Data Source (SQL Server 
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Applies to: Q sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


This topic shows you how to connect to an MySQL data source from the Choose a Data Source or Choose a 
Destination page of the SQL Server Import and Export Wizard. There are several data providers that you can 
use to connect to MySQL. 





IMPORTANT 


The detailed requirements and prerequisites for connecting to a MySQL database are beyond the scope of this Microsoft 
article. This article assumes that you already have MySQL client software installed and that you can already connect 
successfully to the target MySQL database. For more info, consult your MySQL database administrator or the MySQL 


documentation. 








Get the MySQL connectors 


Download the providers and drivers described in this topic from the MySQL Connectors page. 


Connect to MySQL with the .Net Framework Data Provider for MySQL 


After you select .NET Framework Data Provider for MySQL on the Choose a Data Source or Choose a 
Destination page of the wizard, the page presents a grouped list of options for the provider. Many of these are 
unfriendly names and unfamiliar settings. Fortunately, you only have to provide a few pieces of information. You 
can ignore the default values for the other settings. 


NOTE 


The connection options for this data provider are the same whether MySQL is your source or your destination. That is, 
the options you see are the same on both the Choose a Data Source and the Choose a Destination pages of the 











wizard. 

REQUIRED INFO .NET FRAMEWORK DATA PROVIDER FOR MYSQL PROPERTY 
Server name Server 

Database name Database 

Authentication (login) info User Id and Password 


You don't have to enter the connection string in the ConnectionString field of the list. After you enter 
individual values for the MySQL server name (Server) and login info, the wizard assembles the connection 
string from the individual properties and their values. 


B SOL Server Import and Export Wizard — O x 


Choose a Data Source 
Select the source from which to copy data. 


Data source: @ Net Framework Data Provider for MySQL | 














I 








Port 
127.0.0.1 I 
Shared Memory Name 
Use Compression 
Use Old Syntax 
Vv Misc 
FabricGroup 
FabricScope 
FabricServerMode 
Keep Alive 
|__ startin + 
Server 
Server to connect to 
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vy Security 
Password eeccccece 
Persist Security Info 
Ss! Mode 
User Id root 








Connect to MySQL with the MySQL ODBC driver 


ODBC drivers aren't listed in the drop-down list of data sources. To connect with an ODBC driver, start by 
selecting the .NET Framework Data Provider for ODBC as the data source on the Choose a Data Source 
or Choose a Destination page. This provider acts as a wrapper around the ODBC driver. 


Here's the generic screen that you see immediately after selecting the INET Framework Data Provider for ODBC. 


Choose a Data Source 
Select the source from which to copy data. Rs. 
\ 


‘Y_Net Framework Data Provider for Odbc ’ 




















Driver 
The name of the ODBC Driver to use when connecting to the Data Source. 
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Options to specify (MySQL ODBC Driver) 





NOTE 

The connection options for this data provider and ODBC driver are the same whether MySQL is your source or your 
destination. That is, the options you see are the same on both the Choose a Data Source and the Choose a 
Destination pages of the wizard. 








To connect to MySQL with the MySQL ODBC driver, assemble a connection string that includes the following 
settings and their values. The format of a complete connection string immediately follows the list of settings. 


TIP 


Get help assembling a connection string that's just right. Or, instead of providing a connection string, provide an existing 


DSN (data source name) or create a new one. For more info about these options, see Connect to an ODBC Data Source. 





Driver 
The name of the ODBC driver. 


Server 
The name of the MySQL server. 


Database 
The name of the MySQL database. 


UID and PWD 
The user id and password to connect. 


Connection string format 


Here's the format of a typical connection string. 


Driver={MySQL ODBC 5.3 Unicode Driver};Server=<server>;Database=<database>;UID=<user id>;PWD=<password> 


Enter the connection string 


Enter the connection string in the ConnectionString field, or enter the DSN name in the Dsn field, on the 
Choose a Data Source or Choose a Destination page. After you enter the connection string, the wizard 
parses the string and displays the individual properties and their values in the list. 


The following example uses this connection string. 


Driver={MySQL ODBC 5.3 Unicode Driver};Server=127.0.0.1;Database=world;UID=root ; PWD=******** 


Here's the screen that you see after entering the connection string. 





















B SOL Server Import and Export Wizard Ss O xX 
Choose a Data Source | a 
Select the source from which to copy data. r . 
, 
Data source: @ .Net Framework Data Provider for Odbc | 
41/2 
v_ Data 
Driver={MySQL ODBC 5.3 Unicode Driver}:server=127 
Vv Misc 
database world 
server 127.0.0.1 
uid > root 
v Named ConnectionSting 
Dsn 
v_ Secunity 
pwd eeccccses 
v Source 
Driver {MySQL ODBC 5.3 Unicode Driver} 
C ionStri 
The connection string used to connect to the Data Source. 
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Other data providers and more info 


For info about how to connect to MySQL with a data provider that's not listed here, see MySQL connection 
strings. This third-party site also contains more info about the data providers and the connection parameters 
described on this page. 


See also 


Choose a Data Source 
Choose a Destination 


Steps in the SQL Server Import and Export Wizard 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


This topic describes the sequence of steps for importing and exporting data with the SQL Server Import and 
Export Wizard. It also contains links to the individual pages of documentation that describe each page or dialog 


box you see in the wizard. 


This topic describes only the steps in the wizard. If you're looking for something else, see Related tasks and 


content. 


Steps for importing and exporting data 


The following table lists the steps for importing and exporting data and the corresponding pages of the wizard. 
Depending on the options that you select in the wizard, you typically don't see all these pages. 


For a quick look at the several screens you see in a typical session, take a look at this simple end-to-end example 
on a single page - Get started with this simple example of the Import and Export Wizard. 


STEP 


Welcome 
You don't have to take any action on this page. 


Pick the source of the data. 


Pick the destination for the data. 


Configure the destination. (optional steps) 


- Create a new destination database. 
- If you're copying data to a text file, configure additional 
settings. 


Specify what you want to copy. 


Configure the copy operation. (optional steps) 


- Create a new destination table. 

- Decide what to do if the wizard doesn't know how to map 
data types between the source and destination that you 
selected. 


- Review column mappings between source and destination. 


- Handle issues with converting data types between source 
and destination. 
- Preview the data to be copied. 


WIZARD PAGES 


Welcome to SQL Server Import and Export Wizard 


Choose a Data Source 


Choose a Destination 


Create Database 


Configure Flat File Destination 


Specify Table Copy or Query 
Select Source Tables and Views 


Provide a Source Query 


Create Table SQL Statement 

Convert Types without Conversion Checking 
Column Mappings 

Review Data Type Mapping 

Column Conversion Details Dialog Box 


Preview Data Dialog Box 


STEP WIZARD PAGES 


Copy the data. Save and Run Package 


Optionally, save your settings as a SQL Server Integration Save SSIS Package 
Services (SSIS) package. 
Complete the Wizard 


Performing Operation 





TIP 


Tap the F1 key from any page or dialog box of the wizard to see documentation for the current page. 





Related tasks and content 
Here are some other basic tasks. 
See a quick example of how the wizard works. 


o If you prefer to see screen shots. Take a look at this simple end-to-end example on a single 
page - Get started with this simple example of the Import and Export Wizard. 


o If you prefer to watch a video. Watch this four-minute video from YouTube that demonstrates 
the wizard and explains clearly and simply how to export data to Excel - Using the SQL Server 
Import and Export Wizard to Export to Excel. 


Learn more about how the wizard works. 


o Learn more about the wizard. If you're looking for an overview of the wizard, see Import and 
Export Data with the SQL Server Import and Export Wizard. 


o Learn how to connect to data sources and destinations. If you're looking for info about how 
to connect to your data, select the page you want from the list here - Connect to data sources with 
the SQL Server Import and Export Wizard. There's a separate page of documentation for each of 


several commonly used data sources. 


Start the wizard. If you're ready to run the wizard and just want to know how to start it, see Start the 
SQL Server Import and Export Wizard. 


e Get the wizard. If you want to run the wizard, but you don't have Microsoft SQL Server installed on 
your computer, you can install the SQL Server Import and Export Wizard by installing SQL Server Data 
Tools (SSDT). For more info, see Download SQL Server Data Tools (SSDT). 


Welcome to SQL Server Import and Export Wizard 


11/23/2021 * 2 minutes to read « Edit Online 





Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


When you start the SQL Server Import and Export Wizard, the first page is Welcome to SQL Server Import 
and Export Wizard. You don't have to take any action on this page. 





IMPORTANT 


This topic describes only the first page the wizard. If you're looking for something else, see Related tasks and content. 











Prerequisite - Is the wizard installed on your computer? 


If you want to run the wizard, but you don't have Microsoft SQL Server installed on your computer, you can 
install the SQL Server Import and Export Wizard by installing SQL Server Data Tools (SSDT). For more info, see 
Download SQL Server Data Tools (SSDT). 


Screen shot of the Welcome page 


The following screen shot shows the Welcome to SQL Server Import and Export Wizard page of the 


wizard. 





4 SQL Server import and Export Ward 


| 






Welcome to SQL Server |Importand Export 
Wizard 











This wizard helps you to create simple packages that import and export data 
between many popular data formats including databases. spreadsheets. and text 
files, The wizard can also create the destination database and the tables into which 
the date is inserted. 













To move or copy databases and their objects from ome server instance to another. 
cancel this wizard and use the Copy Database Wizard instead. The Copy Database 
Vizard is available in SQL Server Management Studio. 








IF Do not show this starting page again 


_<teck |[Net>] Fish >>) | _ Cancat_| 








Don't show this page again 


Do not show this starting page again. 
Skip the welcome page the next time you run the wizard. 


What's next? 


After the Welcome page, the next page is Choose a Data Source. On this page, you provide info about the 
source of your data and about how to connect to it. For more info, see Choose a Data Source. 


Related tasks and content 
Here are some other basic tasks. 
e See a quick example of how the wizard works. 


o If you prefer to see screen shots. Take a look at this simple end-to-end example on a single 
page - Get started with this simple example of the Import and Export Wizard. 


o If you prefer to watch a video. Watch this four-minute video from YouTube that demonstrates 
the wizard and explains clearly and simply how to export data to Excel - Using the SQL Server 
Import and Export Wizard to Export to Excel. 


e Learn more about how the wizard works. 


o Learn more about the wizard. If you're looking for an overview of the wizard, see Import and 
Export Data with the SQL Server Import and Export Wizard. 


o Learn about the steps in the wizard. If you're looking for info about the steps in the wizard, 
see Steps in the SQL Server Import and Export Wizard. There's also a separate page of 
documentation for each page of the wizard. 


o Learn how to connect to data sources and destinations. If you're looking for info about how 
to connect to your data, select the page you want from the list here - Connect to data sources with 
the SQL Server Import and Export Wizard. There's a separate page of documentation for each of 


several commonly used data sources. 


e Start the wizard. If you're ready to run the wizard and just want to know how to start it, see Start the 
SQL Server Import and Export Wizard. 


e@ Get the wizard. If you want to run the wizard, but you don't have Microsoft SQL Server installed on 
your computer, you can install the SQL Server Import and Export Wizard by installing SQL Server Data 
Tools (SSDT). For more info, see Download SQL Server Data Tools (SSDT). 


Choose a Data Source (SQL Server Import and 


Export Wizard) 
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Applies to: Qsal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


After the Welcome page, the SQL Server Import and Export Wizard displays Choose a Data Source. On this 
page, you provide information about the source of your data and about how to connect to it. 


For info about the data sources that you can use, see What data sources and destinations can | use? 





NOTE 


The SQL Server Import and Export Wizard utilizes SQL Server Integration Services (SSIS). Therefore the same limitations 
that apply to SSIS, also apply to the wizard. For example ErrorCode and ErrorColumn columns, which are added by default 
as described in Error handling in data. 











Screen shot of the Choose a Data Source page 


The following image shows the first part of the Choose a Data Source page of the wizard. The rest of the page 
has a variable number of options which depend on the data source that you choose here. 
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Choose 4 Data Source 
Select the source from which to copy data. 





Choose a data source 


Data source 
Specify the data source by selecting a data provider that can connect to the source. 


e The data provider that you need is typically obvious from its name, because the name of the 
provider typically contains the name of the data source - for example, Flat File Source, Microsoft Exce/, 
Microsoft Access, .Net Framework Data Provider for Sq/Server, .Net Framework Data Provider for Oracle. 


e If you have an ODBC driver for your data source, select the .Net Framework Data Provider for 
ODBC. Then enter the driver-specific info. ODBC drivers aren't listed in the drop-down list of data sources. 
The .Net Framework Data Provider for ODBC acts as a wrapper around the ODBC driver. For more info, 
see Connect to an ODBC Data Source. 


e There may be more than one provider available for your data source. Typically you can select 
any provider that works with your source. For example, to connect to Microsoft SQL Server, you can use 
the .NET Framework Data Provider for SQL Server or the SQL Server ODBC driver. (Other providers are 
also still in the list but are no longer supported.) 


My data source isn't in the list 


e You may have to download the data provider from Microsoft or from a third party. The list of 
available data providers in the Data source list includes only the providers installed on your computer. 
For info about the data sources that you can use, see What data sources and destinations can | use? 


e Do you have an ODBC driver for your data source? ODBC drivers aren't listed in the drop-down 
list of data sources. If you have an ODBC driver for your data source, select the .Net Framework Data 
Provider for ODBC. Then enter the driver-specific info. The Net Framework Data Provider for ODBC acts 
as a wrapper around the ODBC driver. For more info, see Connect to an ODBC Data Source. 


e 64-bit and 32-bit providers. If you're running the 64-bit wizard, you won't see data sources for which 
only a 32-bit provider is installed, and vice versa. 


NOTE 


To use the 64-bit version of the SQL Server Import and Export Wizard, you have to install SQL Server. SQL Server Data 
Tools (SSDT) and SQL Server Management Studio (SSMS) are 32-bit applications and only install 32-bit files, including the 
32-bit version of the wizard. 





After you choose a data source 


After you choose a data source, the rest of the Choose a Data Source page has a variable number of options 
which depend on the data provider that you choose. 


To connect to a commonly used data source, see one of the following pages. 


e Connect to SQL Server 

e Connect to Oracle 

e Connect to flat files (text files) 
e Connect to Excel 

e Connect to Access 

e Connect with ODBC 

e Connect to Azure Blob Storage 
e Connect to PostgreSQL 

e Connect to MySQL 


For info about how to connect to a data source that's not listed here, see The Connection Strings Reference. This 
third-party site contains sample connection strings and more info about data providers and the connection info 
they require. 


What's next? 


After you provide info about the source of your data and about how to connect to it, the next page is Choose a 
Destination. On this page, you provide info about the destination for your data and about how to connect to it. 
For more info, see Choose a Destination. 


See also 


Get started with this simple example of the Import and Export Wizard 


® Get help 


e UserVoice: Have suggestions for improving SQL Server? 





e Microsoft Q & A (SQL Server) 

e DBA Stack Exchange (tag sql-server): Ask SQL Server questions 

e Stack Overflow (tag sql-server): Answers to SQL development questions 
e@ Reddit: General discussion about SQL Server 

e Microsoft SQL Server License Terms and Information 

e Support options for business users 

e Contact Microsoft 

e Additional SQL Server help and feedback 


“ Contribute to SQL documentation 


Did you know that you can edit SQL content yourself? If you do so, not only do you help improve our 
documentation, but you also get credited as a contributor to the page. 


For more information, see How to contribute to SQL Server documentation 


Choose a Destination (SQL Server Import and 


Export Wizard) 
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Applies to: Q sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


After you provide info about the source of your data and about how to connect to it, the SQL Server Import and 
Export Wizard shows Choose a Destination. On this page, you provide info about the destination for your 
data and about how to connect to it. 


For info about the data destinations that you can use, see What data sources and destinations can | use?. 


Screen shot of the Destination page 


The following screen shot shows the first part of the Choose a Destination page of the wizard. The rest of the 
page has a variable number of options which depend on the destination that you choose here. 






4 SQL Server Import and Export Wizard 






Choose a Destination 
Specify where to copy data to. 





Choose a destination 


Destination 


Specify the destination by selecting a data provider that can import data into the destination. 


e The data provider that you need is typically obvious from its name, because the name of the 
provider typically contains the name of the destination - for example, F/at File Destination, Microsoft 
Excel, Microsoft Access, .Net Framework Data Provider for Sq/Server, .Net Framework Data Provider for 
Oracle. 


e If you have an ODBC driver for your destination, select the .Net Framework Data Provider for 
ODBC. Then enter the driver-specific info. ODBC drivers aren't listed in the drop-down list of destinations. 
The .Net Framework Data Provider for ODBC acts as a wrapper around the ODBC driver. For more info, 
see Connect to an ODBC Data Source. 


e There may be more than one provider available for your destination. Typically you can select 
any provider that works with your destination. For example, to connect to Microsoft SQL Server, you can 
use the .NET Framework Data Provider for SQL Server or the SQL Server ODBC driver. (Other providers 
are also still in the list but are no longer supported.) 


My destination isn't in the list 


e You may have to download the data provider from Microsoft or from a third party. The list of 
available data providers in the Destination list includes only the providers installed on your computer. 
For info about the destinations that you can use, see What data sources and destinations can | use? 


e Do you have an ODBC driver for your destination? ODBC drivers aren't listed in the drop-down list 
of destinations. If you have an ODBC driver for your destination, select the .Net Framework Data Provider 
for ODBC. Then enter the driver-specific info. The .Net Framework Data Provider for ODBC acts as a 
wrapper around the ODBC driver. For more info, see Connect to an ODBC Data Source. 


e 64-bit and 32-bit providers. If you're running the 64-bit wizard, you won't see destinations for which 
only a 32-bit provider is installed, and vice versa. 





NOTE 


To use the 64-bit version of the SQL Server Import and Export Wizard, you have to install SQL Server. SQL Server Data 
Tools (SSDT) and SQL Server Management Studio (SSMS) are 32-bit applications and only install 32-bit files, including the 


32-bit version of the wizard. 





After you choose a destination 


After you choose a destination, the rest of the Choose a Destination page has a variable number of options 
which depend on the data provider that you choose. 


To connect to a commonly used destination, see one of the following pages. 


@ Connect to SQL Server 

e Connect to Oracle 

e Connect to flat files (text files) 
e Connect to Excel 

e Connect to Access 

e Connect with ODBC 

e Connect to Azure Blob Storage 
e Connect to PostgreSQL 

e Connect to MySQL 


For info about how to connect to a destination that's not listed here, see The Connection Strings Reference. This 
third-party site contains sample connection strings and more info about data providers and the connection info 
they require. 


What's next? 


After you provide info about the destination for your data and about how to connect to it, the next page is 
Specify Table Copy or Query. On this page, you specify whether you want to copy an entire table or only 
certain rows. For more info, see Specify Table Copy or Query. 


See also 


Get started with this simple example of the Import and Export Wizard 





Create Database (SQL Server Import and Export 
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Applies to: Q sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


If you select New on the Choose a Destination page to create a new SQL Server destination database, the 
SQL Server Import and Export Wizard shows the Create Database dialog box. On this page, you provide a 
name for the new database. Optionally you can also change the settings for the initial size and the automatic 
growth of the new database and its log file. 


The Create Database dialog box in the wizard offers only the basic options that are available for creating a 
new SQL Server database. To see and configure all the options for a new SQL Server database, use SQL Server 
Management Studio to create the database, or to configure the database after the wizard creates it. 


NOTE 
If you're looking for info about the Transact-SQL CREATE DATABASE statement, and not about the Create Database 


dialog box of the SQL Server Import and Export Wizard, see CREATE DATABASE (SQL Server Transact-SQL). 





Screen shot of the Create Database page 


The following screen shot shows the Create Database dialog box of the wizard. 
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Provide a name for the new database 


Name 
Provide a name for the destination SQL Server database. 


Naming requirements 


Make sure that you follow SQL Server naming conventions when you name the database. 


e The database name must be unique within an instance of SQL Server. 


e@ The database name can be a maximum of 123 characters. (This allows 5 characters for the suffixes that 
SQL Server appends to the data file and the log file, within the maximum of 128 characters.) 


e The database name must comply with the rules for identifiers in SQL Server. Here are the most important 
requirements. 


© The first character must be a letter, underscore (_), at sign (@), or number sign (#). 


o Subsequent characters can be letters, numbers, the at sign, dollar sign ($), number sign, or 
underscore. 


o You can't use spaces or other special characters. 


For detailed info about these requirements, see Database Identifiers. 


Optionally specify data file and log file options 





TIP 


You have to provide a name for the new database in the Name field, but typically you can leave the other settings for file 
size and file growth at their default values. 











Data file options 


Initial size 


Specify the number of megabytes for the initial size of the data file. 


No growth allowed 
Indicate whether the data file can grow beyond the specified initial size. 


Grow by percentage 
Specify a percentage by which the data file can grow. 


Grow by size 
Specify a number of megabytes by which the data file can grow. 


Log file options 
Initial size 


Specify the number of megabytes for the initial size of the log file. 


No growth allowed 
Indicate whether the log file can grow beyond the specified initial size. 


Grow by percentage 
Specify a percentage by which the log file can grow. 


Grow by size 
Specify a number of megabytes by which the log file can grow. 


More info 


For more info about the file size options that you see on this page, see CREATE DATABASE (SQL Server Transact- 
SQL). 


What's next? 


After you provide a name for the new database that the wizard will create and click OK, the Create Database 
dialog box returns you to the Choose a Destination page. For more info, see Choose a Destination. 


Specify Table Copy or Query (SQL Server Import 


and Export Wizard) 
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Applies to: Q sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


After you provide info about the destination for your data and about how to connect to it, the SQL Server 
Import and Export Wizard shows Specify Table Copy or Query. On this page, you choose one of the 
following options. 


e Copy data from one or more tables or views. You want to pick a table or tables from a list. 


e Write a query to specify the data to transfer. You want to enter or paste in the text of a SQL query. 





TIP 


If you have to copy more than one database, or database objects other than tables and views, use the Copy Database 
Wizard instead of the Import and Export Wizard. For more info, see Use the Copy Database Wizard. 











Screen shot of the Specify Table Copy or Query page 


The following screen shot shows the Specify Table Copy or Query page of the Wizard. 
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Specify whether to copy an entire table or write a query 


Copy data from one or more tables or views 
Select this option if you want to copy data from the source without filtering or sorting records. 


When you select Copy data from one or more tables or views, you can copy from one table or view to one 
destination table, or from multiple tables or views to multiple destination tables. 


After you click Next, you select the tables to copy on the Select Source Tables and Views page. For more 
info, see Select Source Tables and Views. 


Write a query to specify the data to transfer 
Select this option if you want to filter or sort the source data before you copy it to the destination. 


When you select Write a query to specify the data to transfer, you can only copy the results of one query 
to one destination table. 


After you click Next, you provide a SQL statement to specify columns and select rows in the Provide a Source 
Query dialog box. For more info, see Provide a Source Query. 


Why isn't the Copy option available? 


The Copy data from one or more tables or views option may not be available when the wizard uses a .NET 
Framework data provider to connect to your data source. This happens when the wizard doesn't have enough 
info about the data provider to request a list of tables and views from the data source. 


You can still use the Write a query option, even if you don't typically write SQL queries, as long as you know 
the name of the table that you want to export. In the Provide a Source Query dialog box, which you see after 
you click Next, enter the query as SELECT * FROM <name of table> . If the name of the table contains spaces or 
other special characters, surround the name with square brackets - SELECT * FROM [<name of table>] . 


More info 


The Copy data from one or more tables or views option is available only for those providers that have a 
ProviderDescription section in the ProviderDescriptors.xml file. (By default, this file is in <drive>:\Program 
Files\Microsoft SQL Server\130\DTS\ProviderDescriptors.) Each ProviderDescription section in this file contains 
the information that's required to retrieve metadata from the corresponding provider. 


By default, the ProviderDescriptors.xml file contains a ProviderDescription section only for the providers in the 
following list. 


e .Net Framework Data Provider for SQL Server (System.Data.SqlClient) 
e .Net Framework Data Provider for Oracle (System.Data.OracleClient) 
e Net Framework Data Provider for ODBC (System.Data.Odbc) 

e System.Data.OleDb (which applies to all OLE DB providers) 


e Microsoft Provider for DB2 installed by Microsoft Host Integration Server 
(Microsoft.HostIntegration.MsDb2Client.MsDb2Connection) 


Third-party developers can make the Copy data from one or more tables or views option available for 
their provider by adding a ProviderDescriptor section to the ProviderDescriptors.xml file. To review the 
requirements for the ProviderDescriptor section, see the ProviderDescriptors.xsd schema file which by default is 
in the same folder as the ProviderDescriptors.xml file. 


What's next? 


After you specify whether you want to copy an entire table or provide a query, the next page depends on the 
option that you chose on this page and also on the destination for your data. 


e If you selected Copy data from one or more tables or views, for most destinations the next page is 
Select Source Tables and Views. On this page, you select the existing tables and views to copy from 
the data source to the destination. For more info, see Select Source Tables and Views. 


e If you selected Copy data from one or more tables or views and your destination is a flat file, the 


next page is Configure Flat File Destination. On this page, you specify formatting options for the 
destination flat file. (Then, after you configure the flat file, the following page is Select Source Tables 


and Views.) For more info, see Configure Flat File Destination. 


e If you selected Write a query to specify the data to transfer, the next page is Provide a Source 
Query. On this page, you write and test the SQL statement that selects the data to copy from the data 
source to the destination. (Then, after you provide a query, the following page is Select Source Tables 


and Views.) For more info, see Provide a Source Query. 


See also 


Get started with this simple example of the Import and Export Wizard 


Provide a Source Query (SQL Server Import and 


Export Wizard) 
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Applies to: Q sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


If you specified that you want to provide a query to select the data to copy, the SQL Server Import and Export 
Wizard shows Provide a Source Query. On this page, you write and test the SQL query that selects the data 
to copy from the data source to the destination. You can also paste the text of a saved query, or load the query 
text from a file. 


Screen shot of the Source Query page 
The following screen shot shows the Provide a Source Query page of the Wizard. 


In this simple example, the user has entered the query SELECT * FROM Sales.Customer to copy all rows and all 
columns from the Sales.Customer table in the source database. 


@ SELECT * means copy all columns. 


e@ The absence of a wHERE clause means copy all rows. 
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Provide the query and check its syntax 


SQL statement 


Type a SELECT query to retrieve specific rows and columns of data from the source database. You can also paste 
the text of a saved query, or load the query from a file by clicking Browse. 


For example, the following query retrieves the SalesPersonID, SalesQuota, and SalesYTD from the 
AdventureWorks sample database for sales persons whose commission percentage is more than 1.5 percent. 


SELECT SalesPersonID, SalesQuota, SalesYTD 
FROM Sales.SalesPerson 
WHERE CommissionPct > 0.015 


For more examples of SELECT queries, see SELECT Examples (Transact-SQL) or search online. 


If your data source is Excel, see Provide a source query for Excel later in this topic to learn how to specify Excel 
worksheets and ranges in a query. 


Parse 
Check the syntax of the SQL statement that you entered in the SQL statement text box. 





NOTE 


If the time that's required to check the syntax of the statement exceeds the timeout value of 30 seconds, parsing stops 
and raises an error. You won't be able to move past this page of the wizard until parsing succeeds. One solution to avoid a 
timeout is to create a database view based on the query that you want to use, and then to query the view from the 
wizard, instead of entering the query text directly. 





Browse 
Select a saved file that contains the text of a SQL query by using the Open dialog box. Selecting a file copies the 
text from the file into the SQL statement text box. 


Provide a source query for Excel 








IMPORTANT 


For detailed info about connecting to Excel files, and about limitations and known issues for loading data from or to Excel 


files, see Load data from or to Excel with SQL Server Integration Services (SSIS). 











There are three types of Excel objects that you can query. 


e Worksheet. To query a worksheet, append the $ character to the end of the sheet name and add 
delimiters around the string - for example, [Sheet1 $]. 


SELECT * FROM [Sheet1$] 
e Named range. To query a named range, simply use the range name - for example, MyDataRange. 
SELECT * FROM MyDataRange 


e Unnamed range. To specify a range of cells that you haven't named, append the $ character to the end 
of the sheet name, add the range specification, and add delimiters around the string - for example, 
[Sheet1$A1:B4]. 


SELECT * FROM [Sheet1$A1:B4] 


What's next? 


After you write and test the SQL query that selects the data to copy, the next page depends on the destination 
for your data. 


e For most destinations the next page is Select Source Tables and Views. On this page, you review the 
query that you provided and optionally choose columns to copy and preview sample data. For more info, 


see Select Source Tables and Views. 


e If your destination is a flat file, the next page is Configure Flat File Destination. On this page, you 
specify formatting options for the destination flat file. (After you configure the flat file, the next page is 
then Select Source Tables and Views.) For more info, see Configure Flat File Destination. 


Select Source Tables and Views (SQL Server Import 


and Export Wizard) 


11/23/2021 * 5 minutes to read * Edit Online 





Applies to: Q sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


After you specify that you want to copy an entire table, or after you provide a query, the SQL Server Import and 

Export Wizard shows Select Source Tables and Views. On this page, you select the existing tables and views 

that you want to copy. Then you map the source tables to new or existing destination tables. Optionally, you also 
review the mapping of individual columns and preview sample data. 





TIP 


If you have to copy more than one SQL Server database, or SQL Server database objects other than tables and views, use 
the Copy Database Wizard instead of the Import and Export Wizard. For more info, see Use the Copy Database Wizard. 











Screen shot - If you're going to copy tables 


The following screen shot shows an example of the Select Source Tables and Views page of the wizard when 
you previously selected the Copy data from one or more tables or views option on the Specify Table 
Copy or Query page. In the list you see all the tables and views available from the data source. 


In this example, the Source list contains all the tables in the AdventureWorks sample database. The selected row 
shows that the user wants to copy the Sales.Customer table from the source to the new Sales.CustomerNew 


table at the destination. 
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Screen shot - If you provided a query 


The following screen shot shows an example of the Select Source Tables and Views page of the wizard when 


you previously selected the Write a query to specify the data to transfer option on the Specify Table 
Copy or Query page. The Source list contains only a single row, where the item named [Query] represents 


the query that you provided on the Provide a Source Query page. 


In this example, the user wants to copy the query results from the source to the Sales.CustomerNew table at 


the destination. 
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Select source and destination tables 


Source 

Using the check boxes, select from the list of available tables and views to copy to the destination. By default, 
data from the data source is copied without changes. If you create a new destination table, the schema for the 
new table - that is, the list of columns and their properties - is also copied without change from the data source. 


If you provided a query, the list contains only one item with the name [Query] . 


Destination 
Select a destination table from the list for each source table or query, or enter the name of a new table that you 
want the wizard to create. If you select an existing destination table, the table has to have columns with data 


types that are compatible with the source data. 


NOTE 

If you pause at this point in the wizard to create a new table manually in the destination database by using an external 
tool (such as SQL Server Management Studio), the new table is not immediately visible in the list of available destination 
tables. To refresh the list of destination tables, step back to the Choose a Destination page, re-select the destination 
database to refresh the list of available tables and views, and then step forward again to the Select Source Tables and 


Views page. 





Optionally, review column mappings and preview data 


Edit mappings 
Optionally, click Edit mappings to display the Column Mappings dialog box for the selected table. Use the 
Column Mappings dialog box to do the following things, 





e Review the mapping of individual columns between the source and the destination. 


e Copy only a subset of columns by selecting ignore for columns that you don't want to copy. 
For more info, see Column Mappings. 


Preview 
Optionally, click Preview to preview up to 200 rows of sample data in the Preview Data dialog box. This 
confirms that the wizard is going to copy the data that you want to copy. For more info, see Preview Data. 


After you preview the data, you may want to change the options that you selected on previous pages of the 
wizard. To make these changes, return to the Select Source Tables and Views page, and then click Back to 
return to previous pages where you can change your selections. 


Select source and destination tables for Excel 





IMPORTANT 


For detailed info about connecting to Excel files, and about limitations and known issues for loading data from or to Excel 


files, see Load data from or to Excel with SQL Server Integration Services (SSIS). 








Excel source tables 


The list of source tables and views for an Excel data source includes two types of Excel objects. 


e Worksheets. Worksheet names are followed by the dollar sign ($) - for example, ‘Sheet $'. 


e Named ranges. Named ranges, if any, are listed by name. 


If you want to load data from or to a specific, unnamed range of cells - for example, from or to 
[Sheet1$A1:B4], you have to write a query. Step back to the Specify Table Copy or Query page and select 
Write a query to specify the data to transfer. 


Excel destination tables 


If you are exporting data to Excel, you can specify the destination in one of the following three ways. 


e Worksheet. To specify a worksheet, append the $ character to the end of the sheet name and add delimiters 
around the string - for example, [Sheet1$]. 

e Named range. To specify a named range, simply use the range name - for example, MyDataRange. 

e Unnamed range. To specify a range of cells that you haven't named, append the $ character to the end of 
the sheet name, add the range specification, and add delimiters around the string - for example, 
[Sheet1$A1:B4]. 


TIP 


When you're using Excel as a source or destination, it's a good idea to click Edit Mappings and to review the data type 


mappings on the Column Mappings page. 





What's next? 


After you select the existing tables and views to copy and map them to their destinations, the next page is Save 
and Run Package. On this page, you specify whether you want to run the copy operation immediately. 
Depending on your configuration, you may also be able to save the SQL Server Integration Services package 
created by the wizard to customize it and to reuse it later. For more info, see Save and Run Package. 


See also 


Get started with this simple example of the Import and Export Wizard 
Load data from or to Excel with SQL Server Integration Services (SSIS) 


Configure Flat File Destination (SQL Server Import 


and Export Wizard) 


11/23/2021 + 2 minutes to read * Edit Online 





Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


If you selected a flat file destination, the SQL Server Import and Export Wizard shows Configure Flat File 
Destination after you specify that you want to copy a table or after you provide a query. On this page, you 
specify formatting options for the destination flat file. Optionally, you review the mapping of individual columns 
and preview sample data. 


Screen shot of the Configure Flat File Destination page 
The following screen shot shows an example of the Configure Flat File Destination page of the wizard. 


In this example, the user has specified the following options to create a typical CSV (comma-separated values) 
file. 


e Row delimiter. Each row of data in the output ends with a carriage return-line feed combination. 


e Column delimiter. Columns of data within each row are separated with a comma. 
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Pick a source table 


Source table or view 


e If you specified on a previous page that you want to copy a table, select the source table or view from the 
drop-down list. 


e If you provided a query, "Query" is selected and is the only option. 


Specify row and column delimiters for the output 


Row delimiter 


Select from the list of delimiters to separate rows in the output. There is no option to specify a custom row 


delimiter. 
VALUE DESCRIPTION 
{CR}{LF} Delimit rows with a carriage return-line feed combination. 
{CR} Delimit rows with a carriage return. 
{LF} Delimit rows with a line feed. 
Semicolon {;} Delimit rows with a semicolon. 
Colon {:} Delimit rows with a colon. 
Comma {,} Delimit rows with a comma. 
Tab {t} Delimit rows with a tab. 
Vertical bar {|} Delimit rows with a vertical bar. 


Column delimiter 
Select from the list of delimiters to separate columns in the output. There is no option to specify a custom 
column delimiter. 


VALUE DESCRIPTION 

{CR}{LF} Delimit columns with a carriage return-line feed 
combination. 

{CR} Delimit columns with a carriage return. 

{LF} Delimit columns with a line feed. 

Semicolon {;} Delimit columns with a semicolon. 

Colon {:} Delimit columns with a colon. 

Comma {,} Delimit columns with a comma. 

Tab {t} Delimit columns with a tab. 

Vertical bar {|} Delimit columns with a vertical bar. 


Optionally, review column mappings and preview data 


Edit mappings 
Optionally, click Edit mappings to display the Column Mappings dialog box for the selected table. Use the 
Column Mappings dialog box to do the following things. 


e Review the mapping of individual columns between the source and the destination. 


e Copy only a subset of columns by selecting ignore for columns that you don't want to copy. 


For more info, see Column Mappings. 


Preview 
Optionally, click Preview to preview up to 200 rows of sample data in the Preview Data dialog box. This 
confirms that the wizard is going to copy the data that you want to copy. For more info, see Preview Data. 


After you preview the data, you may want to change the options that you selected on previous pages of the 
wizard. To make these changes, return to the Configure Flat File Destination page, and then click Back to 


return to previous pages where you can change your selections. 


What's next? 


After you specify formatting options for the destination flat file, the next page is Save and Execute Package. 
On this page, you specify whether you want to run the operation immediately. Depending on your configuration, 
you may also be able to save your settings as a SQL Server Integration Services package to customize it and to 
reuse it later. For more info, see Save and Run Package. 


Convert Types without Conversion Checking (SQL 


Server Import and Export Wizard) 


11/23/2021 + 2 minutes to read * Edit Online 





Applies to: Q sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


After you select the existing tables and views to copy or review the query that you provided, the SQL Server 
Import and Export Wizard may show Convert Types without Conversion Checking. The wizard shows this 
page when it can't locate one or more of the data type conversion and mapping files that it needs to map data 
types between your source and destination. The page includes information that helps you to understand what's 
missing. 


Click Next to continue without knowing whether data type conversions will succeed. Otherwise, click Back to 
change your selections, or click Cancel to exit the wizard. 


Screen shot of the Convert Types page 


The following screen shot shows an example of the Convert Types without Conversion Checking page of 
the Wizard. 
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The problem here is that the wizard can't find a mapping file that maps data types for the destination you 
selected. 


The info on this page doesn't include the name of the missing mapping file. Since the wizard doesn't know 
whether a file exists for the specified data provider, it can't provide a name for the missing file. 


What's next? 


After you click Next to continue without knowing whether data type conversions will succeed, the next page is 
Save and Run Package. On this page, you specify whether you want to run the copy operation immediately. 
Depending on your configuration, you may also be able to save the SQL Server Integration Services package 


created by the wizard to customize it and to reuse it later. For more info, see Save and Run Package. 


See also 


Data Type Mapping in the SQL Server Import and Export Wizard 


Column Mappings (SQL Server Import and Export 


Wizard) 
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Applies to: Q sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


After you select the existing tables and views to copy or review the query that you provided, if you click Edit 
mappings, the SQL Server Import and Export Wizard shows the Column Mappings dialog box. On this page 
you specify and configure destination columns to receive the data copied from the source columns. Often you 
don't have to change anything on this page. 


If you don't want to copy all the columns in the table you selected, one thing you can do on this page is exclude 
the columns you don't want. Select ignore in the Destination column of the Mappings list for columns that 


you don't want to copy. 


Screen shot of the Column Mappings page 


The following screen shot shows an example of the Column Mappings dialog box of the wizard. 


In this example, you see that the wizard is going to create a new destination table, because Create destination 
table is selected. By default, the wizard gives each column in the new destination table the same name, data 


type, and properties as the corresponding source column. 
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Source column CustomerID int NOT NULL 








Review the source and destination 






Column Mappings 


Source: “Sales” "Customer 

Destinabon "Sales*."“CustomerNew" 

@ Create destination table Edit SQL 

£3 T~ Drop and re-create destination table 


Source column CustomerID int NOT NULL 





Source 


The selected source table, view, or query. 


Destination 
The selected destination table or view. 


Optionally, create a new destination table 
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Source column CustomerID int NOT NULL 








Create destination table/file 
Create the destination table if it does not already exist. 


Edit SQL 

Click Edit SQL to open the Create Table SQL Statement dialog box. Use the autogenerated CREATE TABLE 
statement, or modify it for your purposes. If you change this statement manually, you have to make sure that the 
list of column mappings recognizes your changes. For more info, see Create Table SQL Statement. 


Sometimes these options are disabled 


The Create destination table/file option and the Edit SQL button are either automatically enabled or 
automatically disabled. 


e Enabled. If you specified a new destination table on the Select Source Tables and Views page, the 
Create destination table option is automatically selected and the Edit SQL button is enabled. 


e Disabled. If you selected an existing destination table on the Select Source Tables and Views page, 
the Create destination table option and the Edit SQL button are disabled. If you want to create a new 
destination table, go back to the Select Source Tables and Views page and enter the name of anew 


table in the Destination column. 


What about existing data in the destination? 
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Mappings 

Source Destination Type Nulable | Size Precision | Scale | 

CustomerID CustomeriD nt Cc 

PersoniD PessoniID nm Vv 

StoreiD StorelD nm Vv 

TemtoryiD Temtory!D rm \v 

AccountNumber  AccountNumber = varchar rc 10 

rowguid ftowguid uniqueidertifier 

ModfiedDate ModfiedDate dmetme 0 3 
Source column CustomerID int NOT NULL 


OK Cancel 








Delete rows in destination table/file 
Specify whether to clear the data from an existing table before loading the new data. 


Append rows to destination table/file 
Specify whether to append the new data to the data already present in an existing table. 


Drop and re-create destination table 


Choose this option to overwrite the destination table. This option is only available when you used the wizard to 


create the destination table. The destination table is only dropped and re-created if you save the package that 
the wizard creates and then run the package again. This is a convenient option when you want to test your 


settings more than once. 


Enable identity insert 
Choose this option to allow existing identity values in the source data to be inserted into an identity column in 
the destination table. By default, the destination identity column typically does not allow this. 





TIP 
If your existing primary keys are in an identity column, an autonumber column, or the equivalent, you typically have to 
select this option to keep your existing primary key values. Otherwise the destination identity column typically assigns 


new values. 











Keep your autonumber or identity values 


If you're exporting data that has an autonumber column or an identity column - for example, if you're exporting 


from Microsoft Access - make sure you select Enable identity insert as described immediately above. 


Review column mappings 
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Source: "Sales”."Customer™ 
Destinaton: "Sales”."CustomerNew" 
@ Create destination table Edit SQL 
Cc I~ Drop and re-create destination table 
c I Enable identity insert 


CustomerID int NOT NULL 











Mappings 
Displays how each column in the data source maps to a column in the destination. 


The Mappings list has the following columns. 


e Source 


View each source column. 


e Destination 
View the mapped destination column or select a different column. 


You don't have to copy all the columns from the source table. Select ignore in this column for columns 
that you want to skip. Before you map columns, you must ignore all columns that will not be mapped. 


e Type 
View the data type for the destination column or select a different data type. 


e Nullable 
Specify whether the destination column allows a null value. 


e Size 
Specify the number of characters in the destination column, if applicable. 


e Precision 
Specify the precision of numeric data in the destination column - that is, the number of digits - if 
applicable. 


e Scale 
Specify the scale of numeric data in the destination column - that is, the number of decimal places - if 
applicable. 


What's next? 


After you review and configure destination columns to receive the data copied from the source columns and 
click OK, the Column Mappings dialog box returns you to the Select Source Tables and Views page or to 
the Configure Flat File Destination page. For more info, see Select Source Tables and Views or Configure Flat 


File Destination. 


If you specified a mapping that may not succeed in the Mappings list, then the Column Mappings dialog box 
takes you to the Review Data Type Mapping page. On this page, you review the warnings, specify conversion 
options, and also specify how to handle errors. For more info, see Review Data Type Mapping. 


See also 


Data Type Mapping in the SQL Server Import and Export Wizard 
Get started with this simple example of the Import and Export Wizard 


Data Type Mapping in the SQL Server Import and 


Export Wizard 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


In the SQL Server Import and Export Wizard, you can set the name, the data type, and the data type properties 
of columns in new destination tables and files, but you can't specify custom conversions for column values. As a 
result, the built-in mapping of data types from source to destination is important. 


How does the wizard map data types between source and 
destination? 


The wizard uses mapping files that are installed by SQL Server Integration Services to map data types from one 
database system or version to another. For example, it can map from SQL Server data types to Oracle data types. 
By default, the mapping files in XML format are installed in the following folders. 


e C:\Program Files\Microsoft SQL Server\130\DTSMappingFiles\ (for 64-bit) 
e C:\Program Files (x86)\Microsoft SQL Server\130\DTSMappingFiles\ (for 32-bit). 


If you edit an existing mapping file, or add a new mapping file to the folder, you have to close and reopen the 
SQL Server Import and Export Wizard or SQL Server Data Tools (SSDT) to load the new or changed mapping 
file. 


You can change an existing mapping file 


If your business requires different mappings between data types, you can update the mapping files to change 
the mappings used by the wizard. For example, if you want the SQL Server nchar data type to map to the DB2 
GRAPHIC data type instead of the DB2 VARGRAPHIC data type when you transfer data from SQL Server to 
DB2, you can change the nchar mapping in the SqiClientToIBMDB2.xml mapping file to use GRAPHIC 
instead of VARGRAPHIC. 


You can add a new mapping file 


Integration Services installs mappings between many commonly used combinations of source and destination. 
You can also add new mapping files to the MappingFiles directory to support additional sources and 
destinations. The new mapping files must conform to the published XSD schema and must map between a 
unique combination of source and destination. The schema for mapping files, DataTypeMapping.xsd, is 
published here. 


Sample mapping file 


Here's a portion of the XML mapping file that maps from SQL Server data types (or, more specifically, from the 
data types used by the Net Framework Data Provider for SQL Server) to Oracle data types. As one example, you 
can see that a SQL Server int data type maps to an Oracle INTEGER data type. 


<dtm: DataTypeMappings 
xmlns:dtm="https://www.microsoft.com/SqlServer/Dts/DataTypeMapping. xsd" 
xmlns:xsi="http: //www.w3.org/2001/XMLSchema-instance" 
SourceType="System.Data.SqlClient.SqiConnection" 
MinSourceVersion="*" 
MaxSourceVersion="*" 
DestinationType="MSDAORA; OraOLEDB.Oracle;System.Data.OracleClient.OracleConnection" 
MinDestinationVersion="08.*" 
MaxDestinationVersion="*"> 


<!-- smallint --> 
<dtm:DataTypeMapping > 
<dtm: SourceDataType> 
<dtm: DataTypeName>smallint</dtm:DataTypeName> 
</dtm:SourceDataType> 
<dtm:DestinationDataType> 
<dtm:SimpleType> 
<dtm: DataTypeName>INTEGER</dtm:DataTypeName> 
</dtm:SimpleType> 
</dtm:DestinationDataType> 
</dtm: DataTypeMapping> 


<lainice > 
<dtm:DataTypeMapping > 
<dtm: SourceDataType> 
<dtm: DataTypeName>int</dtm:DataTypeName> 
</dtm: SourceDataType> 
<dtm:DestinationDataType> 
<dtm:SimpleType> 
<dtm: DataTypeName>INTEGER</dtm: DataTypeName> 
</dtm:SimpleType> 
</dtm:DestinationDataType> 
</dtm: DataTypeMapping> 


</dtm: DataTypeMappings> 


Review Data Type Mapping (SQL Server Import 


and Export Wizard) 
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Applies to: Q sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


If you specified a data type mapping that may not succeed in the Mappings list of the Column Mappings 
dialog box, the SQL Server Import and Export Wizard shows the Review Data Type Mapping page. On this 
page, you review detailed information about data type conversions that the wizard has to perform to make the 
source data compatible with the destination. This information includes visual cues to distinguish data type 
conversions that are expected to succeed from conversions that may cause errors or truncations. For each 
conversion, you decide whether to accept the conversion that the wizard suggests, and you specify how to 
handle any errors that may occur. 


TIP 


You can't change data type mappings on the Review Data Type Mapping page. However, you can click Back to return 
to the Select Source Tables and Views page, and then click Edit Mappings to open the Column Mappings dialog 
box again. In the Column Mappings dialog box, you can specify data type mappings that are more likely to succeed. To 
take another look at the Column Mappings dialog box, see Column Mappings. 








Screen shot of the Review Data Type Mapping page 
The following screen shot shows an example of the Review Data Type Mapping page of the wizard. 


In this example: 


e The user has specified a mapping in the Column Mappings dialog box that may not succeed. 

e The warning icon on the row in the Table list indicates that there is a problem converting at least one column 
of data from the query results to a compatible data type in the destination table. 

e@ The warning icon on the first row in the Data type mapping list indicates that the mapping from the int 


data type of the source column to the smalldatetime data type of the destination column may cause a loss 
of data. 





4 SQL Server import and Export Wizard - o x 


CONVETSION ISSUES. 


Review Dete Type —~ 
Select table to review how its data types map to those in the destination and how it handles RY 
& 











int 
@ PersoniD in PersoniD ; ; : r 
@ Sore = Sarid re _ [Potential lost conversion from int to smalidateti 
@ Temteryid int TemtoryID nt 
@ AccourtNun varchar AccourtNum varchar 
Oo mwa uniqueidentfier  rowguid uniqueidentifier 
@ ModfiedDate datetime ModfiedDate datetime 


To view conversion details, double-click the row that contains the column source type to be converted. 





On Error (global) Fal ~ 
On Truncation (global) Fal 7 
__ Help _| <Back |[Net> fist) | Concet_| 





Review the source and destination tables 


The upper section of the Review Data Type Mapping page is a Table list that lists the tables to be copied from 
the source to the destination. To see conversion information about an individual table, select a table in the Table 
list. The conversion information for the individual columns of the selected table appears in the lower part of the 


page in the Data type mapping grid. 


In this example, the results of the query that the user provided will be copied to the Sales.CustomerNew2 table 
at the destination. The warning icon indicates that there is a problem converting at least one column of data 
from the query results to a compatible data type in the destination table. 








The following table describes the columns in the Table list. 
COLUMN DESCRIPTION 


(Source icon) Indicates the probability of success for the data type 
conversions: 
- Agreen check mark icon indicates that the wizard expects 
all data type conversions for this table to succeed. 
- Ayellow warning icon indicates that you should review 
the individual conversions that the wizard will perform. To 
review these conversions, select the table, and then review 
the conversions for individual columns in the Data type 
mapping list. 
- Ared error icon indicates that the wizard is not able to 
perform some of the conversions for this table reliably. 


Source The name of the source table. 


COLUMN 


(Destination icon) 


Destination 


Review the data type mappings 


DESCRIPTION 


Indicates whether the destination already exists or will be 
created by the wizard: 

- A table icon indicates that the destination is an existing 
table. 

- A table icon with a sunburst indicates that the destination 
is a new table that the wizard will create. 


The name of the destination table. 


The middle section of the Review Data Type Mapping page is the Data type mapping list. This grid 


provides detailed conversion information about the columns in the source table that's selected in the Table list 


in the upper part of the page. 


In this example, each column at the source will be copied to a column with the same name and data type at the 


destination. The warning icon on the first row in the Data type mapping list indicates that the mapping from 


the int data type of the source column to the smalldatetime data type of the destination column may cause a 


loss of data. 


Data type mapping: 





== int 

PersoniD int 

Store!D int 

TemtoryiD int 
AccourtNum varchar 
rowguid uniqueidertfier 
ModfiedDate datetime 


Seeeoececse 





To view conversion details, double-click the row that contains the column source type to be converted 


Customer! 
PersoniD 
StorelD 
TemtoryID 
Account Num, 
rowgud 
ModfiedDate 


Source Type Destination Co ee me On Truncati 


== Use Global 





—— lost conversion from int to smaiidateti 


The following table describes the columns in the Data type mapping list. 


COLUMN 


(Conversion icon) 


Source Column 


Source Type 


Destination Column 


Destination Type 


DESCRIPTION 


Indicates the probability of success for the data type 
conversions: 

- Agreen check mark icon indicates that the wizard expects 
the data type conversion for this column to succeed. 

- Ayellow warning icon indicates that you should review 
the conversion that the wizard will perform. To review the 
conversion, double-click on the column to view the Column 
Conversion Details dialog box. For more info, see Column 
Conversion Details Dialog Box. 

- Ared error icon indicates that the wizard is not able to 
perform the conversion reliably. 


The name of the source column. 


The data type of the source column. 


The name of the destination column. 


The data type of the destination column. 


COLUMN DESCRIPTION 


Convert Specify whether to continue with the planned conversion: 
- Select the check box to have the wizard continue with the 
planned conversion. 
- Clear the check box to cancel the data type conversion. 


On Error Specify how the wizard handles errors: 
- Use the On Error (global) setting, which you can specify 
at the bottom of this page. 
- Fail with an error, and stop the import or export process. 
- Ignore the error. 


On Truncation Specify how the wizard handles truncation: 
- Use the On Truncation (global) setting, which you can 
specify at the bottom of this page. 
- Fail with an error, and stop the import or export process 
- Ignore the truncation. 





TIP 
To see detailed information about the conversion of a particular column of data, double-click any row in the list. The 
Column Conversion Details dialog box opens and displays more detailed conversion information for the column. For 


more info, see Column Conversion Details Dialog Box. 





Specify global error handling options 


The lower section of the Review Data Type Mapping page lets you specify error handling options that apply 
by default to all columns. These settings apply to all conversions that have Use Global selected in the On Error 
or On Truncation columns of the Data type mapping list. 


This example shows the default values for the two global error handling options. 


On Error (global) Fal v 
On Truncation (global) Fal - 


On Error (global) 
Specify how the wizard handles errors: 


e Fail with an error, and stop the import or export process. This is the default value. 


@ Ignore the error, and continue the import or export process. 


On Truncation (global) 
Specify how the wizard handles data truncation: 


e Fail with an error, and stop the import or export process. This is the default value. 


e Ignore the truncation, and continue the import or export process. 


What's next? 


After you review the warnings, specify conversion options, and specify how to handle errors, the Review Data 
Type Mapping page takes you back to the Column Mappings dialog box. For more info, see Column 
Mappings. 





See also 


Data Type Mapping in the SQL Server Import and Export Wizard 


Column Conversion Details Dialog Box (SQL Server 


Import and Export Wizard) 


11/23/2021 + 2 minutes to read * Edit Online 





Applies to: Q sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


If you double-click the row for an individual column on the Review Data Type Mapping page, the SQL Server 
Import and Export Wizard shows the Column Conversion Details dialog box. On this page you can review 
detailed conversion information for an individual column. This information includes the following items. 


e The data type of the column at the source and the destination. 
e The data type conversion that the wizard will perform, if a conversion is required. 


e The data type mapping files that the wizard uses to determine the required data type conversion. 


Screen shot of the Column Conversion Details page 


The following screen shot shows the Column Conversion Details dialog box of the Wizard after the user has 
double-clicked on a row on the Review Data Type Mapping page. To take another look at the Review Data 
Type Mapping page, see Review Data Type Mapping. 


In this example, you see the following things. 


e@ The Persontp column in the source SQL Server table is of type int . The wizard maps this type to the SQL 
Server Integration Services (SSIS) pt_14 data type, which is a four-byte signed integer, by referring to the 
data type mapping file MSSQLToSSIS10.xml. 

e@ The Person1p column in the destination SQL Server table is also of type int . The wizard maps this type to 
the same SSIS data type. 


e The wizard concludes, 7his column does not need conversion. 






a Column Conversion Details - 


Review the conversion information for the selected column. 





What's next? 


After you review the column conversion details and click OK, the Column Conversion Details dialog box 


returns you to the Review Data Type Mapping page. For more info, see Review Data Type Mapping. 


See also 


Data Type Mapping in the SQL Server Import and Export Wizard 


Create Table SQL Statement (SQL Server Import 


and Export Wizard) 
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Applies to: Q sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


If you select Create destination table and then select Edit SQL in the Column Mappings dialog box, the 
SQL Server Import and Export Wizard shows the Create Table SQL Statement dialog box. On this page, you 
review and optionally customize the CREATE TABLE command that the wizard will run to create the new 
destination table. 





NOTE 


If you're looking for info about the Transact-SQL CREATE TABLE statement, and not about the Create Table SQL 
Statement dialog box of the SQL Server Import and Export Wizard, see CREATE TABLE (Transact-SQL). 











Screen shot of the Create Table SQL Statement page 


The following screen shot shows the Create Table SQL Statement dialog box of the Wizard. 


In this example, the SQL statement box contains the default CREATE TABLE statement generated by the 
wizard. This statement creates a new destination table named Person.AddressNew that's a copy of the 
Person.Address source table. 


4 Create Table SQL Statement x 


You can customize the default CREATE TABLE statement. However, after you 
have customized the statement. you must manually maintain any subsequent 
changes to the column mappings by editing the statement. 








Review or regenerate the CREATE TABLE statement 


SQL statement 
Displays the auto-generated SQL statement and lets you customize it. 


If you change the default CREATE TABLE command, you may also have to make changes to the associated 
column mappings when you return to the Column Mappings dialog box. 


To include a carriage return in the text of the SQL statement, press CTRL+ENTER. If you press ENTER alone, the 
dialog box closes. 


For more info about the CREATE TABLE statement and syntax, see CREATE TABLE (Transact-SQL). 


Autogenerate 
Restore the default SQL statement, if you've changed it, by clicking Auto Generate. 


Create a table that includes a FILESTREAM column 


The SQL Server Import and Export Wizard generates a default CREATE TABLE statement based on the connected 
data source. This default CREATE TABLE statement does not include the FILESTREAM attribute even if the source 
table has a FILESTREAM column. 


1. To copy a FILESTREAM column by using the wizard, first implement FILESTREAM storage on the destination 
database. 


2. Then, add the FILESTREAM attribute manually to the CREATE TABLE statement in the Create Table SQL 
Statement dialog box. 


For more info about the syntax, see CREATE TABLE (Transact-SQL). For more info about FILESTREAM, see Binary 
Large Object (Blob) Data (SQL Server). 


What's next? 


After you review and customize the CREATE TABLE command and click OK, the Create Table SQL Statement 
dialog box returns you to the Column Mappings dialog box. For more info, see Column Mappings. 


See also 


Get started with this simple example of the Import and Export Wizard 


Preview Data Dialog Box (SQL Server Import and 


Export Wizard) 
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Applies to: Q sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


After you specify the data that you want to copy, you can optionally click Preview to open the Preview Data 
dialog box. On this page, you can preview up to 200 rows of sample data from your data source. This confirms 
that the wizard is going to copy the data that you want to copy. 


Screen shot of the Preview Data page 


The following screen shot shows the Preview Data dialog box of the Wizard. 
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Preview sample data 


Source 
Displays the query that the wizard is using to load data from the data source. 


If you selected a table to copy, the Source field displays a SELECT * FROM <table> query instead of the table 


name. 


Sample data grid 
Displays up to 200 rows of sample data that the query returns from the data source. 


That's not right, | want to change something 


After you preview the data, you may want to change the options that you selected on previous pages of the 
wizard. To make these changes, click OK to return to the Select Source Tables and Views page, and then click 
Back to return to previous pages where you can change your selections. 


What's next? 


After you preview the data that you're going to copy and click OK, the Preview Data dialog box returns you to 
the Select Source Tables and Views page or the Configure Flat File Destination page. For more info, see 
Select Source Tables and Views or Configure Flat File Destination. 


See also 


Get started with this simple example of the Import and Export Wizard 


Save and Run Package (SQL Server Import and 


Export Wizard) 
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Applies to: Q sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


After you specify and configure your data source and destination, the SQL Server Import and Export Wizard 
shows Save and Run Package. On this page, you specify whether you want to run the copy operation 
immediately. Depending on your configuration, you may also be able to save your settings as a SQL Server 
Integration Services (SSIS) package to customize it and to reuse it later. 


What's a package? The Wizard uses SQL Server Integration Services (SSIS) to copy data. In SSIS, the basic unit 
is the package. The wizard creates an SSIS package in memory as you move through the pages of the wizard 
and specify options. 


Screen shot of the Save and Run Package page 


The following screen shot shows the Save and Run Package page of the wizard. 
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Save and Run Package 
Indicate whether to save the SSIS package 


[7 Run immediately 


I” Save SSIS Package 
es 
c 


Package protection level 


Encrypt sensitive data with user key - 


Password | 
Retype password: | 


Help <Back | Next>] Finish >>I Cancel 








Run and save the package 
To continue, you have to select at least one of the following two options. 


Run immediately 
Select this option to import and export data immediately. By default, this check box is selected and the operation 
runs immediately. 


Save SSIS Package 
Save your settings as an SSIS package. Later you can optionally customize the package and run it again. If you 
choose to save the package, there are additional options on the next page, Save SSIS Package. 


The option to save the package is available only if you have SQL Server Standard Edition or a higher edition 
installed. 





NOTE 


If you finish the wizard, run the operation, but stop the operation before it finishes running, the package is not saved, 


even if you selected the Save SSIS Package check box. 











If you started the wizard from Visual Studio 


If you started the wizard from an Integration Services project in Visual Studio with SQL Server Data Tools 
(SSDT): 


e You can't run the package until after you exit the wizard. Then you can run the package from Visual Studio. 


e The wizard saves the package in the Integration Services project from which you started the wizard. 


Specify options for saving the package 


SQL Server 
Select this option to save the package in SQL Server in the msdb database in the sysssispackages table. 





IMPORTANT 
This option does not save the package to the SSIS Catalog database (SSISDB). 





You select the target server and provide credentials to connect to the server on the next page, Save SSIS 


Package. For more info, see Save SSIS Package. 


File system 
Select this option to save the package as a file with the .dtsx extension. 


You select the target folder and file name for the package on the next page, Save SSIS Package. For more info, 
see Save SSIS Package. 


Specify the package protection level 


Package protection level 
Select a protection level from the list to help protect the data in the package. 


The protection level determines the protection method, the password or user key, and the scope of package 
protection. Protection can include all data or sensitive data only. For more info about the available options, see 
Access Control for Sensitive Data in Packages. 


Password 
Type a password. 


Retype password 
Type the password again. 


NOTE 


The password options are available only if specify a Package protection level that requires a password - that is, if you 


specify either Encrypt sensitive data with password or Encrypt all data with password. 





About the two pages of options for saving the package 


The Save and Run Package page is one of two pages on which you pick options for saving the SSIS package. 


@ On the current page, you pick whether to save the package in SQL Server or as a file. You also pick 
security settings for the saved package. 


e Next, on the Save SSIS Package page, you provide a name for the package and more info about where 


to save it. For more info, see Save SSIS Package. 


These options are available only if you select the Save SSIS Package option on this page. 


What's next? 


After you specify whether to run the copy operation immediately and whether to save the package, the next 
page depends on the options that you choose. 


e If you selected the option to run the package immediately, but not to save it, the next page is Complete 
the Wizard. On this page, you review the choices that you made in the wizard, and then start the copy 
operation. For more info, see Complete the Wizard. 


e If you selected the option to save the package, the next page is Save SSIS Package. On this page, you 
specify additional options for saving the package. (Then, after you save the package, the following page is 
Complete the Wizard.) For more info, see Save SSIS Package. 


See Also 


Save Packages 

Run Integration Services (SSIS) Packages 

SQL Server Integration Services 

Get started with this simple example of the Import and Export Wizard 


Save SSIS Package (SQL Server Import and Export 


Wizard) 
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Applies to: Q sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


If you specified on the Save and Run Package page that you want to save your settings as a SQL Server 
Integration Services (SSIS) package, the SQL Server Import and Export Wizard shows Save SSIS Package. On 
this page, you specify additional options for saving the package created by the wizard. 


The options that you see on the Save SSIS Package page depend on the choice that you made previously on 
the Save and Run Package page to save the package to SQL Server or to the file system. To take another look 
at the Save and Run Package page, see Save and Run Package. 


What's a package? The Wizard uses SQL Server Integration Services (SSIS) to copy data. In SSIS, the basic unit 
is the package. The wizard creates an SSIS package in memory as you move through the pages of the wizard 
and specify options. 


Screen shot - Common options 


The following screen shot shows the first part of the Save SSIS Package page of the wizard. The rest of the 
page has a variable number of options which depend on the package destination that you chose. 
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Provide a name and description for the package 


Name 
Provide a unique name for the package. 


Description 
Provide a description for the package. As a best practice, describe the purpose of the package, to make packages 
self-documenting and easier to maintain. 


Target 
The destination ( SQL Server or File system) that you previously specified for the package. If you want to save 
the package to a different destination, go back to the Save and Run Package page. 


Screen shot - Save the package in SQL Server 


The following screen shot shows the Save SSIS Package page of the wizard if you selected the SQL Server 
option on the Save and Run Package page. 
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Options to specify (Target = SQL Server) 


NOTE 


The wizard saves the package in the msdb database in the sysssispackages table. This option does not save the 
package to the SSIS Catalog database (SSISDB). 





Server name 


Type or select the destination server name. 


Use Windows Authentication 
Connect to the server by using Windows Integrated Authentication. This is the preferred authentication method. 


Use SQL Server Authentication 
Connect to the server by using SQL Server Authentication. 


User name 
If you specified SQL Server Authentication, enter the user name. 


Password 
If you specified SQL Server Authentication, enter the password. 


Screen shot - Save the package in the file system 


The following screen shot shows the Save SSIS Package page of the wizard if you selected the File system 
option on the Save and Run Package page. 
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Options to specify (Target = File system) 


File name 


Enter the path and filename for the destination file, or use the Browse button to select a destination. 


TIP 


Be sure to specify a destination folder, either by entering it or by browsing. If you only enter the filename without a path, 
you don't know where the wizard saves the package. Also, the wizard may try to save the package to a location where 
you don't have permission to save a file, and raise an error. 


Remember where you save the package file. 





Browse 


Optionally, browse to select the path for the destination file in the Save Package dialog box. 


About the two pages of options for saving the package 
The Save SSIS Package page is one of two pages on which you pick options for saving the SSIS package. 


e On the previous page, Save and Execute Package, you pick whether to save the package in SQL Server 
or as a file. You also pick security settings for the saved package. To take another look at the Save and 
Run Package page, see Save and Run Package. 


e On the current page, you provide a name for the package and more info about where to save it. 


Run the saved package again later 


To learn how to run the saved package again later, see one the following topics. 


e Toruna package by using a utility program with a friendly user interface, see Execute Package Utility 
(DtExecUl) UI Reference. 


e Toruna package from the command line or from a batch file, see dtexec Utility. 


e If you saved the package in SQL Server in the msdb database, connect to the Integration Services 





service. Then, in SQL Server Management Studio, in Object Explorer, navigate to Stored Packages | 
MSDB, right-click on the package, and select Run Package. 


e If you saved the package in the file system, see Run Integration Services (SSIS) Packages to run the 
package in the development environment. You have to add the package to an Integration Services project 
before you can open and run it. 


Customize the saved package 


To learn how to customize the saved package, see Integration Services (SSIS) Packages. 


What's next? 


After you specify additional options for saving the package, the next page is Complete the Wizard. On this 
page, you review the choices that you made in the wizard, and then you start the operation. For more info, see 
Complete the Wizard. 


See Also 


Save Packages 
Run Integration Services (SSIS) Packages 
SQL Server Integration Services 


Complete the Wizard (SQL Server Import and 


Export Wizard) 
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Applies to: Q sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


After you specify whether you want to run the copy operation immediately, and after you optionally save the 
package that the wizard created, the SQL Server Import and Export Wizard shows Complete the Wizard. On 
this page, you review the choices that you made in the wizard, and then click Finish to start the copy operation. 


Screen shot of the Complete the Wizard page 


The following screen shot shows a simple example of the Complete the Wizard page of the wizard. 
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‘Source Location : localhost 

Destination Location : locathost 

° Copy rows from “Sales”."Customer” to “Sales”. "“CustomerNew™ 
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Review the options you selected 
Review the summary and verify the following information: 


e The source and destination of the data to copy. 
e The data to copy. 
e@ Whether the package will be saved. 


e@ Whether the package will be run immediately. 


What's next? 


After you review the choices that you made in the wizard and click Finish, the next page is Performing 
Operation. On this page, you see the progress and the result of the operation that you configured on the 
preceding pages. For more info, see Performing Operation. 


See also 


Get started with this simple example of the Import and Export Wizard 
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Export Wizard) 
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Applies to: Q sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


After you review the choices that you made in the wizard and click Finish on the Complete the Wizard page, 
the SQL Server Import and Export Wizard shows Performing Operation. On this page, you see the progress 
and the result of the operation that you configured on the preceding pages. You don't have to take any action on 
this page. 


Screen shot - Operation in progress 


The following screen shot shows the Performing Operation page of the wizard while the operation is still in 


progress. 
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Performing Operation ... 
Click the Stop button to interrupt the operation. 


SSeeeeeeces 








Screen shot - Operation completed 


The following screen shot shows the Performing Operation page of the wizard after the operation is 
complete. Click on an item in the Message column to get more info about the corresponding step. 
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Watch the progress of the operation 


Action 
Displays each step of the operation. 


Status 
Displays the success or failure of each step. 


Message 
Displays informational and error messages about the step. Click on an item in this column to get more info 
about the corresponding step. 


Interrupt the operation or save the results 


Stop 
Interrupt the operation, if necessary, by clicking the Stop button. 


Report 
View a report of the results, save the report to a file, copy the report to the clipboard, or send the report by e- 


mail. 


What's next? 


After the operation that you configured runs and completes successfully, you're finished running the SQL Server 
Import and Export Wizard. 


e Ifyou ran the operation immediately, you can open the destination that you selected to review the data that 
the wizard copied. 


e If you saved the SSIS package created by the wizard, you can open it in SQL Server Data Tools to customize it 
and reuse it. For info about how to customize the saved package and run it again later, see Save SSIS 
Package. 


See also 


Get started with this simple example of the Import and Export Wizard 


Import data from Excel or export data to Excel with 


SQL Server Integration Services (SSIS) 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


This article describes the connection information that you have to provide, and the settings that you have to 
configure, to import data from Excel or export data to Excel with SQL Server Integration Services (SSIS). 


The following sections contain the information you need to use Excel successfully with SSIS, and to understand 
and troubleshoot common problems: 


1. The tools you can use. 
2. The files you need. 


3. The connection information that you have to provide, and the settings that you have to configure, when 
you load data from or to Excel with SSIS. 


e Specify Excel as your data source. 

e Provide the Excel file name and path. 

e Select the Excel version. 

e@ Specify whether the first row contains column names. 
e@ Provide the worksheet or range that contains the data. 


4. Known issues and limitations. 


e Issues with data types. 
e Issues with importing. 


e Issues with exporting. 


Tools you can use 


You can import data from Excel or export data to Excel with SSIS by using one of the following tools: 


e SQL Server Integration Services (SSIS). Create an SSIS package that uses the Excel Source or the 
Excel Destination with the Excel Connection Manager. (This article does not describe how to create SSIS 
packages.) 


e TheSQL Server Import and Export Wizard, which is built on SSIS. For more info, see Import and 
Export Data with the SQL Server Import and Export Wizard and Connect to an Excel Data Source (SQL 
Server Import and Export Wizard). 


Get the files you need to connect to Excel 


Before you can import data from Excel or export data to Excel with SSIS, you may have to download the 
connectivity components for Excel if they're not already installed. The connectivity components for Excel are not 
installed by default. 


Download the latest version of the connectivity components for Excel here: Microsoft Access Database Engine 
2016 Redistributable. The latest version of the components can open files created by earlier versions of Excel. 


Notes about the download and installation 


e Make sure that you download the Access Database Engine 2016 Redistributable and not the Microsoft 
Access 2016 Runtime. 


e If the computer already has a 32-bit version of Office, then you have to install the 32-bit version of the 
components. You also have to ensure that you run the SSIS package in 32-bit mode, or run the 32-bit 
version of the Import and Export Wizard. 


e If you have a Microsoft 365 subscription, you may see an error message when you run the installer. The 
error indicates that you can't install the download side by side with Office click-to-run components. To 
bypass this error message, run the installation in quiet mode by opening a Command Prompt window 
and running the .EXE file that you downloaded with the /quiet switch. For example: 


Cc: \Users\<user_name>\Downloads\AccessDatabaseEngine.exe /quiet 


If you have trouble installing the 2016 redistributable, install the 2010 redistributable instead from here: 
Microsoft Access Database Engine 2010 Redistributable. (There is no redistributable for Excel 2013.) 


Specify Excel as your data source 


The first step is to indicate that you want to connect to Excel. 


In SSIS 


In SSIS, create an Excel Connection Manager to connect to the Excel source or destination file. There are several 


ways to create the connection manager: 


e Inthe Connection Managers area, right-click and select New connection. In the Add SSIS 
Connection Manager dialog box, select EXCEL and then Add. 


e Onthe SSIS menu, select New connection. In the Add SSIS Connection Manager dialog box, select 
EXCEL and then Add. 


e Create the connection manager at the same time that you configure the Excel Source or the Excel 
Destination on the Connection manager page of the Excel Source Editor or of the Excel 
Destination Editor. 


In the SQL Server Import and Export Wizard 


In the Import and Export Wizard, on the Choose a Data Source or Choose a Destination page, select 
Microsoft Excel in the Data source list. 


If you don't see Excel in the list of data sources, make sure you're running the 32-bit wizard. The Excel 
connectivity components are typically 32-bit files and aren't visible in the 64-bit wizard. 


Excel file and file path 


The first piece of info to provide is the path and file name for the Excel file. You provide this info in the Excel 
Connection Manager Editor in an SSIS package, or on the Choose a Data Source or Choose a 
Destination page of the Import and Export Wizard. 


Enter the path and file name in the following format: 
e Fora file on the local computer, C:\TestData.xlsx. 
e Fora file on a network share, \\Sales\Data\TestData.xlsx. 


Or, click Browse to locate the spreadsheet by using the Open dialog box. 





IMPORTANT 


You can't connect to a password-protected Excel file. 





Excel version 


The second piece of info to provide is the version of the Excel file. You provide this info in the Excel Connection 
Manager Editor in an SSIS package, or on the Choose a Data Source or Choose a Destination page of the 
Import and Export Wizard. 


Select the version of Microsoft Excel that was used to create the file, or another compatible version. For example, 
if you had trouble installing the 2016 connectivity components, you can install the 2010 components and select 
Microsoft Excel 2007-2010 in this list. 


You may not be able to select newer Excel versions in the list if you only have older versions of the connectivity 
components installed. The Excel version list includes all the versions of Excel supported by SSIS. The presence 
of items in this list does not indicate that the required connectivity components are installed. For example, 
Microsoft Excel 2016 appears in the list even if you have not installed the 2016 connectivity components. 


First row has column names 


If you're importing data from Excel, the next step is to indicate whether the first row of the data contains column 
names. You provide this info in the Excel Connection Manager Editor in an SSIS package, or on the Choose 
a Data Source page of the Import and Export Wizard. 


e If you disable this option because the source data doesn't contain column names, the wizard uses F1, F2, and 
so forth, as column headings. 

e If the data contains column names, but you disable this option, the wizard imports the column names as the 
first row of data. 

e If the data does not contain column names, but you enable this option, the wizard uses the first row of source 
data as the column names. In this case, the first row of source data is no longer included in the data itself. 


If you're exporting data from Excel, and you enable this option, the first row of exported data includes the 


column names. 


Worksheets and ranges 


There are three types of Excel objects that you can use as the source or destination for your data: a worksheet, a 
named range, or an unnamed range of cells that you specify with its address. 


e Worksheet. To specify a worksheet, append the ¢ character to the end of the sheet name and add 
delimiters around the string - for example, [Sheet1$]. Or, look for a name that ends with the $ 


character in the list of existing tables and views. 


e Named range. To specify a named range, provide the range name - for example, MyDataRange. Or, 
look for a name that does not end with the $ character in the list of existing tables and views. 


e Unnamed range. To specify a range of cells that you haven't named, append the $ character to the end 
of the sheet name, add the range specification, and add delimiters around the string - for example, 
[Sheet1$A1:B4]. 


To select or specify the type of Excel object that you want to use as the source or destination for your data, do 
one of the following things: 


In SSIS 


In SSIS, on the Connection manager page of the Excel Source Editor or of the Excel Destination Editor, 
do one of the following things: 


e To use aworksheet or anamed range, select Table or view as the Data access mode. Then, in the 
Name of the Excel sheet list, select the worksheet or named range. 


e To use an unnamed range that you specify with its address, select SQL command as the Data access 


mode. Then, in the SQL command text field, enter a query like the following example: 


SELECT * FROM [Sheet1$A1:B5] 


In the SQL Server Import and Export Wizard 


In the Import and Export Wizard, do one of the following things: 
e When you're importing from Excel, do one of the following things: 


© To use aworksheet or anamed range, on the Specify table copy or query page, select Copy 
data from one or more tables or views. Then, on the Select Source Tables and Views 
page, in the Source column, select the source worksheets and named ranges. 


o Touse anunnamed range that you specify with its address, on the Specify table copy or 
query page, select Write a query to specify the data to transfer. Then, on the Provide a 
Source Query page, provide a query similar to the following example: 


SELECT * FROM [Sheet1$A1:B5] 


e When you're exporting to Excel, do one of the following things: 


o To use aworksheet or anamed range, on the Select Source Tables and Views page, in the 
Destination column, select the destination worksheets and named ranges. 


o To use an unnamed range that you specify with its address, on the Select Source Tables and 
Views page, in the Destination column, enter the range in the following format without 
delimiters: Sheet1$A1:85 . The wizard adds the delimiters. 


After you select or enter the Excel objects to import or export, you can also do the following things on the 
Select Source Tables and Views page of the wizard: 


e@ Review column mappings between source and destination by selecting Edit Mappings. 


e Preview sample data to make sure it's what you expect by selecting Preview. 


Issues with data types 


Data types 


The Excel driver recognizes only a limited set of data types. For example, all numeric columns are interpreted as 
doubles (DT_R8), and all string columns (other than memo columns) are interpreted as 255-character Unicode 
strings (DT_WSTR). SSIS maps the Excel data types as follows: 


e Numeric - double-precision float (DT_R8) 
e@ Currency - currency (DT_CY) 
e Boolean - Boolean (DT_BOOL) 


e Date/time - datetime (DT_DATE) 


e String - Unicode string, length 255 (DT_WSTR) 
e Memo - Unicode text stream (DT_NTEXT) 


Data type and length conversions 


SSIS does not implicitly convert data types. As a result, you may have to use Derived Column or Data 
Conversion transformations to convert Excel data explicitly before loading it into a destination other than Excel, 


or to convert data from a source other than Excel before loading it into an Excel destination. 
Here are some examples of the conversions that may be required: 


e Conversion between Unicode Excel string columns and non-Unicode string columns with specific 
codepage. 


e Conversion between 255-character Excel string columns and string columns of different lengths. 


e Conversion between double-precision Excel numeric columns and numeric columns of other types. 


TIP 

If you're using the Import and Export Wizard, and your data requires some of these conversions, the wizard configures 
the necessary conversions for you. As a result, even when you want to use an SSIS package, it may be useful to create the 
initial package by using the Import and Export Wizard. Let the wizard create and configure connection managers, sources, 


transformations, and destinations for you. 





Issues with importing 


Empty rows 

When you specify a worksheet or a named range as the source, the driver reads the contiguous block of cells 
starting with the first non-empty cell in the upper-left corner of the worksheet or range. As a result, your data 
doesn't have to start in row 1, but you can't have empty rows in the source data. For example, you can't have an 
empty row between the column headers and the data rows, or a title followed by empty rows at the top of the 
worksheet. 


If there are empty rows above your data, you can't query the data as a worksheet. In Excel, you have to select 
your range of data and assign a name to the range, and then query the named range instead of the worksheet. 


Missing values 

The Excel driver reads a certain number of rows (by default, eight rows) in the specified source to guess at the 

data type of each column. When a column appears to contain mixed data types, especially numeric data mixed 
with text data, the driver decides in favor of the majority data type, and returns null values for cells that contain 
data of the other type. (In a tie, the numeric type wins.) Most cell formatting options in the Excel worksheet do 

not seem to affect this data type determination. 


You can modify this behavior of the Excel driver by specifying Import Mode to import all values as text. To 
specify Import Mode, add Imex=1 to the value of Extended Properties in the connection string of the Excel 


connection manager in the Properties window. 


Truncated text 


When the driver determines that an Excel column contains text data, the driver selects the data type (string or 
memo) based on the longest value that it samples. If the driver does not discover any values longer than 255 
characters in the rows that it samples, it treats the column as a 255-character string column instead of a memo 
column. Therefore, values longer than 255 characters may be truncated. 


To import data from a memo column without truncation, you have two options: 





e Make sure that the memo column in at least one of the sampled rows contains a value longer than 255 
characters 


e Increase the number of rows sampled by the driver to include such a row. You can increase the number of 
rows sampled by increasing the value of TypeGuessRows under the following registry key: 


REDISTRIBUTABLE COMPONENTS VERSION REGISTRY KEY 


Excel 2016 HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\Micro 
soft\Office\16.0\Access Connectivity Engine\Engines\Excel 


Excel 2010 HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\Micro 
soft\Office\14.0\Access Connectivity Engine\Engines\Excel 


Issues with exporting 


Create a new destination file 

In SSIS 

Create an Excel Connection Manager with the path and file name of the new Excel file that you want to create. 
Then, in the Excel Destination Editor, for Name of the Excel sheet, select New to create the destination 
worksheet. At this point, SSIS creates the new Excel file with the specified worksheet. 


In the SQL Server Import and Export Wizard 
On the Choose a Destination page, select Browse. In the Open dialog box, navigate to the folder where you 
want the new Excel file to be created, provide a name for the new file, and then select Open. 


Export to a large enough range 


When you specify a range as the destination, an error occurs if the range has fewer co/umns than the source 
data. However, if the range that you specify has fewer rows than the source data, the wizard continues writing 
rows without error and extends the range definition to match the new number of rows. 


Export long text values 
Before you can successfully save strings longer than 255 characters to an Excel column, the driver must 


recognize the data type of the destination column as memo and not string. 


e If an existing destination table already contains rows of data, then the first few rows that are sampled by the 
driver must contain at least one instance of a value longer than 255 characters in the memo column. 


Related content 


For more information about the components and procedures described in this article, see the following articles: 


About SSIS 

Excel Connection Manager 

Excel Source 

Excel Destination 

Loop through Excel Files and Tables by Using a Foreach Loop Container 
Working with Excel Files with the Script Task 


About the SQL Server Import and Export Wizard 


Connect to an Excel Data Source 
Get started with this simple example of the Import and Export Wizard 


Other articles 


Import data from Excel to SQL Server or Azure SQL Database 


Load data into SQL Server or Azure SQL Database 


with SQL Server Integration Services (SSIS) 
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APPLIES TO: @ sQlServer @ ssis Integration Runtime in Azure Data Factory 


Create a SQL Server Integration Services (SSIS) package to load data into SQL Server or Azure SQL Database. 
You can optionally restructure, transform, and cleanse the data as it passes through the SSIS data flow. 


This article shows you how to do the following things: 


e Create a new Integration Services project in Visual Studio. 
e Design an SSIS package that loads data from the source into the destination. 


e Run the SSIS package to load the data. 


Basic concepts 


The package is the basic unit of work in SSIS. Related packages are grouped in projects. You create projects and 
design packages in Visual Studio with SQL Server Data Tools. The design process is a visual process in which 
you drag and drop components from the Toolbox to the design surface, connect them, and set their properties. 
After you finish your package, you can run it, and you can optionally deploy it to SQL Server or SQL Database 
for comprehensive management, monitoring, and security. 


A detailed introduction to SSIS is beyond the scope of this article. To learn more, see the following articles: 
e SQL Server Integration Services 


e How to Create an ETL Package 


About the solution 


The solution is a typical package which uses a Data Flow task that contains a source and a destination. This 
approach supports a wide range of data sources, including SQL Server and Azure SQL Database. 


This tutorial uses SQL Server as the data source. SQL Server runs on premises or on an Azure virtual machine. 


To connect to SQL Server and to SQL Database, you can use an ADO.NET connection manager and source and 
destination, or an OLE DB connection manager and source and destination. This tutorial uses ADO.NET because 
it has the fewest configuration options. OLE DB may provide slightly better performance than ADO.NET. 


As a shortcut, you can use the SQL Server Import and Export Wizard to create the basic package. Then, save the 
package, and open it in Visual Studio or SSDT to view and customize it. For more info, see Import and Export 
Data with the SQL Server Import and Export Wizard. 


Prerequisites 
To step through this tutorial, you need the following things: 


1. SQL Server Integration Services (SSIS). SSIS is a component of SQL Server and requires a licensed 
version, or the developer or evaluation version, of SQL Server. To get an evaluation version of SQL Server, 
see Evaluate SQL Server. 


2. Visual Studio (optional). To get the free Visual Studio Community Edition, see Visual Studio Community. 


If you don't want to install Visual Studio, you can install SQL Server Data Tools (SSDT) only. SSDT installs a 
version of Visual Studio with limited functionality. 


3. SQL Server Data Tools for Visual Studio (SSDT). To get SQL Server Data Tools for Visual Studio, see 
Download SQL Server Data Tools (SSDT). 


4. This tutorial connects to a SQL Server or a SQL Database instance and loads data into it. You have to have 
permission to connect, to create a table, and to load data on one of the following: 


e An Azure SQL Database database. For more info, see Azure SQL Database. 
or 


e A SQL Server instance. SQL Server runs on premises or on an Azure virtual machine. To download 


a free evaluation or developer edition of SQL Server, see SQL Server downloads. 


5. Sample data. This tutorial uses sample data stored in SQL Server in the AdventureWorks sample 
database as the source data. To get the AdventureWorks sample database, see AdventureWorks Sample 
Databases. 


6. A firewall rule if you're loading data into SQL Database. You have to create a firewall rule on SQL 
Database with the IP address of your local computer before you can upload data to the SQL Database. 


Create a new Integration Services project 


1. Launch Visual Studio. 

2. On the File menu, select New | Project. 

3. Navigate to the Installed | Templates | Business Intelligence | Integration Services project types. 
4 


. Select Integration Services Project. Provide values for Name and Location, and then select OK. 


Visual Studio opens and creates a new Integration Services (SSIS) project. Then Visual Studio opens the designer 
for the single new SSIS package (Package.dtsx) in the project. You see the following screen areas: 


@ On the left, the Toolbox of SSIS components. 


e Inthe middle, the design surface, with multiple tabs. You typically use at least the Control Flow and the 
Data Flow tabs. 


e On the right, the Solution Explorer and the Properties panes. 
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Create the basic data flow 


1. Drag a Data Flow Task from the Toolbox to the center of the design surface (on the Control Flow tab). 
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3. From the Other Sources list in the Toolbox, drag an ADO.NET Source to the design surface. With the 
source adapter still selected, change its name to SQL Server source in the Properties pane. 


4. From the Other Destinations list in the Toolbox, drag an ADO.NET Destination to the design surface under 
the ADO.NET Source. With the destination adapter still selected, change its name to SQL destination in 


the Properties pane. 


e SQL Server source 





Configure the source adapter 


1. Double-click the source adapter to open the ADO.NET Source Editor. 





@ ADO.NET Source Editor 


Configure the properties used by a data flow to obtain data from any ADO.NET provider. 


Specify an ADO.NET connection manager, a data source, or a data source view, and select the data access mode. After 
selecting the data access mode, select from among the additional data access options that appear. 





ADO.NET connection manager: 


Me New... 
Data access mode: 


Table or view 


Name of the table or the view: 


A Select 2 connection manager from the list of connection managers. 
Ms 








2. On the Connection Manager tab of the ADO.NET Source Editor, click the New button next to the 
ADO.NET connection manager list to open the Configure ADO.NET Connection Manager dialog 
box and create connection settings for the SQL Server database from which this tutorial loads data. 











& Configure ADO.NET Connection Manager Oo x 
To create a connection manager based on previously defined connection information, select a data connection, 
and then click OK. To create a new connection manager, click New. 

Data connections: Data connection properties: 
Property Value 
New... Delete 
K Cancel 








3. In the Configure ADO.NET Connection Manager dialog box, click the New button to open the 
Connection Manager dialog box and create a new data connection. 
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4. Inthe Connection Manager dialog box, do the following things. 
a. For Provider, select the SqlClient Data Provider. 
b. For Server name, enter the SQL Server name. 
c. Inthe Log on to the server section, select or enter authentication information. 


d. In the Connect to a database section, select the AdventureWorks sample database. 


e. Click Test Connection. 





Connection Manager 


Test connection succeeded. 





f. In the dialog box that reports the results of the connection test, click OK to return to the 
Connection Manager dialog box. 


g. In the Connection Manager dialog box, click OK to return to the Configure ADO.NET 
Connection Manager dialog box. 


5. In the Configure ADO.NET Connection Manager dialog box, click OK to return to the ADO.NET 
Source Editor. 


6. Inthe ADO.NET Source Editor, in the Name of the table or the view list, select the 
Sales.SalesOrderDetail table. 





@ ADO.NET Source Editor 


Configure the properties used by a data flow to obtain data from any ADO.NET provider. 


Connection Manager Specify an ADO.NET connection manager, a data source, or a data source view, and select the data access mode. After 
Cobwans selecting the data access mode, select from among the additional data access options that appear. 


Error Output 


ADO.NET connection manager. 


localhost.AdventureWorks2014 v New... 


Data access mode: 


Table or view 


Name of the table or the view: 





s”."SalesOrderDetail 








Preview... 


[eT] eet) 








7. Click Preview to see the first 200 rows of data in the source table in the Preview Query Results dialog 
box. 





a? Preview Query Results oO x 
Query result (up to the first 200 rows): 

SalesOrderID SalesOrde... CarrierTra... OrderQty ProductID SpedalOff... @ 

459 S| 1 9911-403... 1 7% 1 

43659 2 4911-403... 3 7 1 

43659 3 4911-403... 1 778 1 

43659 4 4911-403... 1 771 1 

4359 5 911-403... 1 772 1 

43659 6 9911-403... 2 773 1 

43659 7 4911-403... 1 774 1 

43659 8 4911-403... 3 714 1 

43659 9 911-403... 1 716 1 

43659 10 9911-403... 6 709 1 

43659 ll 4911-403... 2 712 1 

43659 12 4911-403... 4 711 1 

43660 13 6431-4DS... 1 762 1 

43660 14 6431-4DS... 1 758 1 

43661 15 0A-F8... 1 745 1 v 

< > 








8. In the Preview Query Results dialog box, click Close to return to the ADO.NET Source Editor. 


9. Inthe ADO.NET Source Editor, click OK to finish configuring the data source. 


Connect the source adapter to the destination adapter 


1. Select the source adapter on the design surface. 


2. Select the blue arrow that extends from the source adapter and drag it to the destination editor until it 
snaps into place. 


= SQL Server source 


| 


(BE SQL DE Destination 


In a typical SSIS package, you use a number of other components from the SSIS Toolbox in between the 
source and the destination to restructure, transform, and cleanse your data as it passes through the SSIS 
data flow. To keep this example as simple as possible, we're connecting the source directly to the 
destination. 


Configure the destination adapter 


1. Double-click the destination adapter to open the ADO.NET Destination Editor. 


Configure the properties used to insert data into a destination using ADO.NET provider. 





Connection Manager 
Specify a connection manager, data source, or data source view, and select the table or the view into which 


Mappings 
the data is copied. Click New to create a new table or view. 


Error Output 


Connection manager: 


SQL DB destination connection hd | | New... 


Use a table or view: 


Net 


Preview 


Use Bulk Insert when possible 














| A Select a table or view from the list. 
aT) (Te 


. On the Connection Manager tab of the ADO.NET Destination Editor, click the New button next to 
the Connection manager list to open the Configure ADO.NET Connection Manager dialog box and 








create connection settings for the database into which this tutorial loads data. 


. Inthe Configure ADO.NET Connection Manager dialog box, click the New button to open the 
Connection Manager dialog box and create a new data connection. 


. Inthe Connection Manager dialog box, do the following things. 


a. For Provider, select the SqlClient Data Provider. 

b. For Server name, enter the name of the SQL Server or of the SQL Database server. 

c. Inthe Log on to the server section, select Use SQL Server authentication and enter 
authentication information. 

d. In the Connect to a database section, select an existing database. a. Click Test Connection. b. In the 
dialog box that reports the results of the connection test, click OK to return to the Connection 
Manager dialog box. c. In the Connection Manager dialog box, click OK to return to the Configure 
ADO.NET Connection Manager dialog box. 

. Inthe Configure ADO.NET Connection Manager dialog box, click OK to return to the ADO.NET 

Destination Editor. 


. Inthe ADO.NET Destination Editor, click New next to the Use a table or view list to open the 
Create Table dialog box to create a new destination table with a column list that matches the source 
table. 


CREATE TABLE "SOL DB Destination" ( 
"SalesOrderiD" int 
"SalesOrderDetaillD" int 
"“CarrierTrackingNumber" nvarchar(25), 
"OrderQty' 


"Produc 


"SpecialOfferlD" int, 
"UnitPrice" money, 
"UnitPriceDiscount" money, 
“LineTotal" numeric(38,6) 
“rowguid" uniqueidentifier 


"“ModifiedDate" datetime 


—s 





Cancel 








7. Inthe Create Table dialog box, do the following things. 





a. Change the name of the destination table to SalesOrderDetail. 


CREATE TABLE "SalesOrderDetaill' ( 
"SalesOrderlD" int, 
"SalesOrderDetaillD" int, 
“CarrierTrackingNumber" nvarchar(25), 
“OrderQty" smallint, 
“ProductID" int, 

"SpecialOfferlD" int, 
"UnitPrice" money, 
“UnitPriceDiscount" money, 
“LineTotal" numeric(38,6), 
“rowguid" uniqueidentifier, 


"“ModifiedDate" datetime 








OK 


| | Cancel 














b. Click OK to create the table and return to the ADO.NET Destination Editor. 


8. In the ADO.NET Destination Editor, select the Mappings tab to see how columns in the source are 


mapped to columns in the destination. 





B+ ADO.NET Destination Editor Oo x 


Configure the properties used to insert data into a destination using ADO.NET provider. 


Connection Manager 





Error Output 











Input Column Destination Column 
| SalesOrderiO | SalesOrderiD 
SalesOrderDetaillD 7 ~ SalesOrderDetaillD 
CamierTrackingNumber CarierTrackingNumber 
OrderQty OrderQty 
ProductiD ProductiD 
SpecialOfferiD SpecialOfferiD 
UnitPrice UnitPrice 
UnitPriceDiscount UnitPriceDiscount 
LineTotal LineTotal 
ModifiedDate ModifiedDate 





[eT] eet) 





9. Click OK to finish configuring the destination. 


Run the package to load the data 


Run the package by clicking the Start button on the toolbar or by selecting one of the Run options on the 
Debug menu. 


The following paragraphs describe what you see if you created the package with the second option described in 
this article, that is, with a data flow containing a source and destination. 


As the package begins to run, you see yellow spinning wheels to indicate activity as well as the number of rows 
processed so far. 


Ns 
@ 


a SQL Server source 


nn we ‘ 


(HE SQL De Destination 


When the package has finished running, you see green check marks to indicate success as well as the total 
number of rows of data loaded from the source to the destination. 


ee SQL Server source 


may rows 


(BE SQL De Destination 


Congratulations! You've successfully used SQL Server Integration Services to load data into SQL Server or Azure 
SQL Database. 


Next steps 


e Learn how to debug and troubleshoot your packages right in the design environment. Start here: 
Troubleshooting Tools for Package Development. 


e Learn how to deploy your SSIS projects and packages to Integration Services Server or to another 
storage location. Start here: Deployment of Projects and Packages. 


Load data into a dedicated SQL pool in Azure 
Synapse Analytics with SQL Server Integration 


Services (SSIS) 


11/23/2021 * 10 minutes to read * Edit Online 





Applies to: QO azure Synapse Analytics 


Create a SQL Server Integration Services (SSIS) package to load data into a dedicated SQL pool in Azure 
Synapse Analytics. You can optionally restructure, transform, and cleanse the data as it passes through the SSIS 
data flow. 


This article shows you how to do the following things: 


e Create a new Integration Services project in Visual Studio. 
e Design an SSIS package that loads data from the source into the destination. 


e Run the SSIS package to load the data. 


Basic concepts 


The package is the basic unit of work in SSIS. Related packages are grouped in projects. You create projects and 
design packages in Visual Studio with SQL Server Data Tools. The design process is a visual process in which 
you drag and drop components from the Toolbox to the design surface, connect them, and set their properties. 
After you finish your package, you can run it, and you can optionally deploy it to SQL Server or SQL Database 
for comprehensive management, monitoring, and security. 


A detailed introduction to SSIS is beyond the scope of this article. To learn more, see the following articles: 
e SQL Server Integration Services 


e How to Create an ETL Package 


Options for loading data into Azure Synapse Analytics with SSIS 


SQL Server Integration Services (SSIS) is a flexible set of tools that provides a variety of options for connecting 
to, and loading data into, Azure Synapse Analytics. 


1. The preferred method, which provides the best performance, is to create a package that uses the Azure 
SQL DW Upload Task to load the data. This task encapsulates both source and destination information. It 
assumes that your source data is stored locally in delimited text files. 


2. Alternately, you can create a package that uses a Data Flow task that contains a source and a destination. 
This approach supports a wide range of data sources, including SQL Server and Azure Synapse Analytics. 


Prerequisites 
To step through this tutorial, you need the following things: 


1. SQL Server Integration Services (SSIS). SSIS is a component of SQL Server and requires a licensed 
version, or the developer or evaluation version, of SQL Server. To get an evaluation version of SQL Server, see 
Evaluate SQL Server. 


2. Visual Studio (optional). To get the free Visual Studio Community Edition, see Visual Studio Community. If 


you don't want to install Visual Studio, you can install SQL Server Data Tools (SSDT) only. SSDT installs a 
version of Visual Studio with limited functionality. 


3. SQL Server Data Tools for Visual Studio (SSDT). To get SQL Server Data Tools for Visual Studio, see 
Download SQL Server Data Tools (SSDT). 


4. An Azure Synapse Analytics database and permissions. This tutorial connects to a dedicated SQL pool 
in Azure Synapse Analytics instance and loads data into it. You have to have permission to connect, to create 
a table, and to load data. 


Create a new Integration Services project 


1. Launch Visual Studio. 
2. On the File menu, select New | Project. 
3. Navigate to the Installed | Templates | Business Intelligence | Integration Services project types. 


4. Select Integration Services Project. Provide values for Name and Location, and then select OK. 


Visual Studio opens and creates a new Integration Services (SSIS) project. Then Visual Studio opens the designer 
for the single new SSIS package (Package.dtsx) in the project. You see the following screen areas: 


@ On the left, the Toolbox of SSIS components. 


e Inthe middle, the design surface, with multiple tabs. You typically use at least the Control Flow and the 
Data Flow tabs. 


e On the right, the Solution Explorer and the Properties panes. 


DK] Tetoria! - Microsoft Visual Studio ici kL : Pe Ox 
File Edt View Project Build Debug Format SS Toots Window Help 
S-cme - * | Develop: » Default > Db Sune 
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BF Bulk insert Tost fe Connection Managers 
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{0 Execute Process Task 4 & Package Pants 


4 Common 


f= Expression Task < fe) Controt Flow 
@ Fike System Task fe Macelisneous 
WP FTP toe 
DS Hedoop File System Task 
& Hadoop Mive Task 
S Hadcop Pig Tas 
S& script Tost 
Send Mail Task 
® Wed Service Task 
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BD Fereach Loop Container 
(2) Sequence Container 
4 Other Tasks 
TD Analysis Services Execute DOC Task 
OF Back Up Databave Task 
BF COC Controt Task 
SB Check Database Integrity Task PackageProntyClass 
£3 Dats Mining Query Tosk GB Forced Execution Value 
EZ Enecute SQ Server Agent Job Task es ° 
PF Execute T-SQL Statement Task FoecedExecutionvaluelype bet32 
> > : FeeceExecubeniialue False 
Information. G Identification 
= = X CreationDate 3/22/2016 3:23 PM 
CeestorComputertleme 
Creatoriame 
Descnation 
Name 
Specifies the name of the object 


Drag 2 toolbox item to $$15 Dengner to use it 





Right-cick here to add 2 new connector manager to he SSS package 





Option 1 - Use the SQL DW Upload task 


The first approach is a package that uses the SQL DW Upload task. This task encapsulates both source and 
destination information. It assumes that your source data is stored in delimited text files, either locally or in 
Azure Blob Storage. 

Prerequisites for Option 1 


To continue the tutorial with this option, you need the following things: 


e The Microsoft SQL Server Integration Services Feature Pack for Azure. The SQL DW Upload task is a 
component of the Feature Pack. 


e An Azure Blob Storage account. The SQL DW Upload task loads data from Azure Blob Storage into Azure 
Synapse Analytics. You can load files that are already in Blob Storage, or you can load files from your 
computer. If you select files on your computer, the SQL DW Upload task uploads them to Blob Storage 
first for staging, and then loads them into your dedicated SQL pool. 


Add and configure the SQL DW Upload Task 
1. Drag a SQL DW Upload Task from the Toolbox to the center of the design surface (on the Control Flow 
tab). 


2. Double-click the task to open the SQL DW Upload Task Editor. 


Upload data to Azure SQL Data Warehouse (DW). Data will first be uploaded to Azure Blob Storage, and then copied to 
Azure SQL DW using PolyBase. 





¥ 2Source : 


Mappings LocalDirectory 
Columns Recursively False 
T-SQL FileName : 
Expressions v 3 Source Format 
RowDelimiter CRLF 
ColumnDelimiter l 
IsFirstRowHeader True 
vy 4 Blob Storage 
AzureStorageConnection 
BlobContainer 
BlobDirectory 
RetainFiles False 
CompressionType None 
CompressionLevel 
v 5 Data Warehouse 
AzureDwConnection 
TableName 
TableDistribution 


. Sree —EEE 


Name 
Specifies the name of the task. 











[ox | Cancel | Help 


3. Configure the task with the help of the guidance in the article Azure SQL DW Upload Task. Since this task 
encapsulates both source and destination information, and the mappings between source and destination 
tables, the task editor has several pages of settings to configure. 


Create a similar solution manually 
For more control, you can manually create a package that emulates the work done by the SQL DW Upload task. 


1. Use the Azure Blob Upload Task to stage the data in Azure Blob Storage. To get the Azure Blob Upload 
task, download the Microsoft SQL Server Integration Services Feature Pack for Azure. 


2. Then use the SSIS Execute SQL task to launch a PolyBase script that loads the data into your dedicated 
SQL pool. For an example that loads data from Azure Blob Storage into dedicated SQL pool (but not with 
SSIS), see Tutorial: Load data to Azure Synapse Analytics. 


Option 2 - Use a source and destination 


The second approach is a typical package which uses a Data Flow task that contains a source and a destination. 
This approach supports a wide range of data sources, including SQL Server and Azure Synapse Analytics. 


This tutorial uses SQL Server as the data source. SQL Server runs on premises or on an Azure virtual machine. 


To connect to SQL Server and to a dedicated SQL pool, you can use an ADO.NET connection manager and 
source and destination, or an OLE DB connection manager and source and destination. This tutorial uses 
ADO.NET because it has the fewest configuration options. OLE DB may provide slightly better performance than 
ADO.NET. 


As a shortcut, you can use the SQL Server Import and Export Wizard to create the basic package. Then, save the 
package, and open it in Visual Studio or SSDT to view and customize it. For more info, see Import and Export 
Data with the SQL Server Import and Export Wizard. 


Prerequisites for Option 2 
To continue the tutorial with this option, you need the following things: 
1. Sample data. This tutorial uses sample data stored in SQL Server in the AdventureWorks sample 


database as the source data to be loaded into a dedicated SQL pool. To get the AdventureWorks sample 
database, see AdventureWorks Sample Databases. 


2. A firewall rule. You have to create a firewall rule on your dedicated SQL pool with the IP address of your 
local computer before you can upload data to the dedicated SQL pool. 


Create the basic data flow 


1. Drag a Data Flow Task from the Toolbox to the center of the design surface (on the Control Flow tab). 
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2. Double-click the Data Flow Task to switch to the Data Flow tab. 


3. From the Other Sources list in the Toolbox, drag an ADO.NET Source to the design surface. With the 
source adapter still selected, change its name to SQL Server source in the Properties pane. 


4. From the Other Destinations list in the Toolbox, drag an ADO.NET Destination to the design surface under 
the ADO.NET Source. With the destination adapter still selected, change its name to SQL DW 


destination in the Properties pane. 


= SQL Server source 


(KE SQL DW destination 





Configure the source adapter 


1. Double-click the source adapter to open the ADO.NET Source Editor. 





@ ADO.NET Source Editor 


Configure the properties used by a data flow to obtain data from any ADO.NET provider. 





Specify an ADO.NET connection manager, a data source, or a data source view, and select the data access mode. After 
Coberaes selecting the data access mode, select from among the additional data access options that appear. 


Error Output 


ADO.NET connection manager: 


Vv New... 
Data access mode: 


Table or view 


Name of the table or the view: 


A Select 8 connection manager from the list of connection managers. 





er 





2. On the Connection Manager tab of the ADO.NET Source Editor, click the New button next to the 
ADO.NET connection manager list to open the Configure ADO.NET Connection Manager dialog 
box and create connection settings for the SQL Server database from which this tutorial loads data. 











& Configure ADO.NET Connection Manager Oo x 
To create a connection manager based on previously defined connection information, select a data connection, 
and then click OK. To create a new connection manager, click New. 

Data connections: Data connection properties: 
Property Value 
New... Delete 
K Cancel 








3. In the Configure ADO.NET Connection Manager dialog box, click the New button to open the 
Connection Manager dialog box and create a new data connection. 

















§@ Connection Manager x 
Provider: | Net Providers\SqiClient Data Provider = ] 
ie 
5 | 
_ [localhost v| Refresh 
—— Log on to the server 
ar) A 
5 4 @ Use Windows Authentication 
All O Use SQL Server Authentication 


Save my password 


Connect to a database 


@ Select or enter a database name 





CO Attach a database file: 


Browse... 


Test Connection [_ «| Cancel Help 








4. Inthe Connection Manager dialog box, do the following things. 
a. For Provider, select the SqlClient Data Provider. 
b. For Server name, enter the SQL Server name. 
c. Inthe Log on to the server section, select or enter authentication information. 


d. In the Connect to a database section, select the AdventureWorks sample database. 


e. Click Test Connection. 





Connection Manager 


Test connection succeeded. 





f. In the dialog box that reports the results of the connection test, click OK to return to the 
Connection Manager dialog box. 


g. In the Connection Manager dialog box, click OK to return to the Configure ADO.NET 
Connection Manager dialog box. 


5. In the Configure ADO.NET Connection Manager dialog box, click OK to return to the ADO.NET 
Source Editor. 


6. Inthe ADO.NET Source Editor, in the Name of the table or the view list, select the 
Sales.SalesOrderDetail table. 





@ ADO.NET Source Editor 


Configure the properties used by a data flow to obtain data from any ADO.NET provider. 


Connection Manager Specify an ADO.NET connection manager, a data source, or a data source view, and select the data access mode. After 
Cobwans selecting the data access mode, select from among the additional data access options that appear. 


Error Output 


ADO.NET connection manager. 


localhost.AdventureWorks2014 v New... 


Data access mode: 


Table or view 


Name of the table or the view: 





s”."SalesOrderDetail 








Preview... 


[eT] eet) 








7. Click Preview to see the first 200 rows of data in the source table in the Preview Query Results dialog 
box. 





a? Preview Query Results oO x 
Query result (up to the first 200 rows): 

SalesOrderID SalesOrde... CarrierTra... OrderQty ProductID SpedalOff... @ 
[4x59] 4911-403... 1 776 1 

“43659 22 4911-403... 3 7 1 

43659 3 4911-403... 1 778 1 

43659 4 4911-403... 1 771 1 

4359 s 911-403... 1 772 1 

43659 6 9911-403... 2 773 1 

43659 7 4911-403... 1 774 1 

43659 8 4911-403... 3 714 1 

43659 3 911-403... 1 716 1 

43659 10 9911-403... 6 709 1 

43659 ll 911-403... 2 712 1 

43659 12 4911-403... 4 711 1 

43660 13 6431-405... 1 762 1 

43660 14 6431-4DS... 1 758 1 

43661 15 0A-F8... 1 745 1 v 

< > 








8. In the Preview Query Results dialog box, click Close to return to the ADO.NET Source Editor. 
9. Inthe ADO.NET Source Editor, click OK to finish configuring the data source. 


Connect the source adapter to the destination adapter 


1. Select the source adapter on the design surface. 


2. Select the blue arrow that extends from the source adapter and drag it to the destination editor until it 
snaps into place. 


we SQL Server source 


= SQL DW destination (x) 


In a typical SSIS package, you use a number of other components from the SSIS Toolbox in between the 
source and the destination to restructure, transform, and cleanse your data as it passes through the SSIS 
data flow. To keep this example as simple as possible, we're connecting the source directly to the 
destination. 


Configure the destination adapter 


1. Double-click the destination adapter to open the ADO.NET Destination Editor. 





®¢ ADO.NET Destination Editor Oo x 


Configure the properties used to insert data into a destination using ADO.NET provider. 


Connection Manager 
Specify a connection manager, data source, or data source view, and select the table or the view into which 


Mappings 
the data is copied. Click New to create a new table or view. 


Error Output 


Connection manager: 


SQL DW destination connection v New... 


Use a table or view: 


Pl x New... 


©] Use Bulk Insert when possible 


| A Select a table or view from the list. 


. On the Connection Manager tab of the ADO.NET Destination Editor, click the New button next to 
the Connection manager list to open the Configure ADO.NET Connection Manager dialog box and 
create connection settings for the Azure Synapse Analytics database into which this tutorial loads data. 





. Inthe Configure ADO.NET Connection Manager dialog box, click the New button to open the 
Connection Manager dialog box and create a new data connection. 


. Inthe Connection Manager dialog box, do the following things. 


a. For Provider, select the SqlClient Data Provider. 

b. For Server name, enter the dedicated SQL pool name. 

c. Inthe Log on to the server section, select Use SQL Server authentication and enter 
authentication information. 

d. In the Connect to a database section, select an existing dedicated SQL pool database. 

e. Click Test Connection. 

f. In the dialog box that reports the results of the connection test, click OK to return to the Connection 
Manager dialog box. 

g. In the Connection Manager dialog box, click OK to return to the Configure ADO.NET Connection 
Manager dialog box. 

. Inthe Configure ADO.NET Connection Manager dialog box, click OK to return to the ADO.NET 


Destination Editor. 


. Inthe ADO.NET Destination Editor, click New next to the Use a table or view list to open the 
Create Table dialog box to create a new destination table with a column list that matches the source 
table. 





al Create Table 


CREATE TABLE "SQL DW destination" ( 
“SalesOrderlD" int, 
“SalesOrderDetaillD" int, 
“CarrierTrackingNumber" nvarchar(25), 
"“OrderQty" smallint, 

“ProductiD" int, 
“SpecialOfferlD" int, 
"UnitPrice" money, 
"UnitPriceDiscount" money, 
"LineTotal" numeric(38,6), 

| "“ModifiedDate" datetime 

) 





OK Cancel 








7. Inthe Create Table dialog box, do the following things. 
a. Change the name of the destination table to SalesOrderDetail. 


b. Remove the rowguid column. The uniqueidentifier data type is not supported in dedicated SQL 
pool. 


c. Change the data type of the LineTotal column to money. The decimal data type is not supported 


in dedicated SQL pool. For info about supported data types, see CREATE TABLE (Azure Synapse 
Analytics, Parallel Data Warehouse). 





a Create Table O 


CREATE TABLE “SalesOrderDetail" ( 
"SalesOrderlD" int, 
"“SalesOrderDetaillD" int, 
“CarrierTrackingNumber" nvarchar(25), 
“OrderQty" smallint, 

"“ProductID" int, 
“SpecialOfferlD" int, 
“UnitPrice" money, 
“UnitPriceDiscount" money, 
“LineTotal" money, 
"ModifiedDate" datetime 

) 





OK Cancel 








d. Click OK to create the table and return to the ADO.NET Destination Editor. 


8. Inthe ADO.NET Destination Editor, select the Mappings tab to see how columns in the source are 
mapped to columns in the destination. 





B+ ADO.NET Destination Editor 0 x 


Configure the properties used to insert data into a destination using ADO.NET provider. 


Connection Manager 
Error Output 











Input Column Destination Column 

| SalesOrderiO | SalesOrderiO 
CamierTrackingNumber CarierTrackingNumber 
OrderQty OrderQty 
ProductiD ProductiD 
SpecialOfferlD SpecialOfferlD 
UnitPrice UnitPrice 
UnitPriceDiscount UnitPriceDiscount 
LineTotal LineTotal 
ModifiedDate ModifiedDate 
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9. Click OK to finish configuring the destination. 


Run the package to load the data 


Run the package by clicking the Start button on the toolbar or by selecting one of the Run options on the 
Debug menu. 


The following paragraphs describe what you see if you created the package with the second option described in 
this article, that is, with a data flow containing a source and destination. 


As the package begins to run, you see yellow spinning wheels to indicate activity as well as the number of rows 
processed so far. 


@ 


a SQL Server source 


29,916 rows 


(BE SQL DW cestination 





When the package has finished running, you see green check marks to indicate success as well as the total 
number of rows of data loaded from the source to the destination. 


=e SQL Server source 





Congratulations! You've successfully used SQL Server Integration Services to load data into Azure Synapse 
Analytics. 


Next steps 


e Learn how to debug and troubleshoot your packages right in the design environment. Start here: 
Troubleshooting Tools for Package Development. 


e Learn how to deploy your SSIS projects and packages to Integration Services Server or to another 
storage location. Start here: Deployment of Projects and Packages. 


Change Data Capture (SSIS) 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


In SQL Server, change data capture offers an effective solution to the challenge of efficiently performing 
incremental loads from source tables to data marts and data warehouses. 


What is Change Data Capture? 


Source tables change over time. A data mart or data warehouse that is based on those tables needs to reflect 
these changes. However, a process that periodically copies a snapshot of the entire source consumes too much 
time and resources. Alternate approaches that include timestamp columns, triggers, or complex queries often 
hurt performance and increase complexity. What is needed is a reliable stream of change data that is structured 
so that it can easily be applied by consumers to target representations of the data. Change data capture in SQL 
Server provides this solution. 


The change data capture feature of the Database Engine captures insert, update, and delete activity applied to 
SQL Server tables, and makes the details of the changes available in an easily-consumed, relational format. The 
change tables used by change data capture contain columns that mirror the column structure of the tracked 
source tables, along with the metadata needed to understand the changes that have occurred on a row by row 
basis. 





NOTE 


Change data capture is not available in every edition of MicrosoftSQL Server. For a list of features that are supported by 
the editions of SQL Server, see Features Supported by the Editions of SQL Server 2016. 











How Change Data Capture Works in Integration Services 


An Integration Services package can easily harvest the change data in the SQL Server databases to perform 
efficient incremental loads to a data warehouse. However, before you can use Integration Services to load 
change data, an administrator must enable change data capture on the database and the tables from which you 
want to capture changes. For more information on how to configure change data capture on a database, see 
Enable and Disable Change Data Capture (SQL Server). 


Once an administrator has enabled change data capture on the database, you can create a package that 
performs an incremental load of the change data. The following diagram shows the steps for creating such a 
package that performs an incremental load from a single table: 
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Step 3: Designing the Data Flow 
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As shown in the previous diagram, creating a package that performs an incremental load of changed data 
involves the following steps: 





























Step 1: Designing the Control Flow 
In the control flow in the package, the following tasks need to be defined: 


@ Calculate the starting and ending datetime values for the interval of changes to the source data that you 
want to retrieve. 


To calculate these values, use an Execute SQL task or Integration Services expressions with datetime 
functions. You then store these endpoints in package variables for use later in the package. 


For more information: Specify an Interval of Change Data 


e Determine whether the change data for the selected interval is ready. This step is necessary because the 
asynchronous capture process might not yet have reached the selected endpoint. 


To determine whether the data is ready, start with a For Loop container to delay execution, if necessary, 
until the change data for the selected interval is ready. Inside the loop container, use an Execute SQL task 
to query the time mapping tables maintained by change data capture. Then, use a Script task that calls 
the Thread.Sleep method, or another Execute SQL task with a WAITFOR statement, to delay the 
execution of the package temporarily, if necessary. Optionally, use another Script task to log an error 
condition or a timeout. 


For more information: Determine Whether the Change Data Is Ready 


e Prepare the query string that will be used to query for the change data. 


Use a Script task or an Execute SQL task to assemble the SQL statement that will be used to query for 
changes. 


For more information: Prepare to Query for the Change Data 


Step 2: Setting Up the Query for Change Data 
Create the table-valued function that will query for the data. 


Use SQL Server Management Studio to develop and save the query. 
For more information: Retrieve and Understand the Change Data 


Step 3: Designing the Data Flow 
In the data flow of the package, the following tasks need to be defined: 


e Retrieve the change data from the change tables. 


To retrieve the data, use a source component to query the change tables for the changes that fall within 
the selected interval. The source calls a Transact-SQL table-valued function that you must have previously 
created. 


For more information: Retrieve and Understand the Change Data 
e Split the changes into inserts, updates, and deletes for processing. 


To split the changes, use a Conditional Split transformation to direct inserts, updates, and deletes to 
different outputs for appropriate processing. 


For more information: Process Inserts, Updates, and Deletes 
e Apply the inserts, deletes, and updates to the destination. 


To apply the changes to the destination, use a destination component to apply the inserts to the 
destination. Also, use OLE DB Command transformations with parameterized UPDATE and DELETE 
statements to apply updates and deletes to the destination. You can also apply updates and deletes by 
using destination components to save the rows to temporary tables. Then, use Execute SQL tasks to 
perform bulk update and bulk delete operations against the destination from the temporary tables. 


For more information: Apply the Changes to the Destination 


Change Data from Multiple Tables 


The process outlined in the previous diagram and steps involves an incremental load from a single table. When 
having to perform an incremental load from multiple tables, the overall process is the same. However, the 
design of the package needs to be changed to accommodate the processing of multiple tables. For more 
information on how to create a package that performs an incremental load from multiples tables, see Perform 
an Incremental Load of Multiple Tables. 


Related Tasks 

e Specify an Interval of Change Data 

e Determine Whether the Change Data Is Ready 

e Prepare to Query for the Change Data 

@® Create the Function to Retrieve the Change Data 


@ Retrieve and Understand the Change Data 


e Process Inserts, Updates, and Deletes 
e Apply the Changes to the Destination 


e@ Perform an Incremental Load of Multiple Tables 


Related Content 


Blog entry, SSIS Design Pattern - Incremental Load, on sqlblog.com 


Specify an Interval of Change Data 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


In the control flow of an Integration Services package that performs an incremental load of change data, the first 
task is to calculate the endpoints of the change interval. These endpoints are datetime values and will be stored 
in package variables for use later in the package. 


NOTE 


For a description of the overall process of designing the control flow, see Change Data Capture (SSIS). 





Set Up Package Variables for the Endpoints 


Before configuring the Execute SQL task to calculate the endpoints, the package variables that will store the 
endpoints have to be defined. 


To set up package variables 


1. In SQL Server Data Tools (SSDT), open a new Integration Services project. 
2. In the Variables window, create the following variables: 
a. Create a variable with the datetime data type to hold the starting point for the interval. 
This example uses the variable name, ExtractStartTime. 
b. Create another variable with the datetime data type to hold the ending point for the interval. 


This example uses the variable name, ExtractEndTime. 


If you calculate the endpoints in a master package that executes multiple child packages, you can use Parent 
Package Variable configurations to pass the values of these variables to each child package. For more 
information, see Execute Package Task and Use the Values of Variables and Parameters in a Child Package. 


Calculate a Starting Point and an Ending Point for Change Data 


After you set up the package variables for the interval endpoints, you can calculate the actual values for those 
endpoints and map those values to the corresponding package variables. Because those endpoints are 
datetime values, you will have to use functions that can calculate or work with datetime values. Both the 
Integration Services expression language and Transact-SQL have functions that work with datetime values: 


Functions in the Integration Services expression language that work with datetime values 
e DATEADD (SSIS Expression) 

e@ DATEDIFF (SSIS Expression) 

e@ DATEPART (SSIS Expression) 

e DAY (SSIS Expression) 

e@ GETDATE (SSIS Expression) 


e@ GETUTCDATE (SSIS Expression) 


MONTH (SSIS Expression) 


YEAR (SSIS Expression) 


Functions in Transact-SQL that work with datetime values 


Date and Time Data Types and Functions (Transact-SQL). 


Before you use any one of these datetime functions to calculate the endpoints, you have to determine whether 


the interval is fixed and occurs on a regular schedule. Typically, you want to apply changes that have occurred in 


source tables to destination tables on a regular schedule. For example, you might want to apply those changes 


on an hourly, daily, or weekly basis. 


After you understand whether your change interval is fixed or is more random, you can calculate the endpoints: 


Calculating the starting date and time. You use the ending date and time from the previous load as 
the current starting date and time. If you use a fixed interval for incremental loads, you can calculate this 
value by using the datetime functions of Transact-SQL or of the Integration Services expression 
language. Otherwise, you might have to persist the endpoints between executions, and use an Execute 
SQL task or a Script task to load the previous endpoint. 


Calculating the ending date and time. If you use a fixed interval for incremental loads, calculate the 
current ending date and time as an offset from the starting date and time. Again, you can calculate this 
value by using the datetime functions of Transact-SQL or of the Integration Services expression 
language. 


In the following procedure, the change interval uses a fixed interval and assumes that the incremental load 


package is run daily without exception. Otherwise, change data for missed intervals would be lost. The starting 


point for the interval is midnight the day before yesterday, that is, between 24 and 48 hours ago. The ending 


point for the interval is midnight yesterday, that is, the previous night, between 0 and 24 hours ago. 


To calculate the starting point and ending point for the capture interval 


1. 


2: 


On the Control Flow tab of SSIS Designer, add an Execute SQL Task to the package. 

Open the Execute SQL Task Editor, and on the General page of the editor, select the following options: 
a. For ResultSet, select Single row. 

b. Configure a valid connection to the source database. 

c. For SQLSourceType, select Direct input. 


d. For SQLStatement, enter the following SQL statement: 


SELECT DATEADD(dd,@, DATEDIFF(dd,@,GETDATE()-1)) AS ExtractStartTime, 
DATEADD(dd,@, DATEDIFF(dd,@,GETDATE())) AS ExtractEndTime 


. On the Result Set page of the Execute SQL Task Editor, map the ExtractStartTime result to the 


ExtractStartTime package variable, and map the ExtractEndTime result to the ExtractEndTime package 


variable. 





NOTE 


When you use an expression to set the value of an Integration Services variable, the expression is evaluated every 


time that the value of the variable is accessed. 








Next Step 


After you calculate the starting point and ending point for a range of changes, the next step is to determine 
whether the change data is ready. 


Next topic: Determine Whether the Change Data Is Ready 


See Also 


Use Variables in Packages 

Integration Services (SSIS) Expressions 
Execute SQL Task 

Script Task 


Determine Whether the Change Data Is Ready 
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In the control flow of an Integration Services package that performs an incremental load of change data, the 
second task is to ensure that the change data for the selected interval is ready. This step is necessary because 
the asynchronous capture process might not yet have processed all the changes up to the selected endpoint. 


NOTE 


The first task for the control flow is to calculate the endpoints of the change interval. For more information about this 
task, see Specify an Interval of Change Data. For a description of the overall process of designing the control flow, see 
Change Data Capture (SSIS). 








Understanding the Components of the Solution 


The solution described in this topic uses 4 Integration Services components: 
e A For Loop container that repeatedly evaluates the output of an Execute SQL Task. 


e An Execute SQL task that queries special tables that the change data capture process maintains and then 
uses this information to determine whether data is ready. 


e Acomponent that implements a delay in processing when the data is not ready. This can be either a 
Script task or an Execute SQL task. 


e@ Optionally, a component that reports an error or a timeout when the Execute SQL task returns a value 
that indicates an error or a timeout condition. 


These components set or read the values of several package variables to control the flow of execution inside the 
loop and later in the package. 


To set up package variables 


1. In SQL Server Data Tools (SSDT), in the Variables window, create the following variables: 


a. Create a variable with an integer data type to hold the status value returned by the Execute SQL 
task. 


This example uses the variable name, DataReady, with an initial value of 0. 


b. Create a variable to hold the period of time to delay when data is not ready. If you plan to use a 
Script task to implement the delay, the variable should have an integer data type integer. If you 
plan to use an Execute SQL task with a WAITFOR statement, the variable should have a string data 
type to accept values such as "00:00:10". 


This example uses the variable name, DelaySeconds, with an initial value of 10. 
c. Create a variable with an integer data type to hold the current iteration of the loop. 
This example uses the variable name, TimeoutCount, with an initial value of 0. 


d. Create a variable with an integer data type to specify the number of times that the loop should test 
for data before reporting a timeout condition. 


This example uses the variable name, TimeoutCeiling, with an initial value of 20. 


e. (Optional) Create a variable with an integer data type that you can use to indicate the first load of 


change data. 


This example uses the variable name, IntervallD, and checks only for a value of 0 to indicate the 


initial load. 


Configuring a For Loop Container 


With the variables set, the For Loop container is the first component to be added. 


To configure a For Loop container to wait until change data is ready 


1. On the Control Flow tab of the SSIS Designer, add a For Loop container to the control flow. 


2. Connect the Execute SQL Task that calculates the endpoints of the interval to the For Loop container. 


3. In the For Loop Editor, select the following options: 


a. For InitExpression, enter @DataReady = @. 


This expression sets the initial value of the loop variable. 


b. For EvalExpressionm, enter @DataReady == @. 


When this expression evaluates to False, execution passes out of the loop and the incremental 


load starts. 


Configuring the Execute SQL Task That Queries for Change Data 


Inside the For Loop container, you add an Execute SQL task. This task queries the tables that the change data 


capture process maintains in the database. The result of this query is a status value that indicates whether the 


change data is ready. 


In the following table, the first column shows the values returned from the Execute SQL task by the sample 


Transact-SQL query. The second column shows how the other components respond to these values. 


RETURN VALUE 


MEANING 


Indicates that the change data is not 
ready. 


There are no change data capture 
records later than the ending point of 
the selected interval. 


Might indicate that the change data 
has not been captured for the 
complete interval, or that it has been 
deleted. This is treated as an error 
condition. 


There are no change data capture 
records earlier than the starting point 
of the selected interval 


RESPONSE 


Execution continues with the 
component that implements a delay. 
Then control returns to the For Loop 
container, which continues to check 
the Execute SQL task as long as the 
value returned is 0. 


Execution continues with the optional 
component that logs the error. 


RETURN VALUE 


MEANING 


Indicates that data is ready. 


There are change data capture records 
that are both earlier than the starting 

point and later than the ending point 

of the selected interval. 


Indicates the initial load of all available 
change data. 


The conditional logic obtains this value 
from a special package variable that is 
used only for this purpose. 


Indicates that the TimeoutCeiling has 
been reached. 


The loop has tested for data the 
specified number of times, and data is 


still not available. Without this test or a 


similar test, the package might run 
indefinitely. 


RESPONSE 


Execution passes out of the For Loop 
container and the incremental load 
starts. 


Execution passes out of the For Loop 
container and the incremental load 
starts. 


Execution continues with the optional 
component that logs the timeout. 


To configure an Execute SQL task to query whether change data is ready 


1. Inside the For Loop container, add an Execute SQL task. 

2. In the Execute SQL Task Editor, on the General page, select the following options: 
a. For ResultSet, select Single row. 
b. Configure a valid connection to the source database. 
c. For SQLSourceType, select Direct input. 


d. For SQLStatement, enter the following SQL statement: 


declare @DataReady int, @TimeoutCount int 


if not exists (select tran_end_time from cdc.1lsn_time_mapping 
where tran_end_time > ? ) 
select @DataReady = 0 
else 
dit eve=20 
select @DataReady = 3 
else 
if not exists (select tran_end_time from cdc.1lsn_time_mapping 
where tran_end_time <= ? ) 
select @DataReady = 1 
else 
select @DataReady = 2 


select @TimeoutCount = ? 
if (@DataReady = Q) 

select @TimeoutCount = @TimeoutCount + 1 
else 

select @TimeoutCount = @ 


if (@TimeoutCount > ?) 
select @DataReady = 5 


select @DataReady as DataReady, @TimeoutCount as TimeoutCount 


3. On the Parameter Mapping page of the Execute SQL Task Editor, make the following mappings: 


a. Map the ExtractEndTime variable to parameter 0. 
b. Map the IntervallD variable to parameter 1. 

c. Map the ExtractStartTime variable to parameter 2. 
d. Map the TimeoutCount variable to parameter 3. 
e. Map the TimeoutCeiling variable to parameter 4. 


On the Result Set page of the Execute SQL Task Editor, map the DataReady result to the DataReady 
variable, and the TimeoutCount result to the TimeoutCount variable. 


Waiting Until the Change Data Is Ready 


You can use one of several methods to implement a delay when the change data is not ready. The following two 
procedures illustrate how to use a Script task or an Execute SQL task to implement the delay. 





NOTE 


A precompiled script incurs less overhead than an Execute SQL task. 





To implement a delay by using a Script task 


1. 


Inside the For Loop container, add a Script task. 


. Connect the Execute SQL task that queries to determine whether the change data is ready to the new 


Script task. 


. For the precedence constraint that connects the Execute SQL task to the Script task, open the 


Precedence Constraint Editor and select the following options: 


a. For Evaluation operation, select Expression and Constraint. 


b. For Value, select Success. 


The constraint value of Success refers to the success of the previous task. In this case, the success 
of the Execute SQL task. 


c. For Expression, enter @DataReady == @ && @TimeoutCount <= @TimeoutCeiling . 
d. Select Logical AND. All constraints must evaluate to True, if not already selected. 


4. In the Script Task Editor, on the Script page, for ReadOnlyVariables, select the User::DelaySeconds 
integer variable from the list. 


5. Inthe Script Task Editor, on the Script page, click Edit Script to open the script development 


environment. 
6. In the Main procedure, enter one of the following lines of code: 


e If you are programming in C#, enter the following line of code: 


System. Threading. Thread.Sleep((int)Dts.Variables["DelaySeconds"].Value * 1000); 


-or- 


e If you are programming in Visual Basic, enter the following line of code: 


System. Threading. Thread.Sleep(Ctype(Dts.Variables("DelaySeconds").Value, Integer) * 1000) 





NOTE 


The Thread.Sleep method expects an argument that is specified in milliseconds. 





7. Leave the default line of code which returns DtsExecResult.Success from the execution of the script. 


8. Close the script development environment and the Script Task Editor. 


To implement a delay by using an Execute SQL task 


1. Inside the For Loop container, add an Execute SQL task. 


2. Connect the Execute SQL task that queries to determine whether the change data is ready to the new 
Execute SQL task. 


3. For the precedence constraint that connects the two Execute SQL tasks, open the Precedence 
Constraint Editor and select the following options: 


a. For Evaluation operation, select Expression and Constraint. 
b. For Value, select Success. 
The constraint value of Success refers to the success of the previous Execute SQL task. 
c. For Expression, enter @DataReady == @. 
d. Select Logical AND. All constraints must evaluate to True, if not already selected. 
This selection requires that both conditions, the constraint and the expression, must be true. 
4. In the Execute SQL Task Editor, on the General page, select the following options: 


a. For ResultSet, select Single row. 


D 


b. Configure a valid connection to the source database. 
c. For SQLSourceType, select Direct input. 


d. For SQLStatement, enter the following SQL statement: 


WAITFOR DELAY ? 


On the Parameter Mapping page of the editor, map the DelaySeconds string variable to parameter 0. 


Handling an Error Condition 


You can optionally configure an additional component inside the loop to log an error or a timeout condition: 


This component can log an error condition when the value of the DataReady variable = 1. This value 
indicates that there is no available change data before the start of the selected interval. 


This component can also log a timeout condition when the value of the TimeoutCeiling variable is 
reached. This value indicates the loop has tested for data the specified number of times, and data is still 
not available. Without this test or a similar test, the package might run indefinitely. 


To configure an optional Script task to log an error condition 


1. 


If you want to report the error or timeout by writing a message to the log, configure logging for the 
package. For more information, see Enable Package Logging in SQL Server Data Tools. 


Inside the For Loop container, add a Script task. 


. Connect the Execute SQL task that queries to determine whether the change data is ready to the new 


Script task. 


. For the precedence constraint that connects the Execute SQL task to the Script task, open the 


Precedence Constraint Editor and select the following options: 
a. For Evaluation operation, select Expression and Constraint. 
b. For Value, select Success. 


The constraint value of Success refers to the success of the previous task. In this case, the success 
of the Execute SQL task. 


c. For Expression, enter @DataReady == 1 || @DataReady == 5. 
d. Select Logical AND. All constraints must evaluate to True, if not already selected. 


This selection requires that both conditions, the constraint and the expression, must be true. 


. Inthe Script Task Editor, on the Script page of the editor, for ReadOnlyVariables, select 


User::DataReady and User::ExtractStartTime from the list to make their values available to the script. 


If you want to include information from certain system variables (for example, System::PackageName) in 
the information that you write to the log, select those variables also. 


In the Script Task Editor, on the Script page, click Edit Script to open the script development 


environment. 


In the Main procedure, enter code to log an error by calling the Dts.Log method, or to raise an event by 
calling one of the methods of the Dts.Events interface. Inform the package of the error by returning 


Dts.TaskResult = Dts.Results.Failure . 


The following sample shows how to write a message to the log. For more information, see Logging in the 
Script Task, Raising Events in the Script Task, and Returning Results from the Script Task. 


User variables. 

Dim dataReady As Integer = _ 
CType(Dts.Variables("DataReady").Value, Integer) 

Dim extractStartTime As Date = _ 
CType(Dts.Variables("ExtractStartTime").Value, DateTime) 

" System variables. 

Dim packageName As String = _ 
Dts.Variables("PackageName" ) .Value.ToString() 

Dim executionStartTime As Date = _ 

CType(Dts.Variables("StartTime").Value, DateTime) 


Dim eventMessage As New System. Text.StringBuilder() 
If dataReady = 1 OrElse dataReady = 5 Then 


If dataReady = 1 Then 
eventMessage.AppendLine("Start Time Error”) 
Else 
eventMessage.AppendLine("Timeout Error") 
End If 


With eventMessage 
-Append("The package ") 
-Append(packageName ) 
-Append(" started at ") 
-Append(executionStartTime. ToString() ) 
-Append(" and ended at ") 
.AppendLine(DateTime.Now().ToString() ) 
If dataReady = 1 Then 
-Append("The specified ExtractStartTime was ") 
-AppendLine(extractStartTime. ToString() ) 
End If 
End With 


System.Windows. Forms .MessageBox. Show(eventMessage. ToString() ) 


Dts.Log(eventMessage.ToString(), @, Nothing) 


W 


Dts.TaskResult Dts.Results.Failure 


Else 


W 


Dts.TaskResult Dts.Results.Success 


End If 


8. Close the script development environment and the Script Task Editor. 


Next Step 


After you determine that change data is ready, the next step is to prepare to query for the change data. 


Next topic: Prepare to Query for the Change Data 


Prepare to Query for the Change Data 
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In the control flow of an Integration Services package that performs an incremental load of change data, the 
third and final task is to prepare to query for the change data and add a Data Flow task. 





NOTE 

The second task for the control flow is to ensure that the change data for the selected interval is ready. For more 
information about this task, see Determine Whether the Change Data Is Ready. For a description of the overall process of 
designing the control flow, see Change Data Capture (SSIS). 











Design Considerations 


To retrieve the change data, you will call a Transact-SQL table-valued function that accepts the endpoints of the 

interval as input parameters and returns change data for the specified interval. A source component in the data 
flow calls this function. For information about this source component, see Retrieve and Understand the Change 
Data. 


The most frequently used Integration Services source components, including the OLE DB source, the ADO 
source, and the ADO NET source, cannot derive parameter information for a table-valued function. Therefore, 
most sources cannot call a parameterized function directly. 


You have two design options for passing the input parameters to the function: 


e Assemble the parameterized query as a string. You can use a Script task or an Execute SQL task to 
assemble a dynamic SQL string with parameter values hard-coded into the string. Then, you can store 
this string in a package variable and use it to set the SqilCommand property of a source component. This 


approach succeeds because the source component no longer requires parameter information. 





NOTE 


A precompiled script incurs less overhead than an Execute SQL task. 





e Use a parameterized wrapper. Alternatively, you can create a parameterized stored procedure as a 
wrapper that calls the parameterized table-valued function. This approach succeeds because a source 
component can successfully derive parameter information for a stored procedure. 


This topic uses the first design option and assembles a parameterized query as a string. 


Preparing the Query 


Before you can concatenate the values of the input parameters into a single query string, you have to set up the 
package variables that the query needs. 


To set up package variables 
e In SQL Server Data Tools (SSDT), in the Variables window, create a variable with a string data type to 
hold the query string returned by the Execute SQL Task. 


This example uses the variable name, SqiDataQuery. 


With the package variable created, you can use either a Script task or Execute SQL task to concatenate the values 
of the input parameters. The following two procedures describe how to configure these components. 


To use a Script task to concatenate the query string 


1. On the Control Flow tab, add a Script task to the package after the For Loop container and connect the 


For Loop container to the task. 





NOTE 
This procedure assumes that the package performs an incremental load from a single table. If the package loads 
from multiple tables and has a parent package with multiple child packages, this task would be added as the first 


component to each child package. For more information, see Perform an Incremental Load of Multiple Tables. 








2. In the Script Task Editor, on the Script page, select the following options: 


a. For ReadOnlyVariables, select User::DataReady, User::ExtractStartTime, and 
User::ExtractEndTime from the. 


b. For ReadWriteVariables, select User:SqlDataQuery from the list. 


3. In the Script Task Editor, on the Script page, click Edit Script to open the script development 


environment. 
4. In the Main procedure, enter one of the following code segments: 


e If you are programming in C#, enter the following lines of code: 


int dataReady; 

System.DateTime extractStartTime; 
System.DateTime extractEndTime; 
string sqlDataQuery; 


dataReady = (int)Dts.Variables["DataReady"].Value; 
extractStartTime = (System.DateTime)Dts.Variables["ExtractStartTime" ].Value; 
extractEndTime = (System.DateTime)Dts.Variables["ExtractEndTime"].Value; 


if (dataReady == 2) 
‘ 
sqlDataQuery = "SELECT * FROM CDCSample.uf_Customer('" + string.Format("{@:yyyy-MM-dd 


hh:mm:ss}", extractStartTime) + "', '" + string.Format("{@:yyyy-MM-dd hh:mm:ss}", 


extractEndTime) + H 


} 


else 


{ 
sqlDataQuery = "SELECT * FROM CDCSample.uf_Customer(null" + ", '" + string.Format("{®:yyyy- 


MM-dd hh:mm:ss}", extractEndTime) + "')"; 
} 


Dts.Variables["SqlDataQuery"].Value = sqlDataQuery; 


-or- 


e If you are programming in Visual Basic, enter the following lines of code: 


Dim dataReady As Integer 

Dim extractStartTime As Date 
Dim extractEndTime As Date 
Dim sqlDataQuery As String 


dataReady = CType(Dts.Variables("DataReady").Value, Integer) 
extractStartTime = CType(Dts.Variables("ExtractStartTime").Value, Date) 
extractEndTime = CType(Dts.Variables("ExtractEndTime").Value, Date) 


If dataReady = 2 Then 
sqlDataQuery = "SELECT * FROM CDCSample.uf_Customer('" & _ 
String.Format("{@:yyyy-MM-dd hh:mm:ss}", extractStartTime) & _ 


Me Me 
String.Format("{@:yyyy-MM-dd hh:mm:ss}", extractEndTime) & _ 
mrym 

Else 

sqlDataQuery = "SELECT * FROM CDCSample.uf_Customer(null" & _ 
a ae 
String.Format("{@:yyyy-MM-dd hh:mm:ss}", extractEndTime) & _ 
mrym 

End If 


Dts.Variables("SqlDataQuery").Value = sqlDataQuery 


5. Leave the default line of code which returns DtsExecResult.Success from the execution of the script. 


6. Close the script development environment and the Script Task Editor. 


To use an Execute SQL task to concatenate the query string 


1. On the Control Flow tab, add an Execute SQL task to the package after the For Loop container and 
connect the For Loop container to this task. 





NOTE 


This procedure assumes that the package performs an incremental load from a single table. If the package loads 
from multiple tables and has a parent package with multiple child packages, this task would be added as the first 
component to each child package. For more information, see Perform an Incremental Load of Multiple Tables. 








2. Inthe Execute SQL Task Editor, on the General page, select the following options: 
a. For ResultSet, select Single row. 
b. Configure a valid connection to the source database. 
c. For SQLSourceType, select Direct input. 


d. For SQLStatement, enter the following SQL statement: 


declare @ExtractStartTime datetime, 
@ExtractEndTime datetime, 
@DataReady int 


select @DataReady = ?, 
@ExtractStartTime = ?, 
@ExtractEndTime = ? 


if @DataReady = 2 

select N'select * from CDCSample.uf_Customer' 

+ N'('''+ convert(nvarchar(3@),@ExtractStartTime, 120) 
blac eae see esha 

+ convert (nvarchar(3Q),@ExtractEndTime,120) + ''') ' 
as SqlDataQuery 

else 

select N'select * from CDCSample.uf_Customer' 

+ NE(nulS 

+ convert (nvarchar(30),@ExtractEndTime, 120) 

Boga) ae 

as SqlDataQuery 





NOTE 
The else clause in this sample generates a query for the initial load of change data by passing a null value 
for the starting date and time. This sample does not address the scenario in which changes that were 


made before change data capture was enabled also have to be uploaded to the data warehouse. 





3. On the Parameter Mapping page of the Execute SQL Task Editor, do the following mapping: 
a. Map the DataReady variable to parameter 0. 
b. Map the ExtractStartTime variable to parameter 1. 
c. Map the ExtractEndTime variable to parameter 2. 


4. On the Result Set page of the Execute SQL Task Editor, map the Result Name to the SqiIDataQuery 


variable. 


The Result Name is the name of the single column that is returned, SqlDataQuery. 


The previous procedures configure a task that prepares a query string with hard-coded string values for the 
input parameters. The following code is an example of such a query string: 


select * from CDCSample. uf_Customer('2007-06-11 14:21:58', ‘2007-06-12 14:21:58') 


Adding a Data Flow Task 


The last step in designing the control flow for the package is to add a Data Flow task. 


To add a Data Flow task and complete the control flow 


e On the Control Flow tab, add a Data Flow task and connect the task that concatenated the query string. 


Next Step 


After you prepare the query string and configure the Data Flow task, the next step is create the table-valued 
function that will retrieve the change data from the database. 


Next topic: Create the Function to Retrieve the Change Data 





Create the function to retrieve the change data 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


After completing the control flow for an Integration Services package that performs an incremental load of 
change data, the next task is to create a table-valued function (TVF) that retrieves the change data. You only have 
to create this function one time before the first incremental load. 


NOTE 


The creation of a function to retrieve the change data is the second step in the process of creating a package that 
performs an incremental load of change data. For a description of the overall process for creating this package, see 
Change Data Capture (SSIS). 





Design considerations for change data capture (CDC) functions 


To retrieve change data, a source component in the data flow of the package calls one of the following change 
data capture query functions: 


e cdc.fn_cdc_get_net_changes_<capture_instance> For this query, the single row returned for each 
update contains the final state of each changed row. In most cases, you only need the data returned by a 
query for net changes. For more information, see cdc.fn_cdc_get_net_changes_<capture_instance> 
(Transact-SQL). 


e cdc.fn_cdc_get_all_changes_<capture_instance> This query returns all the changes that have 
occurred in each row during the capture interval. For more information, see 
cdc.fn_cdc_get_all_changes_<capture_instance> (Transact-SQL). 


The source component then takes the results returned by the function and passes them to downstream 
transformations and destinations, which apply the change data to the final destination. 


However, an Integration Services source component cannot call these change data capture functions directly. An 
Integration Services source component requires metadata about the columns that the query returns. The 
change data capture functions do not define the columns of their output table. Thus, these functions do not 
return sufficient metadata for an Integration Services source component. 


Instead, you use a table-valued wrapper function because this kind of function explicitly defines the columns of 
its output table in its RETURNS clause. This explicit definition of columns provides the metadata that an 
Integration Services source component needs. You have to create this function for each table for which you want 
to retrieve change data. 


You have two options for creating the table-valued wrapper function that calls the change data capture query 
function: 


e You can call the sys.sp_cdc_generate_wrapper_function system stored procedure to create the table- 
valued functions for you. 


e You can write your own table-valued function by using the guidelines and the example in this topic. 


Calling a stored procedure to create the table-valued function 





The quickest and easiest way to create the table-valued functions that you need is to call the 

sys.sp_cdc_generate_wrapper_function system stored procedure. This stored procedure generates scripts to 
create wrapper functions that are designed specifically to meet the needs of an Integration Services source 
component. 


IMPORTANT 


The sys.sp_cdc_generate_wrapper_function system stored procedure does not directly create the wrapper functions. 
Instead, the stored procedure generates the CREATE scripts for the wrapper functions. The developer must run the 


CREATE scripts that the stored procedure generates before an incremental load package can call the wrapper functions. 





To understand how to use this system stored procedure, you should understand what the procedure does, what 
scripts the procedure generates, and what wrapper functions the scripts create. 


Understanding and using the stored procedure 


The sys.sp_cdc_generate_wrapper_function system stored procedure generates scripts to create wrapper 
functions for use by Integration Services packages. 


Here are the first few lines of the definition of the stored procedure: 


CREATE PROCEDURE sys.sp_cdc_generate_wrapper_function 
( 


@capture_instance sysname = null 
@closed_high_end_point bit = 1, 
@column_list = null, 
@update_flag list = null 

) 


All the parameters for the stored procedure are optional. If you call the stored procedure without supplying 
values for any of the parameters, the stored procedure creates wrapper functions for all the capture instances to 
which you have access. 








NOTE 


For more information about the syntax of this stored procedure and its parameters, see 


sys.sp_cdc_generate_wrapper_function (Transact-SQL). 











The stored procedure always generates a wrapper function to return all changes from each capture instance. If 
the @supports_net_changes parameter was set when the capture instance was created, the stored procedure 
also generates a wrapper function to return net changes from each applicable capture instance. 


The stored procedure returns a result set with two columns: 


e@ The name of the wrapper function that the stored procedure has generated. This stored procedure 
derives the function name from the name of the capture instance name. (The function name is 
‘fn_all_changes_' followed by the capture instance name. The prefix used for the net changes function, if it 
is created, is 'fn_net_changes_'.) 


e@ The CREATE statement for the wrapper function. 


Understanding and using the scripts created by the stored procedure 


Typically, a developer would use an INSERT...EXEC statement to call the sys.sp_cdc_generate_wrapper_function 
stored procedure and save the scripts that the stored procedure creates to a temporary table. Each script could 
then be individually selected and run to create the corresponding wrapper function. However, a developer could 
also use one set of SQL commands to run all the CREATE scripts, as shown in the following sample code: 


create table #wrapper_functions 

(function_name sysname, create_stmt nvarchar(max) ) 
insert into #wrapper_functions 
exec sys.sp_cdc_generate_wrapper_function 





declare @stmt nvarchar(max) 
declare #hfunctions cursor local fast_forward for 
select create_stmt from #wrapper_functions 
open #hfunctions 
fetch #hfunctions into @stmt 
while (@@fetch_status <> -1) 
begin 
exec sp_executesql @stmt 
fetch #hfunctions into @stmt 
end 
close #hfunctions 
deallocate #hfunctions 


Understanding and using the functions created by the stored procedure 


To systematically walk the timeline of captured change data, the generated wrapper functions expect that the 
@end_time parameter for one interval will be the @start_time parameter for the subsequent interval. When this 
convention is followed, the generated wrapper functions can do the following tasks: 


e Map the date/time values to the LSN values that are used internally. 
e Ensure that no data is lost or repeated. 


To make querying for all rows of a change table simpler, the generated wrapper functions also support the 


following conventions: 


e If the @start_time parameter is null, the wrapper functions use the lowest LSN value in the capture 
instance as the lower bound of the query. 


e |f the @end_time parameter is null, the wrapper functions use the highest LSN value in the capture 
instance as the upper bound of the query. 


e If the value of either @start_time or @end_time parameter is beyond the time of lowest LSN or highest 
LSN, then execution of generated wrapper functions will return in error 313: 


Msg 313, Level 16, State 3, Line 1 An insufficient number of arguments were supplied for the procedure 
or function 


. This error should be handled by the developer. 


Most users should be able to use the wrapper functions that the sys.sp_cdc_generate_wrapper_function system 





stored procedure creates without modification. However, to customize the wrapper functions, you have to 
customize the CREATE scripts before you run the scripts. 


When your package calls the wrapper functions, the package must supply values for three parameters. These 
three parameters are like the three parameters that the change data capture functions use. These three 


parameters are as follows: 


e The starting date/time value and the ending date/time value for the interval. While the wrapper functions 
use date/time values as the end points for the query interval, the change data capture functions use two 
LSN values as the end points. 


e The row filter. For both the wrapper functions and the change data capture functions, the 
@row_filter_option parameter is the same. For more information, see 
cdc.fn_cdc_get_all_changes_<capture_instance> (Transact-SQL) and 
cdc.fn_cdc_get_net_changes_<capture_instance> (Transact-SQL). 


The result set returned by the wrapper functions includes the following data: 


e All of the requested columns of change data. 


e Acolumn named __CDC_OPERATION that uses a one- or two-character field to identify the operation that 
is associated with the row. The valid values for this field are as follows: 'I' for insert, 'D' for delete, 'UO' for 
update old values, and 'UN' for update new values. 


e Update flags, when you request them, that appear as bit columns after the operation code and in the 
order that is specified in the @update_flag_list parameter. These columns are named by appending 


_uflag' to the associated column name. 


If your package calls a wrapper function that queries for all changes, the wrapper function also returns the 
columns, _CDC_STARTLSN and __CDC_SEQVAL. These two columns become the first and second columns, 
respectively, of the result set. The wrapper function also sorts the result set based on these two columns. 


Writing your own table-value function 


You can also use SQL Server Management Studio to write your own table-valued wrapper function that calls the 
change data capture query function, and store the table-valued wrapper function in SQL Server. For more 
information about how to create a Transact-SQL function, see CREATE FUNCTION (Transact-SQL). 


The following example defines a table-valued function that retrieves changes from a Customer table for the 
specified change interval. This function uses change data capture functions to map the datetime values to the 
binary log sequence number (LSN) values that the change tables use internally. This function also handles 
several special conditions: 


e When a null value is passed for the starting time, this function uses the earliest available value. 
e When a null value is passed for the ending time, this function uses the latest available value. 


e When the starting LSN is equal to the ending LSN, which usually indicates that there are no records for 
the selected interval, this function exits. 


Example of a table-value function that queries for change data 


CREATE function CDCSample.uf_Customer ( 
@start_time datetime 
,»@end_time datetime 
) 
returns @Customer table ( 
CustomerID int 
yTerritoryID int 
,CustomerType nchar(1) 
,»rowguid uniqueidentifier 
,»ModifiedDate datetime 
,»CDC_OPERATION varchar(1) 
) as 
begin 
declare @from_lsn binary(10), @to_lsn binary(10) 


if (@start_time is null) 
select @from_Isn = sys.fn_cdc_get_min_lsn('Customer' ) 
else 


select @from_Isn = sys.fn_cdc_increment_lsn(sys.fn_cdc_map_time_to_lsn('largest less than or 
equal',@start_time) ) 


if (@end_time is null) 
select @to_lsn = sys.fn_cdc_get_max_lsn() 
else 


select @to_lsn = sys.fn_cdc_map_time_to_lsn('largest less than or equal’ ,@end_time) 


if (@from_lsn = sys.fn_cdc_increment_lsn(@to_1lsn)) 
return 


-- Query for change data 
insert into @Customer 
select 
CustomerID, 
TerritoryID, 
CustomerType, 
rowguid, 
ModifiedDate, 
case _ $operation 
when 1 then 'D' 
when 2 then 'I' 
when 4 then 'U' 
else null 
end as CDC_OPERATION 
from 
cdc. fn_cdc_get_net_changes_Customer(@from_lsn, @to_lsn, ‘all') 





return 
end 


go 


Retrieving additional metadata with the change data 


Although the user-created table-valued function shown earlier uses only the__$operation column, the 

cdc. fn_cdc_get_net_changes_<capture_instance> function returns four columns of metadata for each change row. 
If you want to use these values in your data flow, you can return them as additional columns from the table- 
valued wrapper function. 


COLUMN NAME DATA TYPE DESCRIPTION 


COLUMN NAME 


__$start_Isn 


__$seqval 


__$operation 


__$update_mask 


<captured source table columns> 


DATA TYPE 


binary(10) 


binary(10) 


int 


varbinary(128) 


varies 


DESCRIPTION 


LSN associated with the commit 
transaction for the change. 


All changes committed in the same 
transaction share the same commit 
LSN. For example, if an update 
operation on the source table modifies 
two different rows, the change table 
will contain four rows (two with the old 
values and two with the new values), 
each with the same __$start_Isn 
value. 


Sequence value that is used to order 
the row changes in a transaction. 


The data manipulation language (DML) 
operation associated with the change. 
Can be one of the following: 


=< 
Il 


delete 


Nh 
| 


= insert 


3 = update (Values before the update 
operation.) 


4 = update (Values after the update 
operation.) 


A bitmask that is based on the column 
ordinals of the change table identifying 
those columns that changed. You 
could examine this value if you had to 
determine which columns have 
changed. 


The remaining columns returned by 
the function are the columns from the 
source table that were identified as 
captured columns when the capture 
instance was created. If no columns 
were originally specified in the 
captured column list, all columns in the 
source table are returned. 


For more information, see cdc.fn_cdc_get_net_changes_<capture_instance> (Transact-SQL). 


Next Step 


After you have created the table-valued function that queries for change data, the next step is to start designing 


the data flow in the package. 


Next topic: Retrieve and Understand the Change Data 


Retrieve and Understand the Change Data 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


In the data flow of an Integration Services package that performs an incremental load of change data, the first 
task is to run the query that retrieves the change data. You execute this query inside a source component in a 
Data Flow task. You can then use downstream transformations and destinations to apply the change data to 
your destination. 





NOTE 


The creation of a query that contains a table-valued function is the third step in the process of creating a package that 
performs an incremental load of change data. For more information about this query, see, Create the Function to Retrieve 
the Change Data. For a description of the overall process for creating a package that performs an incremental load of 
change data, see Change Data Capture (SSIS). 





Adding the Data Flow Task 


In the data flow of the package, you retrieve the change data, separate the rows based on the type of change 
that occurred, and then apply the changes to the destination. 


To add a Data Flow task to the package 
1. In SQL Server Data Tools (SSDT), on the Control Flow tab, add a Data Flow task. 


2. Connect the preceding task that prepared the query string to the Data Flow task. 


Configuring the Source Component to Query for Changes 


The source component uses the query string that was prepared and stored in a variable to calls the table-valued 
function that retrieves the changed data. 








NOTE 


For more information about the query string that was prepared and stored in a variable, see Prepare to Query for the 
Change Data. For more information about the table-valued function that retrieves the change data, see Create the 
Function to Retrieve the Change Data. 





To configure an OLE DB source to retrieve the change data 


1. In SQL Server Data Tools (SSDT), on the Data Flow tab, add an OLE DB source. 

2. In the OLE DB Source Editor, on the Connection Manager page, select the following options: 
a. Configure a valid connection to the source database. 
b. For Data access mode, select SQL command from variable. 
c. For Variable name, select User::SqIDataQuery. 


3. Inthe OLE DB Source Editor, on the Columns page, make sure that all the columns that you want are 
mapped to output columns. 





Next Step 


After you have configured an OLE DB source to retrieve the change data, the next step is to start designing the 


data flow in the package. 


Next topic: Process Inserts, Updates, and Deletes 


Process Inserts, Updates, and Deletes 
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In the data flow of an Integration Services package that performs an incremental load of change data, the 
second task is to separate inserts, updates, and deletes. Then, you can use appropriate commands to apply them 
to the destination. 


NOTE 


The first task in designing the data flow of a package that performs an incremental load of change data is to configure the 
source component that runs the query that retrieves the change data. For more information about this component, see 
Retrieve and Understand the Change Data. For a description of the overall process for creating a package that performs 
an incremental load of change data, see Change Data Capture (SSIS). 











Associating Friendly Values to Separate Inserts, Updates, and Deletes 


In the example query that retrieves change data, the cdc.fn_cdc_get_net_changes_<capture_instance> 
function returns only the column of metadata named __$operation. This metadata column contains an ordinal 
value that indicates which operation caused the change. 





NOTE 


For more information about the query that uses calls the cdc.fn_cdc_get_net_changes_<capture_instance> 
function, see Create the Function to Retrieve the Change Data. 











Matching an ordinal value to its corresponding operation is not as easy as using a mnemonic of the operation. 
For example, 'D' can easily represent a delete operation and ‘I’ represent an insert operation. The example query 
that was created in the topic, Creating the Function to Retrieve the Change Data, makes this conversion from an 
ordinal value to a friendly string value that is returned in a new column. The following segment of code shows 
this conversion: 


select 


case _ ¢operation 
when 1 then 'D' 
when 2 then 'I' 
when 4 then 'U' 
else null 

end as CDC_OPERATION 


Configuring a Conditional Split Transformation to Direct Inserts, 
Updates, and Deletes 
To direct rows of change data to one of three outputs, the Conditional Split transformation is ideal. The 


transformation just checks the value of the CDC_OPERATION column in each row and determines whether 
that change was an insert, update, or delete. 





NOTE 


The CDC_OPERATION column contains a friendly string value derived from the numeric value in the ___$operation 


column. 











To split inserts, updates, and deletes for processing by using a Conditional Split transformation 


1. On the Data Flow tab, add a Conditional Split transformation. 
2. Connect the output of the OLE DB source to the Conditional Split transformation. 


3. In the Conditional Split Transformation Editor, in the lower pane of the editor, enter the following 
three lines to designate the three outputs 


a. Enter a line with the condition cDc_OPERATION == "I" to direct inserted rows to the output for 
inserts. 

b. Enter a line with the condition cDC_OPERATION == "U" to direct updated rows to the output for 
updates. 

c. Enter a line with the condition cDC_OPERATION == "D" to direct deleted rows to the output for 
deletes. 


Next Step 
After you split the rows for processing, the next step is to apply the changes to the destination. 


Next topic: Apply the Changes to the Destination 


See Also 


Conditional Split Transformation 
Split a Dataset by Using the Conditional Split Transformation 


Apply the Changes to the Destination 
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In the data flow of an Integration Services package that performs an incremental load of change data, the third 
and final task is to apply the changes to your destination. You will need one component to apply inserts, one to 
apply updates, and one to apply deletes. 


NOTE 


The second task in designing the data flow of a package that performs an incremental load of change data is to separate 
inserts, updates, and deletes. For more information about this component, see Process Inserts, Updates, and Deletes. For 
a description of the overall process for creating a package that performs an incremental load of change data, see Change 
Data Capture (SSIS). 











Applying Inserts 
To apply inserts, you use an OLE DB destination because the new rows do not require any special handling. 


To process inserts by using an OLE DB Destination 


1. On the Data flow tab, add an OLE DB destination. 


2. Connect the output that contains inserts from the Conditional Split transformation to the OLE DB 
destination. 


3. In the OLE DB Destination Editor, on the Connection Manager page, select the following options: 
a. Select or create an OLE DB Connection Manager for the destination database. 


b. Select a Data access mode option, and then select the destination table or enter a SQL statement 
that contains the destination columns. 


4. On the Mappings page of the editor, map the appropriate columns from the change data to the 
destination table. 


Applying Updates 


To apply updates, you use an OLE DB Command transformation. You use this transformation because you have 
to use a parameterized UPDATE statement to update one row at a time with the new column values. 


NOTE 

You can also use destination components to apply updates. When using this approach, you use the destination 
components to save the rows to temporary tables that you create for this purpose. Then, you use Execute SQL tasks to 
perform bulk update and bulk delete operations against the destination from the temporary tables. 





To process updates by using an OLE DB Command transformation 


1. On the Data flow tab, add an OLE DB Command transformation. 


2. Connect the output that contains updates from the Conditional Split transformation to the OLE DB 
Command transformation. 





3. Inthe Advanced Editor for OLE DB Command, on the Connection Manager tab, select or create an 
OLE DB Connection Manager for the destination database. 


4. In the Advanced Editor for OLE DB Command, on the Component Properties tab, for 
SqlCommand, enter a parameterized UPDATE statement. 


For example, an UPDATE statement for a Customer table might have the following syntax: 


update CDCSample.Customer 

set TerritoryID = ?, 
CustomerType = ?, 
rowguid = ?, 
ModifiedDate = ? 

where CustomerID 


i 
~u 


5. On the Column Mappings tab of the editor, map the appropriate columns from the change data to the 
parameters in the UPDATE statement. 


Applying Deletes 


To apply deletes, you use an OLE DB Command transformation. You use this transformation because you have to 
use a parameterized DELETE statement that deletes a single row at a time based on the column value that 
uniquely identifies the row. 





NOTE 
You can also use destination components to apply deletes. When using this approach, you use the destination 
components to save the rows to temporary tables that you create for this purpose. Then, you use Execute SQL tasks to 


perform bulk update and bulk delete operations against the destination from the temporary tables. 





To process deletes by using an OLE DB Command transformation 


1. On the Data flow tab, add an OLE DB Command transformation to the data flow. 


2. Connect the output that contains deletes from the Conditional Split transformation to the OLE DB 
Command transformation. 


3. Open the Advanced Editor to configure the transformation. 


4. Inthe Advanced Editor for OLE DB Command, on the Connection Manager tab, select or create an 
OLE DB Connection Manager for the destination database. 


5. Inthe Advanced Editor for OLE DB Command, on the Component Properties tab of the editor, for 
SqlCommand, enter a parameterized DELETE statement. 


For example, a DELETE statement for a Customer table might have the following syntax: 


delete from Customer where CustomerID = ? 


6. On the Column Mappings tab of the editor, map the appropriate column from the change data to the 
parameter in the DELETE statement. 


Optimizing Inserts and Updates by Using MERGE Functionality 


You can optimize the processing of inserts and updates by combining certain change data capture options with 





the use of the Transact-SQL MERGE keyword. For more information about the MERGE keyword, see MERGE 
(Transact-SQL). 


In the Transact-SQL statement that retrieves the change data, you can specify a// with merge as the value of the 
row_tilter_option parameter when you call the cdc.fn_cdc_get_net_changes_<capture_instance> function. 
This change data capture function operates more efficiently when it does not have to perform the extra 
processing that is required to distinguish inserts from updates. When you specify the a// with merge parameter 
value, the__$operation value of the change data is 1 for deletes or 5 for changes that were caused by inserts 
or updates. For more information about the Transact-SQL function that is used to retrieve the change data, see 
Retrieve and Understand the Change DataAfter retrieving changes with the a// with merge parameter value, you 
can apply deletes, and output the remaining rows to a temporary table or a staging table. Then, in a downstream 
Execute SQL Task, you can use a single MERGE statement to apply all the inserts or updates from the staging 
table to the destination. 


Perform an Incremental Load of Multiple Tables 
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In the topic, Improving Incremental Loads with Change Data Capture, the diagram illustrates a basic package 
that performs an incremental load on just one table. However, loading one table is not as common as having to 
perform an incremental load of multiple tables. 


When you perform an incremental load of multiple tables, some steps have to be performed once for all the 
tables, and other steps have to be repeated for each source table. You have more than one option for 
implementing these steps in Integration Services: 


e Use a parent package and child packages. 


e Use multiple Data Flow tasks in a single package. 


Loading Multiple Tables by Using a Parent Package and Multiple Child 
Packages 


You can use a parent package to perform those steps that only have to be done once. The child packages will 
perform those steps that have to be done for each source table. 


To create a parent package that performs those steps that only have to be done once 


1. Create a parent package. 

2. In the control flow, use an Execute SQL task or Integration Services expressions to calculate the endpoints. 
For an example of how to calculate endpoints, see Specify an Interval of Change Data. 

3. If needed, use a For Loop container to delay execution until change data for the selected period is ready. 
For an example of such a For Loop container, see Determine Whether the Change Data Is Ready. 


4. Use multiple Execute Package tasks to execute child packages for each table to be loaded. Pass the 
endpoints calculated in the parent package to each child package by using Parent Package Variable 
configurations. 


For more information, see Execute Package Task and Use the Values of Variables and Parameters in a 
Child Package. 


To create child packages to perform those steps that have to be done for each source table 


1. For each source table, create a child package. 


2. In the control flow, use a Script task or an Execute SQL task to assemble the SQL statement that will be 
used to query for changes. 


For an example of how to assemble the query, see Prepare to Query for the Change Data. 


3. Use a single Data Flow task in each child package to load the change data and apply it to the destination. 
Configure the Data Flow as described in the following steps: 


a. In the data flow, use a source component to query the change tables for the changes that fall 
within the selected endpoints. 


For an example of how to query the change tables, see Retrieve and Understand the Change Data. 


b. Use a Conditional Split transformation to direct inserts, updates, and deletes to different outputs 
for appropriate processing. 


For an example of how to configure this transformation to direct output, see Process Inserts, 
Updates, and Deletes. 


c. Use a destination component to apply the inserts to the destination. Use OLE DB Command 
transformations with parameterized UPDATE and DELETE statements to apply updates and deletes 
to the destination. 


For an example of how to use this transformation to apply updates and deletes, see Apply the 
Changes to the Destination. 


Loading Multiple Tables by Using Multiple Data Flow Tasks in a Single 


Package 


Alternatively, you can use a single package that contains a separate Data Flow task for each source table to be 


loaded. 


To load multiple tables by using multiple Data Flow tasks in a single package 


1. Create a single package. 


2. In the control flow, use an Execute SQL Task or Integration Services expressions to calculate the 
endpoints. 


For an example of how to calculate endpoints, see Specify an Interval of Change Data. 


3. If needed, use a For Loop container to delay execution until the change data for the selected interval is 
ready. 


For an example of such a For Loop container, see Determine Whether the Change Data Is Ready. 


4. Usea Script task or an Execute SQL task to assemble the SQL statement that will be used to query for 
changes. 


For an example of how to assemble the query, see Prepare to Query for the Change Data. 


5. Use multiple Data Flow tasks to load the change data from each source table and apply it to the 
destination. Configure each Data Flow task as described in the following steps. 


a. In each data flow, use a source component to query the change tables for the changes that fall 
within the selected endpoints. 


For an example of how to query the change tables, see Retrieve and Understand the Change Data. 


b. Use a Conditional Split transformation to direct inserts, updates, and deletes to different outputs 
for appropriate processing. 


For an example of how to configure this transformation to direct output, see Process Inserts, 
Updates, and Deletes. 


c. Use a destination component to apply the inserts to the destination. Use OLE DB Command 
transformations with parameterized UPDATE and DELETE statements to apply updates and deletes 
to the destination. 


For an example of how to use this transformation to apply updates and deletes, see Apply the 
Changes to the Destination. 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 
The Change Data Capture for Oracle by Attunity download includes the following two components. 
e Change Data Capture Designer for Oracle by Attunity 


® Change Data Capture Service for Oracle by Attunity 


Get the Change Data Capture for Oracle by Attunity download 


Download Microsoft Change Data Capture Designer and Service for Oracle by Attunity for corresponding SQL 
Server version from below links: 


e Microsoft SQL Server 2012 Integration Services Attunity Oracle CDC Designer/Service Feature Pack 


Microsoft SQL Server 2016 Integration Services Attunity Oracle CDC Designer/Service Feature Pack 
e Microsoft SQL Server 2017 Integration Services Attunity Oracle CDC Designer/Service Feature Pack 


Microsoft SQL Server 2019 Integration Services Feature Pack 


Change Data Capture Designer for Oracle by 


Attunity 
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The CDC Designer Console is used to develop and maintain Oracle CDC Instances. The CDC Designer Console is 
a Microsoft Management Console snap-in that contains the following elements: 


e New Instance Wizard: This wizard creates a new Oracle CDC Instance. For information on using the New 
Instance Wizard, see Use the New Instance Wizard. 


e CDC Instance Properties Viewer: This is a docked view showing the status and configuration of the 
selected CDC instance. For information about the properties viewer, see How to Manage a CDC Instance. 


e CDC Instance Properties Editor: This dialog box is used to edit any existing Oracle CDC Service instance. 
For information about editing the CDC instance properties, see Edit Instance Properties. 


Download Microsoft Change Data Capture Designer for Oracle by Attunity for corresponding SQL Server 
version from below links: 


e Microsoft SQL Server 2012 Integration Services Attunity Oracle CDC Designer/Service Feature Pack 
e® Microsoft SQL Server 2016 Integration Services Attunity Oracle CDC Designer/Service Feature Pack 
e Microsoft SQL Server 2017 Integration Services Attunity Oracle CDC Designer/Service Feature Pack 


© Microsoft SQL Server 2019 Integration Services Feature Pack 


In This Documentation 


e The CDC Designer Console Introduction 

e@ Oracle CDC Instance Data Types 

e Error Handling 

e@ The Oracle CDC Instance 

e The Oracle CDC Databases 

e@ Change Data Capture Designer for Oracle by Attunity F1 Help Reference 
e Change Data Capture Designer for Oracle by Attunity How to Guide 
e@ SQL Server Connection for Instance Creation 

e Advanced Connection Properties 

e Oracle Credentials for Running Script 

e@ Oracle Supplemental Logging Script 

e CDC Instance Deployment Script 


@ SQL Server Connection Required Permissions for the CDC Designer 
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The section describes the installation procedures for the Change Data Capture Designer for Oracle by Attunity. 


Installation 


The section describes the installation procedures for the Change Data Capture Designer for Oracle by Attunity. 


The Microsoft(R) Change Data Capture Designer and Service for Oracle by Attunity for Microsoft SQL 
ServerA®) 2016 are part of the SQL Server 2016 Feature Pack. Download components of the Feature Pack 
from the SQL Server 2016 Feature Pack web page. 


Supported Windows Environments 


The CDC Designer Console can run in the following Windows environments: 


e Windows 8 and 8.1 

e Windows 10 

e Windows Server 2012 and 2012 R2 
e Windows Server 2016 


Database Prerequisites 


To work with the Change Data Capture Designer for Oracle by Attunity, you work with an Oracle database. The 
Change Data Capture Designer for Oracle by Attunity supports the following versions: 


Source Oracle Database 
e Oracle Database 10g Release 2 
e Oracle Database 11g Release 1 and Release 2 


e Oracle Database 12c in classic installation (Multitenant installation is not supported.) 


Target SQL Server Database 
e@ SQL Server edition with support for SQL Server CDC 


Software Prerequisites 


You have to use the 32-bit or 64-bit version of the Oracle client software according to the version of the Oracle 
CDC Designer console installed. 


The Oracle CDC Designer Console uses the Oracle ODBC provider to communicate with the source Oracle 
database. 


Running the Installation Program 


This section describes how to install the CDC Designer Console. 
To install the CDC Designer Console 


Double-click the CDC Designer Console installation kit and follow the directions in the installation wizard. 


Uninstalling the CDC Designer Console 


Uninstall the CDC Designer Console by using Control Panel, Programs, and Features. 
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The Oracle CDC Instance supports most Oracle data types. The following sections describe the supported data 


types and the non-supported data types. 


Supported Data Types 


The following table describes the Oracle data types that can be captured and their default mapping to SQL 


Server data types in the change tables. When adding a capture instance for a source Oracle table, you can 


override some of these mappings. 


ORACLE DATABASE DATA TYPE 


BINARY_FLOAT 


BINARY_DOUBLE 


CHAR 


DATE 


FLOAT 


INT 


INTERVAL 


NCHAR 


NUMBER 


NAVARCHAR2 


RAW 


REAL 


TIMESTAMP 


TIMESTAMP WITH TIME ZONE 


TIMESTAMP WITH LOCAL TIME ZONE 


VARCHAR2 


XMLTYPE 


SQL SERVER DATA TYPE 


REAL 


FLOAT 


NVARCHAR 


DATETIME 


FLOAT 


NUMERIC (38) 


DATETIME 


NVARCHAR 


FLOAT 


NVARCHAR 


VARBINARY 


FLOAT 


DATETIME2 


VARCHAR (37) 


VARCHAR (37) 


VARCHAR 


NVARCHAR (MAX) 


Non-Supported Data Types 


Source Oracle tables with columns of the following Oracle data types cannot be captured. Captured columns 
with these data types will show as null; however, a change in their value is indicated in the change mask of the 
captured tables. 


e LONG 

@ XMLTYPE 

e BLOB 

e CLOB 

Source Oracle tables with columns of the following Oracle data types cannot be captured. 
e BFILE 

e ROWID 

e REF 

e UROWID 


e Nested Table 


If the following data types are present in a table they will prevent the LogMinder from getting any data for any 
column of the table: 


e User-defined data types 


e VARRAY 


See Also 
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An Oracle CDC Instance mines changes from a single Oracle source database (an Oracle RAC cluster is 
considered a single database) and writes the committed changes to change tables in a CDC database in the 
target SQL Server instance. 


A CDC Instance maintains its state in a system table called cdc.xdbcdc_state. This table can be queried any 
time to find the state of the CDC Instance. For more information about the cdc.xdbcdc_state table, see 
cdc.xdbcdc_state. 


The table below describes the CDC Instance states in the xdbcdc_state table. 


For each state, the following two indications are shown for the corresponding columns in the cdc.xdbcdc_state 
table: 


e Instance is not active (there is no Windows process currently handling it). If the active column value is 1, 
a subprocess of the Oracle CDC Service handling this specific Oracle CDC Instance is running. 


e Ifthe error column value is 0, the Oracle CDC Instance is not in an error condition. If the error column 
value is 1, there is an error that prevents the Oracle CDC Instance from processing changes. 


If the error column has a value of 1 and the active column value is also 1, then a recoverable error is 
occurring for the Oracle CDC Instance, which can be resolved automatically. If the error column has a 
value of 1 and the active column has a value of 0, then in most cases a manual workaround may be 
needed to resolve the problem before processing can be resumed. 


The following table describes the various status codes that the Oracle CDC Instance may report in its state table. 


ACTIVE STATUS 


STATUS CODE ERROR STATUS CODE DESCRIPTION SUBSTATUS 

ABORTED 0 1 The Oracle CDC The ABORTED 
Instance is not substatus is 
running. The established by the 
ABORTED substatus Oracle CDC Service 
indicates that the main instance when 


Oracle CDC Instance it detects that the 
was ACTIVE and then Oracle CDC Instance 
has stopped is not running while 
unexpectedly. its status is ACTIVE. 


STATUS 


ERROR 


RUNNING 


STOPPED 


ACTIVE STATUS 
CODE 


ERROR STATUS CODE 


DESCRIPTION 


The Oracle CDC 
Instance is not 
running. The ERROR 
status indicates that 
the CDC instance 
was ACTIVE but then 
encountered an error 
that is not 
recoverable and 
disabled itself. 


The CDC instance is 
running and is 
processing change 
records. 


The CDC instance is 
not running. 


SUBSTATUS 


MISCONFIGURED: 
An unrecoverable 
configuration error 
was detected. 


PASSWORD- 
REQUIRED: There is 
no password set for 
the Change Data 
Capture Designer for 
Oracle by Attunity or 
the configured 
password is not valid. 
This can be because 
of a change to the 
service asymmetric 
key password. 


IDLE: All change 
records were 
processed and stored 
into the target 
control (_CT) tables. 
There is no active 
transaction with the 
control tables. 


PROCESSING: There 
are change records 
being processed that 
are not yet written to 
the control (_CT) 
tables. 


The STOP substatus 
indicates that the 
CDC instance was 
ACTIVE and then was 
stopped correctly. 


STATUS 


SUSPENDED 


DATAERROR 


ACTIVE STATUS 
CODE 


ERROR STATUS CODE 


DESCRIPTION 


The CDC instance is 
running but 
processing is 
suspended due to a 
recoverable error. 


This status code is 
only used for the 
xdbcdc_trace table. 
It does not appear in 
the xdbcdc_state 
table. Trace records 
with this status 
indicate a problem 
with an Oracle log 
record. The bad log 
record is stored in 
the data column as a 
BLOB. 


SUBSTATUS 


DISCONNECTED: The 
connection with the 
source Oracle 
database cannot be 
established. 
Processing will 
resume once 
connection is 
restored. 


STORAGE: The 
storage is full. 
Processing will 
resume when storage 
becomes available. In 
some cases, this 
status may not 
appear because the 
status table cannot 
be updated. 


LOGGER: The logger 
is connected to 
Oracle but it cannot 
read the Oracle 
transaction logs 
because of a 
temporary problem. 


BADRECORD: The 
attached log record 
could not be parsed. 


CONVERT-ERROR: 
The data in some 
columns could not be 
converted to the 
target columns in the 
capture table. This 
status may appear 
only if the 
configuration 
specifies that 
conversion errors 
should produce trace 
records. 


Because the Oracle CDC Service state is stored in SQL Server, there may be cases where the state value in the 
database might not reflect the actual state of the service. The most common scenario is when the service loses 
its connection to SQL Server and cannot resume it (for any reason). In that case, the state stored in 
cdc.xdbcdc_state becomes stale. If the last update timestamp (UTC) is more than a minute old, the state is 
probably stale. In this case, use the Windows Event Viewer to find additional information about the status of the 


service. 


Error Handling 


This section describes how the Oracle CDC Service handles errors. 


Logging 


The Oracle CDC Service creates error information in one of the following places. 


e The Windows event log, which is used with logging errors and to indicate Oracle CDC Service life cycle 
events (starting, stopping, (re)connection to the target SQL Server instance). 


e The MSXDBCDC.dbo.xdbcdc_trace table, which is used for general logging and tracing by the Oracle CDC 


Service main process. 


e The <cdc-database>.cdc.xdbcdc_trace table, which is used for general logging and tracing by Oracle CDC 
Instances. This means that errors related to a specific Oracle CDC Instance are logged to that instance's 
trace table. 


Information is logged by the Oracle CDC service when the service: 
e ls started or stopped by the service control manager. 


e Cannot connect to the associated SQL Server instance and when it successfully establishes a connection 


following a failure. 
e Encounters an error starting Oracle CDC Service instances. 
e Detects that an Oracle CDC Instance has aborted. 
e Encounters an unexpected error. 
Information is logged by the CDC instance when the instance: 
e Is enabled or disabled. 
e Encounters an error. 
e Recovers from a recoverable error. 
The trace table is also used for recording detailed trace information for troubleshooting. 


Handling Source Oracle Connection Errors 

The Oracle CDC Service needs a persistent connection with the source Oracle database. Many connection errors 
that are unrelated to the service configuration (such as networking errors) are considered transient. Therefore, if 
the Oracle CDC Service cannot establish connection with the Oracle database (either on start or during work 
following a disconnection), the service changes its state to SUSPENDED/DISCONNECTED and enters a retry loop 
where the connection is retried at regular intervals. When the connection is re-established, processing 


continues. 


Other types of connection errors are not transient (for example, bad credentials, insufficient privileges, and bad 
database address). When these errors occur, the Oracle CDC Service state is set to ERROR/MISCONFIGURED or 
to ERROR/PASSWORD-REQUIRED and the service is disabled. When the user fixes the underlying error, the 
Oracle CDC Instance should be manually re-enabled for processing to resume. 


When it is not clear whether the error is transient, it is best to assume it is transient. 


Handling Target SQL Server Connection Errors 


The Oracle CDC Service needs a persistent connection to the target SQL Server instance. This connection is used 
to: 


e Ensure that there are no other services by the same name currently working with this SQL Server 


instance. 


e Check which Oracle CDC Instance is enabled or disabled and start (or stop) its subprocess. 


When the service establishes a connection with the target SQL Server instance and verifies that it is the only 
Oracle CDC service by this name that is working, it can check which Oracle CDC instances are enabled and start 
their handling processes (afterward the service stops these processes when they are disabled). The Oracle CDC 
instances use their SQL Server connections to work with the CDC database of the Oracle CDC instance. 


How errors are handled when the connection to the target SQL Server fails depends on whether the errors are 
transient. 


For known non-transient errors (such as bad credentials, insufficient privileges, bad connection information), the 
service logs an error to the Windows event log and stops (it cannot write to the trace table because it cannot 
connect to SQL Server). In this case, the user must resolve the error and restart the Oracle CDC Windows 
service. 


For transient errors and unexpected errors, the operation is retried several times and if the failure persists for a 
significant time period, the CDC Service stops its CDC Instance subprocesses and goes back to its initial 
connection attempt (by this time, an Oracle CDC Service on another machine may have already taken control of 


the named CDC service). 


Handling Target SQL Server Storage Full Errors 
When the Oracle CDC Service detects that it cannot insert new change data into the target SQL Server CDC 


database, it writes a warning to the event log and tries to insert a trace record (although that may fail for the 
same reason). It then retries the operation in a specific interval until it is successful. 


Handling Oracle CDC Errors 
The Oracle CDC Instance reads the Oracle transaction log and processes it. If the CDC processing encounters an 
error, it is reported in the cdc.xdbcdc_state table and the user needs to manually intervene based on the 


reported error. 


For example, the Oracle CDC Instance may not be active for an extended duration and the required Oracle 
transaction log files are no longer available. In this case, the Oracle DBA must restore the required logs for the 
Oracle CDC Instance to resume processing. 


Handling Unexpected Oracle CDC Instance Failures 


The Oracle CDC Service monitors its CDC Instance subprocesses. When a CDC Instance subprocess aborts, the 
CDC Service disables it in the MSXDBCDC.dbo.xdbcdc_databases table and updates its cdc.xdbcdc_state status to 
ABORTED. In this case, the standard Windows Error Reporting dialog box is used to report this error for further 
analysis. 


See Also 
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The Oracle CDC Instance is a process created by the Oracle CDC Service to process changes captured from a 
single Oracle source database. The Oracle CDC Instance retrieves its configuration from the cdc.xdbcdc_config 
table and maintains its state in the cdc.xdbcdc_state table. These tables are part of the CDC database, which 
defines the Oracle CDC Instance. For more information about the xdbcdc database and tables see The CDC 
Databases. 


The following describes the tasks carried out by the Oracle CDC instance: 


e Handling service startup verification: When started, the CDC instance loads its configuration from 
the xdbcdc_config table and performs a series of status verifications that ensure that the CDC instance 
persisted state is consistent and that it can start processing changes. 


e Preparing for change capture: When the verification passes successfully, the Oracle CDC Instance 
scans all of the capture instances currently defined and prepares the Oracle LogMiner queries and other 
support structures required for change capture. In addition, the Oracle instance re-loads the internal 
capture state that was saved the last time the Oracle CDC Instance run. 


e Capturing changes from Oracle: The Oracle CDC Instance pools changes from Oracle by means of the 
Oracle LogMiner facility, orders them in according to transaction commit, and then changes the time in a 
transaction and writes them to the SQL Server change tables in the CDC database. 


e Handling service shutdown: The life cycle of the Oracle CDC Instance is managed by the Oracle CDC 
Service. When the Oracle CDC Instance is requested to shut down, it performs the following tasks: 


o Stops reading from the Oracle transaction log. 
o Stops writing completed Oracle transactions to the CDC database. 


o Waits for up to 30 seconds (if necessary) until the current transaction finishes writing to the CDC 
database. If more than 30 seconds pass, the writing is cancelled and transaction is rolled back (to 
be retried when the CDC instance is restarted). 


o In aseparate thread, writes as many memory-cached records as possible to the staged 
transactions table for up to 30 seconds (from the oldest transaction to the newest), then updates 
the xdbcdc_state table and commits all the changes. 


e Handling configuration changes: The Oracle CDC Instance is notified about configuration changes 
either from the CDC Service or by detecting a new version in the cdc.xdbcdc_config table. Most 
changes do not require the restart of the Oracle CDC Instance (for example, adding or removing capture 
instances). However, some changes, such as changing the Oracle connection string or access credentials 
do require the restart of the CDC Instance. 


e Handling recovery: When an Oracle CDC Instance starts its internal state is restored from the 
xdbcdc_state and the xdbcdc_staged_transactions tables. Once the state is restored, the CDC 
instance proceeds as usual. 


See Also 
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An Oracle CDC Instance is associated with a SQL Server database by the same name on the target SQL Server 
instance. This database is called the Oracle CDC database (or the CDC database). 


The CDC database is created and configured using the Oracle CDC Designer Console and it contains the 
following elements: 


e A cde schema created by enabling the database for SQL Server CDC. 
e Aset of cdc.xdbcdc_xxxx tables used by the Oracle CDC Instance. 
e Aset of empty mirror tables with the definitions of the captured tables in tuphe Source Oracle database. 


e Aset of change tables and change access functions that are generated by the SQL Server CDC 
mechanism and are identical to those used in the regular, non-Oracle, SQL Server CDC. 


The cde schema is initially accessible only to the members of the dbowner fixed database role. Access to the 
change tables and change functions is determined by the same security model as the SQL Server CDC. For more 
information about the security model, see Security Model. 


Creating the CDC Database 


In most cases, the CDC database is created using the CDC Designer Console, but it can also be created with a 
CDC deployment script that is generated using the CDC Designer Console. The SQL Server system administrator 
can change the database settings if necessary (for items such as for storage, security, or availability). 


For more information about using the CDC Designer Console to create the database tables and the necessary 
scripts, see Use the New Instance Wizard. 


CDC Database User Roles 


When a CDC Database is created and enabled for CDC, a database user called cdc_service is created in the CDC 
database and is associated with the SQL Server login that the Oracle CDC Service was configured with. This user 
is made a member of the db_datareader, db_datawriter, and db_ddladmin database roles. If the SQL Server 
login is also the associated with the dbo user then the cdc_service is not created. 


This role assignment allows the Oracle CDC Service to update the tables under the cde schema with captured 
data and with control information. 


When a CDC database is created and CDC source Oracle tables are set up, the CDC database owner can grant 
SELECT permission of mirror tables and define SQL Server CDC gating roles to control who accesses the change 
data. 


Mirror Tables 


For each captured table, <schema-name>.<table-name>, in the Oracle source database, a similar empty table is 
created in the CDC Database, with the same schema and table name. Oracle source tables with the schema 
name cdc (not case sensitive) cannot be captured because the cdc schema in SQL Server is reserved for the 
SQL Server CDC. 


The mirror tables are empty; no data is stored in them. They are used to enable the standard SQL Server CDC 
infrastructure that is used by the Oracle CDC Instance. To prevent data from being inserted or updated into the 
mirror tables, all UPDATE, DELETE, and INSERT operations are denied for PUBLIC. This ensures that they cannot 
be modified. 


Access to Change Data 


Because of the SQL Server security model used to gain access to the change data that is associated with a 
capture instance, the user must be granted select access to all the captured columns of the associated mirror 
table (access permissions to the original Oracle tables do not provide access to the change tables in SQL Server). 
For information on the SQL Server security model, see Security Model. 


In addition, if a gating role is specified when the capture instance is created, the caller must also be a member of 
the specified gating role. Other general change data capture functions for accessing metadata are accessible to 
all database users through the PUBLIC role, although access to the returned metadata is usually gated by using 
select access to the underlying source tables, and by membership in any defined gating roles. 


Change data may be read by calling special table-based functions generated by the SQL Server CDC component 
when a capture instance is created. For more information about this function, see Change Data Capture 
Functions (Transact-SQL). 


Accessing CDC data through the Integration Services CDC Source component is subject to the same rules. 


The CDC Database Tables 


This section describes the following tables in the CDC database. 
e@ Change Tables (_CT) 

e cdclsn_time_mapping 

@ cdcxdbcdc_config 

e cdcxdbcdc_state 

e cdc.xdbcdc_trace 

e cdc.xdbcdc_staged_transactions 


Change Tables (_CT) 


The change tables are created from the mirror tables. They contain the change data that is captured from the 
Oracle database. The tables are named according to the following convention: 


[cdc].[<capture-instance>_CT] 


When capture is initially enabled for table <schema-name>.<table-name> , the default capture instance name is 
<schema-name>_<table-name> . For example, the default capture instance name for the Oracle HREMPLOYEES 
table is HR_LEMPLOYEES and the associated change table is [cdc]. [HR_EMPLOYEES_CT]. 


The capture tables are written to by the Oracle CDC Instance. They are read using special table-valued functions 
generated by SQL Server when the capture instance is created. For example, 

fn_cdc_get_all_changes_HR_EMPLOYEES . For more information about these CDC functions see Change Data 
Capture Functions (Transact-SQL). 


cdc.Isn_time_mapping 


The [cdc].[Isn_time_mapping] table is generated by the SQL Server CDC component. Its use in the case of 
Oracle CDC is different than its normal use. 


For the Oracle CDC, the LSN values stored in this table are based on the Oracle System Change Number (SCN) 
value associated with the change. The first 6 bytes of the LSN value is the original Oracle SCN number. 


Also when using the Oracle CDC, the time columns ( tran_begin_time and tran_end_time ) store the UTC time of 


the change rather than the local time as it does with the regular SQL Server CDC. This ensures that daylight 


savings time changes do not impact the data stored in the Isn_time_mapping. 


cdc.xdbcdc_config 


This table contains the configuration data for the Oracle CDC Instance. It is updated using the CDC Designer 


Console. This table has only one row. 


The following table describes the cdc.xdbcdc_config table columns. 


ITEM 


version 


connect_string 


use_windows_authentication 


username 


password 


transaction_staging_timeout 


DESCRIPTION 


This keeps track of the version of the CDC instance 
configuration. It is updated each time that the table is 
updated and each time a new capture instance is added or 
an existing capture instance is removed. 


An Oracle connection string. A basic example is: 


<server>:<port>/<instance> (for example, 


erp.contoso.com:1521/orcl ). 


The connection string can also specify an Oracle Net connect 
descriptor, for example, 


(DESCRIPTION=(ADDRESS=(PROTOCOL=tcp) 
(HOST=erp.contoso.com) (PORT=1521)) (CONNECT_DATA= 
(SERVICE_NAME=orcl))) 


If using a directory server or tnsnames, the connect string 
can be the name of the connection. 


For more information about Oracle connection strings, see 
https://go.microsoft.com/fwlink/?Linkld=231153 for detailed 
information on Oracle database connection strings for the 
Oracle Instant Client that is used by the Oracle CDC Service. 


A Boolean value that can be: 


0: An Oracle user name and password are provided for 
authentication (the default) 


1: Windows authentication is used to connect to the Oracle 
database. You can use this option only if the Oracle database 
is configured to work with Windows authentication. 


The name of the log-mining Oracle database user. This is 
mandatory only if use_windows_authentication = 0. 


The password for the log-mining Oracle database user. This 
is mandatory only if use_windows_authentication = 0. 


The time, in seconds, that an uncommitted Oracle 
transaction is kept in memory before being written to the 
cdc.xdbcdc_staged_transactions table. The default is 120 
seconds. 


ITEM 


memory_limit 


options 


The following table describes the available options. 


NAME 


trace 


cdc_update_state 
_interval 


target_max_batc 
hed_transactions 


target_idle_Isn_u 
pdate_interval 


DEFAULT 


False 


10 


100 


10 


MIN 


DESCRIPTION 


The limit on the amount of memory, in Mb, that can be used 
for caching data in memory. A lower setting causes more 
transaction to be written to the 
cdc.xdbcdc_staged_transactions table. The default is 50 
Mb. 


A list of options in the form of name[=value]f[; ] - it is used 
for specifying secondary options (for example, tracing, 
tuning). See the table below for a description of the available 
options. 


MAX STATIC DESCRIPTION 
- False The available 
values are: 
True 
False 
on 
off 
120 False The size (in 
Kbytes) of 


memory chunks 
allocated for a 
transaction (a 
transaction can 
allocate more 
than one chunk). 
See the 
memory_limit 
column in 
cdc.xdbcdc_confi 
g table. 


1000 True The maximum 
number of 
Oracle 
transactions that 
can be processed 
as one 
transaction in 
SQL Server CT 
tables update. 


1 False The interval (in 
seconds) for 
updating the 
Isn_time_mapp 
ing table when 
the captured 
tables have no 
activity. 


NAME 


trace_retention_ 
period 


sql_reconnect_int 
erval 


sql_reconnect_li 
mit 


cdc_restart_limit 


DEFAULT 


24 


6 


MIN 


MAX 


24*31 


3600 


3600 


STATIC 


False 


False 


False 


False 


DESCRIPTION 


The amount of 
time (in hours to 
keep messages 
in the trace 
table). 


The amount of 
time (in seconds) 
to wait before 
reconnecting to 
SQL Server. This 
interval is used 
in addition to 
SQL Server 
client's connect 
timeout. 


The maximum 
number of SQL 
Server 
reconnections. 
The default -1 
means that the 
process tries to 
reconnect until it 
stops. 


In most cases, 
the CDC service 
restarts an 
abnormally 
ended CDC 
instance 
automatically. 
This property 
defines after how 
many failures per 
hour the service 
stops to restart 
the instance. The 
value -1 means 
that the instance 
should be always 
restarted. 


The Service 
returns to restart 
the instance after 
any update of 
the configuration 
table. 


NAME 


cdc_memory_rep 
ort 


target_command 
_timeout 


source_character 
_set 


source_error_retr 
y_interval 


source_prefetch_ 
size 


source_max_tabl 
es_in_query 


source_read_retr 
y_interval 


DEFAULT 


600 


30 


100 


100 


MIN 


MAX 


1000 


3600 


3600 


10000 


10000 


3600 


STATIC 


False 


False 


True 


False 


True 


True 


False 


DESCRIPTION 


If the value of 
the parameter 
was changed, the 
CDC Instance 
prints its 
memory report 
on the trace 
table. 


Command 
timeout working 
with SQL Server. 


Can be set toa 
specific Oracle 
encoding to be 
used instead of 
the Oracle 
database 
codepage. This 
may be of use 
when the actual 
encoding the 
character data is 
using is different 
than the one 
expressed by the 
Oracle database 
codepage. 


Used before 
retry on several 
errors such as a 
connection error 
or temporary 
lack of 
synchronization 
between system 
tables. 


Size of the 
prefetch batch. 


Maximum 
number of tables 
in WHERE clause 
before switching 
to reading the 
Oracle log 
without table 
filtering. 


The amount of 
time the source 
waits before 
trying to read 
the Oracle 
transaction logs 
on EOF again. 


NAME 


source_reconnec 
tinterval 


source_reconnec 
t_limit 


source_comman 
d_timeout 


source_connectio 
n_timeout 


trace_data_errors 


CDC_stop_on_br 
eaking_schema_c 
hanges 


source_oracle_ho 
me 


DEFAULT 


30 


-1 


30 


30 


True 


False 


MIN 


MAX 


3600 


3600 


3600 


STATIC 


False 


False 


False 


False 


False 


False 


False 


DESCRIPTION 


How long (in 
seconds) to wait 
before trying to 
re-connect to 
the source 
database. 


The maximum 
number of the 
source database 
reconnections. 
The default -1 
means that the 
process tries to 
reconnect until it 
is stopped. 


Connection 
timeout working 
with Oracle. 


Connection 
timeout working 
with SQL Server. 


Boolean. True 
indicates to log 
data conversion 
and truncation 
errors. 


Boolean. True 
indicates to stop 
when breaking 
schema change 
is detected. 


False indicates 
to drop the 
mirror table and 
capture instance. 


Can be set toa 
specific Oracle 
Home path or an 
Oracle Home 
Name that the 
CDC instance will 
use to connect 
to Oracle. 


cdc.xdbcdc_state 


This table contains information about the persisted state of the Oracle CDC Instance. The capture state is used in 


recovery and fail-over scenarios and for health monitoring. 


The following table describes the cdc.xdbcdc_state table columns. 


ITEM 


status 


sub_status 


active 


error 


status_message 


timestamp 


active_capture_node 


last_transaction_timestamp 


last_change_timestamp 


transaction_log_head_cn 


transaction_log_tail_cn 


current_cn 


software_version 


completed_transactions 


written_changes 


DESCRIPTION 


The current status code for the current Oracle CDC Instance. 
The status describes the current state for the CDC. 


A second level status that provides additional information 
about the current status. 


A Boolean value that can be: 
0: The Oracle CDC Instance process is not active. 


1: The Oracle CDC Instance process is active. 


A Boolean value that can be: 
0: The Oracle CDC Instance process is not in an error state. 


1: The Oracle CDC Instance is in an error state. 


A string that provides a description of the error or status. 


The timestamp with the time (UTC) that the capture state 
was last updated. 


The name of the host (the host can be a node on a cluster) 
that is currently running the Oracle CDC Service and the 
Oracle CDC Instance (which is processing the Oracle 
transaction logs). 


A timestamp with the time (UTC) when the last transaction 
that was written to the change tables. 


A timestamp with the time (UTC) when the most recent 
change record was read from the source Oracle transaction 
log. This timestamp helps to identify the current latency of 
the CDC process. 


The most recent change number (CN) read from the Oracle 
transaction log. 


The change number (CN) on the Oracle transaction log 
where the Oracle CDC Instance repositions to in case of a 
restart or recovery. 


The most recent change number (CN) known to be in the 
source database. 


The internal version of the Oracle CDC Service. 


The number of transactions processed since the CDC was 
last reset. 


The number of change records written to the SQL Server 
change tables. 


ITEM DESCRIPTION 


read_changes The number of change records read from the source Oracle 
transaction log. 


staged_transactions The number of currently active transactions that are staged 
in the cdc.xdbcdc_staged_transactions table. 


cdc.xdbcdc_trace 


This table contains information about the operation of the CDC instance. Information stored in this table 
includes error records, notable status changes, and trace records. Error information is also written to the 


Windows event log to ensure that the information is available if the cdc.xcbcdc_trace table is unavailable. 


The following table describes the cdc.xdbcdc_trace table columns. 


ITEM DESCRIPTION 
timestamp The exact UTC timestamp when the trace record was written. 
type Contains one of the following values. 

ERROR 

INFO 

TRACE 
node The name of the node on which the record was written. 
status The status code that is used by the state table. 
sub_status The sub-status code that is used by the state table. 
status_message The status message that is used by the state table. 
data Additional data for cases when the error or trace record 


contains a payload (for example, a corrupted log record). 


cdc.xdbcdc_staged_transactions 


This table stores change records for large or long-running transactions until the transaction commit or rollback 
event is captured. The Oracle CDC Service orders captured log records by transaction commit time and then by 
chronological order for each transaction. Log records for the same transaction are stored in memory until the 
transaction ends and then are written to the target change table or discarded (in case of a rollback). Because 
there is a limited amount of memory available, large transactions are written into the 
cdc.xdbcdc_staged_transactions table until the transaction is complete. Transactions are also written to the 
staging table when they run for a long time. Therefore, when the Oracle CDC Instance is restarted, the old 
changes do not need to be re-read from the Oracle transaction logs. 


The following table describes the cdc.xdbcdc_staged_transactions table columns. 


ITEM DESCRIPTION 


transaction_id The unique transaction identifier of the transaction being 
staged. 


ITEM 


seq_num 


data_start_cn 


data_end_cn 


data 


See Also 


Change Data Capture Designer for Oracle by Attunity 


DESCRIPTION 


The number of xcbcdc_staged_transactions row for the 
current transaction (starting with 0). 


The change number (CN) for the first change in the data in 
this row. 


The change number (CN) for the last change in the data in 
this row. 


The staged changes for the transaction in the form of a 
BLOB. 


Known errors and resolutions with change data 


capture for Oracle by Attunity 
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APPLIES TO: @ sQu Server @ Azure SQL Managed Instance %* Azure Synapse Analytics %’ Parallel 
Data Warehouse 


This topic lists the top issues and known resolutions when viewing a change data capture (CDC) instance in the 
Oracle CDC Designer configuration tool. This tool is part of the Change Data Capture for Oracle by Attunity that 
is included starting with SQL Server 2012. 


Bug fixes 


Before spending too much time troubleshooting, it is important to use the latest builds of CDC for Oracle by 
Attunity to avoid known issues such as these: 


SQL Server 2017 


Version 5.0.0.111 contains these fixes: 


e Bug fix - Oracle CDC Designer fails with "Incorrect syntax near the keyword 'KEY'™ error when adding an 
Oracle table. 

e Improvement - Improved support for RAC, this includes better handling when an RAC node is restarted. 

e Bug fix - The CDC is not working with Oracle 10.2 due to requesting NEXT_CHANGE# from the v$log. 


Version 5.0.0.93 contains these fixes: 


e Microsoft CDC for Oracle by Attunity Designer fails with "Incorrect syntax near the word 'KEY'" error when 
adding an Oracle table. 


SQL Server 2016 


Version 4.0.107 contains these fixes: 


e Bug Fixes —- Oracle CDC Designer fails with "Incorrect syntax near the keyword 'KEY' error when adding an 
Oracle Table. 

e Improvement -— Improved support for RAC, this includes better handling when a RAC node is restarted. 

e Bug Fixes — The CDC is not working with Oracle 10.2 due to requesting NEXT_CHANGE# from the v$log. 


Version 4.0.0.95 contains these fixes: 


e Bug Fixes —- Oracle CDC Designer fails with "Incorrect syntax near the keyword 'KEY'" error when adding an 
Oracle Table. 


Version 4.0.0.88 contains these fixes: 


e Properties added in the Advanced options of the Attunity CDC instance are removed when a table is added 
or removed from CDC. 


e Attunity CDC stops working after applying SQL fix that adds __ $command_id column 


SQL Server 2014 


Version 2.0.0.114 contains these fixes: 


e Bug Fixes —- Oracle CDC Designer fails with "Incorrect syntax near the keyword 'KEY' error when adding an 


Oracle Table. 
e Improvement — Improved support for RAC, this includes better handling when a RAC node is restarted. 


e Bug Fixes — The CDC is not working with Oracle 10.2 due to requesting NEXT_CHANGE# from the v$log. 
Version 2.0.0.92 contains these fixes: 


e Properties added in the Advanced options of the Attunity CDC instance are removed when a table is added 
or removed from CDC. Attunity CDC stops working after applying SQL fix that adds __$command_id column 
e@ The metadata validation for Oracle table cdc.table_name failed. Column column_name index is out of range. 
And this issue: Oracle CDC service shows aborted status when you use CDC for Oracle by Attunity 
o Fixed in Cumulative Update 7 for SQL Server 2014 RTMas described in KB 2894025. 
e Some changes are missed and are not replicated to the SQL Server database. This issue occurs when a table 
contains more than one character large binary object (CLOB) and one of the CLOBs has a large value. 
o Fixed in Cumulative Update 7 for SQL Server 2014 SP7 and Cumulative Update 8 for SQL Server 
2014 RTMas described in KB 3029096. 
e Change Data Capture for Oracle by Attunity stops working when Oracle tables have column with Long data 
type. 
o Fixed in Cumulative Update 5 for SQL Server 2014 SP71 and Cumulative Update 12 for SQL 2014 RTM 
as described in KB KB4017793. 


SQL Server 2012 


Version 1.1.0.102 contains these fixes: 


e Properties added in the Advanced options of the Attunity CDC instance are removed when a table is added 
or removed from CDC. Attunity CDC stops working after applying SQL fix that adds __$command_id column 

e CDC for Oracle instance hangs when you start it, and does not capture changes. Oracle server memory may 
increase until it runs out of memory or crash. 

e@ 2672759: Error message when you use the Microsoft Change Data Capture Service for Oracle by Attunity: 
"ORA-00600: internal error code". Add the SOURCE level tracing and confirm if you get the same ORA- 
00600 error. Fixed by an Oracle patch download. 

e Multiple Partitions 
o When you use more than 10 partitions on an Oracle table, the CDC instance cannot capture all the 

changes for the table. When the Oracle table is defined with more than 10 partitions, the changes are 
only captured from the last 10 partitions. Fixed in the Service Pack 7 release for SQL Server 2012. See 
SP1 Feature Pack download page. 

e Changes are lost 

o The capturing of events can go into an infinite loop and stop capturing new data changes (related to 
Oracle bug 5623813). When on Oracle RAC environment is performing a stop or resume of the CDC 
instance, changes can be skipped/lost. This means the SQL Server change data capture will be missing 
important rows, and thus there is data loss in the data warehouse or subscribing system. Fixed in the 
Service Pack 7 release for SQL Server 2072. See SP1 Feature Pack download page 

e Double widths on columns in SQL 
o When creating a CDC for Oracle instance, in the scripts to run against SQL Server, the length of a 

variable width data type column is doubled in SQL Server tables that are created in the script. For 
example, if you try to track changes on a VARCHAR2(10) column in an Oracle table, then the 
corresponding column in the SQL Server table is NVARCHAR(20) in the deployment script. Fix in 
either Cumulative Update 2 for SQL Server 2012 SP7 or Cumulative update 5 for SQL Server 2012 as 
described in KB 2769673. 

e DDL Data is truncated 
o When you run a Data Definition Language (DDL) statement that is more than 4,000 bytes against an 

Oracle database that contains non-Latin characters, CDC for Oracle by Attunity fails. Additionally, you 


see the error message ORA-01406: fetched column value was truncated. . Fixed in Cumulative Update 4 
for SQL Server 2012 SP7 as described in KB 2839806. 

e Changes are lost in last two columns 
o Fixed in Cumulative update 6 for SQL Server 2012 SP7 as described in KB 2874879. 

e SQL Transaction log grows when you use CDC for Oracle 
o When Change Data Capture for Oracle instances are configured, the SQL database that receives the 

changed data will have mirrored tables, with transactions marked for replication. This behavior occurs 
because CDC for Oracle relies on underlying system stored procedures that resemble those that are 
used in CDC for SQL Server. However, because there is no SQL CDC replication involved when CDC for 
Oracle is used alone, there is no log reader to clear the transactions that are marked for replication. 
Because the transaction does not have to be replicated in SQL Server, it's safe to manually mark the 
transaction as distributed by using the workaround that's described later in this article. More 
information can be found in KB 2871474. 

e Error ORACDC@@eT: Error encountered at position to change event - SCN not found - EOF simulated . Fixed in 
Cumulative Update 7 for SQL Server 2012 SP7 as described in KB 2883524. 

e The metadata validation for Oracle table cdc.table_name failed. Column column_name index is out of range. 
Fixed in Cumulative Update 7 for SQL Server 2012 SP7 as described in KB 2883524. 

e@ Oracle CDC service shows aborted status when you use CDC for Oracle by Attunity in SQL Server 2012. 
Fixed in Cumulative Update 8 for SQL Server 2012 SP7 as described in KB 2923839. 

e@ Some changes are missed and are not replicated to the SQL Server databases. This issue occurs when a table 
contains more than one character large binary object (CLOB) and one of the CLOBs has a large value. Fixed in 
Cumulative Update 8 for SQL Server 2012 SP7 as described in KB 2923839. 

e Change Data Capture for Oracle by Attunity stops working when Oracle tables have column with Long data 
type. Fixed in Cumulative Update 2 for SQL Server 2012 SP3 and Cumulative Update 171 for SQL 2012 SP2 
as described in KB KB4017793. 


Collect detailed logs 


This section explains how to collect errors and events from the CDC instance. 


Management console 


You can see errors in the Status messages filed within the Oracle Change Data Capture Designer management 
console when a CDC instance is highlighted in the left pane. 


Query trace table 


You can query the trace table in the CDC database within SQL Server to see logged errors. 


Save output from basic logging 


To capture diagnostics, select Collect Diagnostics on the status tab in the Oracle Change Data Capture 


management console. 


File Action View Help 
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(@ Oracle CDC Services Status | Oracle | Tables | Advanced 
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Status: 1) 
Detailed status: UNEXPECTED Collect Diagnostics 


The Target component failed with retum code 2. ODBC err: RetCode: 
SQL_ERROR SaqlStat: 42S02 NativeEror: 208 Message: [Microsoft][SQL Server 
Native Client 11.0)[SQL Server]invalid object name ‘cdc Jsn_time_mapping’. 





Status message: 

















Choose a start time and select a location for the log file. Then select Create to start the diagnostics collection. 





Diagnostics information is collected from the Oracle Environment and from the xdbcdc_trace table. 
This information will help analyze the operation of the product at your site. Please provide this file 
when filling a support case. 





Start time : ————————— 15:55:27 — 








eo 





Detailed errors 

You can increase the level of tracing collected by the instance and repeat the scenario to gather more detailed 
logging. To do so, select Properties under Actions and then add a new property in the Advanced Settings 
grid on the Advanced tab. Set the name of the property to trace and then set the value to SOURCE . 


| | 


Start 





Stop 

Reset 

Delete 

Collect Diagnostics 
Oracle Logging Script F 
CDC Instance Deployment Script r 
View r 


Help 











Reproduce the error and then select the Collect diagnostics option to gather logs. 
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Status: 1) 





UNEXPECTED Collect Diagnostics 





failed with retum code 2. ODBC error: RetCode: 
Native Client 11 OJSQL Serverlinvalid object name ‘cde Isn_time_mapping’. 








ORA-00942 Table of view does not exist 


This is a common error displayed in the Status message field of the CDC Instance. The instance retries 
numerous times, so the status icon will change to green momentarily, but then it will fail with the red 
exclamation and UNEXPECTED status. 


(03 Orade CDC Services 


= Status | Oracie | Tables | Advanced | 
© © oradecocservice 1 


S° HRinstance : 2/17/2012 4:32.41 PM 


UNEXPECTED Collect Diaanostics 
hairdos wags spew lene replace nec paren ed ec) - 


ORA-00942. table or view does not exist. 














"ERROR", "computername", "ERROR", "UNEXPECTED", 
"ORACDC5@8E:Oracle method OCIStmtExecute failed with error: ORA-@@942: table or view does not exist 


7 SOURCE jcou 


"ERROR", "“computername", "RUNNING", "IDLE", 
"ORACDC518E:Failed to verify archive log mode.","source","","" 


"ERROR", "“computername", "ERROR", "UNEXPECTED", 
"ORACDC517E:Oracle Call Interface (OCI) method failed: ORA-@0942: table or view does not exist 
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"ERROR", "“computername", "ERROR", "UNEXPECTED", 
"ORACDC414E:The Engine component failed with return code 1.","engine","","" 


This happens when the Oracle account connecting from the CDC instance to the Oracle server does not have 


permission to see system log views. 


Resolution 


To resolve this error, either grant the currently configured user appropriate permissions within the Oracle 
database system, or change which account is being used to connect to the Oracle server from the CDC instance. 


The list of all the necessarily permissions is detailed in the help file included in the installation program files 
folder C:\Program Files\Change Data Capture for Oracle by Attunity\Attunity.SqlServer.XdbCdcDesigner.chm . See 


the page titled "Connect to an Oracle Source Database" within the .chm file for the complete list. 


You can set the user account by selecting the CDCInstance from the left pane and selecting the Properties button 
in the Actions right-most pane within the CDC Designer window. You can change the Oracle log mining 
authentication account from the properties dialogue page. 




















Oracle connection string (Such as: host[:port][/service name]): 


Oracle log mining authentication 

— = 

— ed 
[ est Cameco | 


Test Connection 
[ox] 





See also 


Track Data Changes (SQL Server) 

About Change Data Capture (SQL Server) 

Work with Change Data (SQL Server) 

Administer and Monitor Change Data Capture (SQL Server) 


Change Data Capture Designer for Oracle by 


Attunity F1 Help Reference 


11/23/2021 + 2 minutes to read * Edit Online 





Applies to: @sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


The Change Data Capture Designer for Oracle by Attunity is used to create and manage Oracle CDC Instance. 
The topics in this section explain how to carry out the available tasks in the CDC Designer Console. 


What do you want to do? 
e Access the CDC Designer Console 
e Manage a CDC Service 
@ Manage a CDC Instance 
e Use the New Instance Wizard (Or go directly to one of the following tasks) 
© Create the SQL Server Change Database 
© Connect to an Oracle Source Database 
© Connect to Oracle 
o Select Oracle Tables and Columns 
o Select Oracle Tables for Capturing Changes 
o Make Changes to the Tables Selected for Capturing Changes 
© Generate and Run the Supplemental Logging Script 
o Generate Mirror Tables and CDC Capture Instances 
o Finish 
e Edit Instance Properties(Or go directly to one of the following tasks) 
o Edit the Oracle Database Properties 
o Edit Tables 
o Add Tables to a CDC Instance 
o Edit the Table Properties 
o Review and Generate Supplemental Logging Scripts 


© Edit the Advanced Properties 


Access the CDC Designer Console 


11/23/2021 * 2 minutes to read « Edit Online 





Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


You can access the CDC Designer Console from the computer where you installed the console. For more 
information about installation, see Installation. 


When you open the CDC Designer Console, the Connect to SQL Server dialog box opens. 


The SQL Server login that accesses the CDC Designer must have UPDATE permissions on the MSXDBCDC 
database. In addition, the login must also have the dbcreator fixed-server role to create new Oracle CDC 
Instances. It is recommended that the login also have SELECT access to the CDC databases being used or the 
user will not be able to view the state of those databases. 


Enter the following information in the Connect to SQL Server dialog box. 


Server Name 


Type the name of the server where the SQL Server is located. 


Authentication 


Select one of the following: 
e Windows Authentication 


e SQL Server Authentication: If you select this option, you must type the Login and Password for the 
user in the SQL Server you are connecting to. 


The login must have a database role that allows access to the MSXCDCDB database. It is recommended that the 
login also have access to any additional databases being used or the user will not be able to view the data in 
those databases. 


Options 


Click the arrow to view available options to be configured. You can choose to leave these options with their 
default value. The available options are: 


Connection Timeout 
Type the time (in seconds) that the CDC Service for Oracle waits for a connection to the SQL Server before 
timing out. The default value is 15. 


Execution Timeout 
Type the time (in seconds) that the Oracle CDC Windows Service waits for a command to execute before timing 
out. The default value is 30. 


Encrypt Connection 

Select Encrypt Connection for communication between the Oracle CDC Service and the target SQL Server 
instance using an encrypted connection Advanced: Click Advanced and type any additional connection 
properties into the Advanced Connection Properties dialog box, if necessary. 


Advanced 
Click Advanced and type any additional connection properties into the Advanced Connection Properties dialog 
box, if necessary. 


For information about the Advanced Connection Properties dialog box, see Advanced Connection Properties. 


See Also 


SQL Server Connection Required Permissions for the CDC Designer 


Manage a CDC Service 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


You can use the CDC Designer Console to view the services you created with the CDC Service Configuration 
Console and manage all of the instances in the Oracle CDC Service. 


Click the name of the service in the left pane to display information about the service and to manage it. 


NOTE 


You must first create a service using the CDC Service Configuration Console to add services to this list. For information on 
how to create a service, see the online help provided with the CDC Service Configuration Console. 











What you can do when you display the CDC service information 


You can do the following when you display information about a service: 
Create a new CDC instance for the selected service 


Click New Oracle CDC Instance in the right pane to create a new instance for that service. The New Instance 
wizard opens to create the instance. For more information about the New Instance wizard, see Use the New 
Instance Wizard. 


Start all CDC instances in the service 
Click Start All Instances in the right pane to begin capturing data from all the defined instances in the service. 
Stop all CDC instances in the service 


Click Stop All Instances to stop the change data capture for all instances in the service. 


See Also 


How to Create the SQL Server Change Database Instance 
How to Manage a CDC Service from the CDC Designer Console 
Use the New Instance Wizard 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


You can use the CDC Designer Console to view information about the instances that you create and to manage 
the operation of the instances. 


Click on the name of an instance in the left pane to view the information about the instance. 


NOTE 

If you select a service in the left pane, the list of available instances is also displayed in the center of the CDC Designer 
Console. If you select one of the instances in this section, you can carry out the tasks in the right pane; however, you will 
not be able to view the information in the property tabs. 








What you can do when you display the CDC Instance information 
The following actions are carried out from the right pane: 


Start 
Click Start to start the capturing changes for the selected CDC instance. 


Stop 
Click Stop to stop capturing changes for the selected CDC instance. When you stop the CDC instance, the 
changes that were captured to that point are not lost and are delivered when the CDC instance is resumed. 


Reset 

Click Reset to reset the CDC instance to its initial (empty) state. This option is available when the CDC instance is 
stopped. All changes in the change tables and the CDC instance internal state are deleted. When the CDC 
instance is started later, the change capture starts from that point in time and only includes transactions that 
started after the CDC instance started. 


Click OK in the confirmation dialog box to confirm that you want to reset the CDC instance and delete the 
changes written to the change tables. 


Delete 
Click Delete to delete the CDC instance permanently. This option is available only when the CDC instance is 
stopped. 


Click OK in the confirmation dialog box to confirm that you want to delete the CDC instance. 


Oracle Logging Script 
Click this link to display the Oracle Logging script dialog box with the Oracle supplemental-logging script. For 
information on what you can do in this dialog box, see Oracle Supplemental Logging Script. 


NOTE 


When you run the supplemental logging scripts, the Oracle Credentials for Running Script dialog box opens where you 
provide a valid Oracle user name and password. For information on how to provide the proper Oracle credentials, see 
Oracle Credentials for Running Script. 











CDC Instance Deployment Script 
Click this link to display the CDC Instance Deployment Script dialog box that displays the CDC instance 
deployment script. For information about this dialog box, see CDC Instance Deployment Script. 


Properties 
Click this link to open the property editor. You edit the CDC instance configuration using the property editor. For 
more information about editing the properties for a CDC instance, see Edit Instance Properties. 


Viewer Tabs 


The following Viewer tabs are available when you view information for the CDC instance. The information in 
these tabs is read only. 


Status 
This tab provides information and statistics about the CDC instance current status. It contains the following 
information. 


e Status: An icon that indicates the current status for the CDC instance. The following describes the 
statuses. 


ICON STATUSES AND DESCRIPTIONS 


Pt) Error. The Oracle CDC Instance is not running because a 
non-retryable error occurred. The following sub-statuses 
are available: 


Misconfigured: A configuration error occurred that 
requires manual intervention. 


Password Required: No password was set for the 
Oracle CDC Instance or the password is not valid. 


Unexpected. All other non-recoverable errors. 


@ Running: The CDC Instance is running and is processing 
change records. The following sub-statuses are available: 


Idle: All change records have been processed and stored 
in the target change tables. There are no more active 
transactions. 


Processing: There are change records being process 
that are not yet written to the change tables. 


a Stopped: The CDC instance is not running. The stopped 
status indicates that the CDC instance was stopped in a 
normal manner. 


ICON STATUSES AND DESCRIPTIONS 


@ Paused: The CDC instance is running but processing is 
suspended because of a retryable error. The following 
sub-statuses are available: 


Disconnected: The connection to the source Oracle 
database cannot be established. Processing resumes 


when the connection is restored. 


Storage: The storage is full. Processing resumes when 
additional storage becomes available. 


Logger: The logger is connected to Oracle but cannot 
read the Oracle transaction logs due to a temporary 


problem, for example, a required transaction log is not 
available. 


e Detailed Status: The current substatus. 
e Status Message: More information about the current status. 
e Timestamp: The UTC time for when the CDC state was last read from the state table. 
e Currently Processing: You monitor the following information in this section. 
o Last transaction timestamp: The local time of the last transaction written to the change tables. 


o Last change timestamp: The local time of the most recent change seen by the Oracle CDC 
Instance in the source Oracle database transaction logs. This provides information about the 
current latency of the CDC instance in reading the Oracle transaction log. 


© Transaction log head CN: The most recent change number (CN) that was read from the Oracle 
transaction log. 


o Transaction log tail CN: The change number for recovery or restarting the CDC instance. The 
Oracle CDC instance will reposition to this location in the event of a re-start or any other type of 


failure (including cluster failover). 


o Current CN: The last change number (SCN) seen in the source Oracle database (not the 
transaction log). 


o Active transactions: The current number of source Oracle transactions that are being processed 
by the Oracle CDC Instance and are not yet decided (commit/rollback). 


o Staged transactions: The current number source Oracle transactions that are staged to the 
cdc.xdbcdc_staged_transactions table. 


e Counters: You monitor the following information in this section. 


o Completed transactions: The number of transactions completed since the CDC instance was last 
reset. This does not include transactions that do not contain tables of interest. 


o Written changes: The number of changes written to the SQL Server change tables. 


Oracle 

Displays information about the CDC instance and its connection to the Oracle database. This tab is read only. To 
edit these properties, right-click the instance in the left pane and select Properties or click Properties in the 
right pane to open the <instance> Properties dialog box. 


For information about these properties and how to edit them, see Edit the Oracle Database Properties. 


Tables 

Displays information about the tables included in the CDC instance. Column information is also available here. 
This tab is read only. To edit these properties, right-click the instance in the left pane and select Properties or 
click Properties in the right pane to open the <instance> Properties dialog box. 


For information about these properties and how to edit them, see Edit Tables. 


Advanced 

Displays the advanced properties for the CDC instance and the property values. This tab is read only. To edit 
these properties, right-click the instance in the left pane and select Properties or click Properties in the right 
pane to open the <instance> Properties dialog box. 


For information about these properties and how to edit them, see Edit the Advanced Properties. 
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The New Instance wizard is used to create a new instance for a CDC service. You open the Create an Oracle CDC 
Instance wizard from the CDC Designer Console. You can do the following in the New Instance wizard. 


® Create the SQL Server Change Database 

e® Connect to an Oracle Source Database 

e@ Connect to Oracle 

e Select Oracle Tables and Columns 

e Select Oracle Tables for Capturing Changes 

e@ Make Changes to the Tables Selected for Capturing Changes 
e@ Generate and Run the Supplemental Logging Script 

e@ Generate Mirror Tables and CDC Capture Instances 


e Finish 


See Also 


How to Create the SQL Server Change Database Instance 
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When you start the New Instance wizard, the Create CDC Database page opens. Use the Create CDC Database 
page to provide information about the new CDC instance and create a new Change database. 


When you create a new CDC database it is enabled for SQL Server CDC and this enablement requires a login 
that is a member of the sysadmin fixed-server role. 


When a user that starts the Create an Oracle CDC Instance wizard is not a member of the sysadmin fixed-server 
role, the Connect to SQL Server dialog box opens and requests the credentials for a member of the sysadmin 
role to carry out the Enable the database for SQL Server CDC task. When the CDC database is created, the 

sysadmin login is discarded and work resumes with the original SQL Server login used when the Oracle 
Designer Console was entered. 


IMPORTANT 


For tasks other than Enable the database for SQL Server CDC of the SQL Server login used for running the New Instance 
Wizard must have the dbcreator fixed-server role and UPDATE permissions on the MSXDBCDC database. 











For information on entering the data in the Connect to SQL Server dialog box, see SQL Server Connection for 
Instance Creation. 


Options 


Oracle CDC Instance 
Type the following information about the CDC instance you are creating. 


e Name: Type a name for the new service. This will also be the name of the new Change database. 
e Description: Type a description for the new instance to help you identify it. This is optional. 


SQL Server Change Database 
This section is used to create the database. 


1. Change Database: The name of the new Change database. The name of the database is the same as the 
name that you gave to the instance. This read-only field displays the full path to the database. 


2. Create Database: Click Create Database to create the database. 


To create the database, the login must have the sysasmin server role. See the security note above for 


more information. 


After you create the database, you can click Next to Connect to an Oracle Source Database. 
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Applies to: Q sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Use the Oracle Source page to provide the information necessary to connect to the Oracle source database. The 
CDC instance will read the redo logs of the Oracle database you are connected to. 


Oracle Connect String 
Enter the Oracle connect string to the computer with the Oracle database you are using. The connect string is 
written in one of the following ways: 


host[:port][/service name] 


The connection string can also specify an Oracle Net connect descriptor, for example, 
(DESCRIPTION=(ADDRESS=(PROTOCOL=tcp) (HOST=erp.contoso.com) (PORT=1521)) (CONNECT_DATA=(SERVICE_NAME=orcl))) 


If using a directory server or tnsnames, the connect string can be the name of the connection. 


Oracle Log Mining Authentication 
To enter the credentials for the Oracle database user that is authorized for log mining, select one of the 
following: 


e Windows Authentication: Select this to use the current Windows domain credentials. You can use this 
option only if the Oracle database is configured to work with Windows authentication. 


e Oracle Authentication: If you select this option, you must type the User Name and Password for the 
user in the Oracle database you are connecting to. 


NOTE 


A user must have the following privileges granted in the Oracle database to be a log-mining user. 


e@ SELECT on <any-captured-table> 
e SELECT ANY TRANSACTION 

e@ EXECUTE on DBMS LOGMNR 

e@ SELECT on V$LOGMNR CONTENTS 
e@ SELECT on V$ARCHIVED LOG 

e SELECT on V$LOG 

e@ SELECT on V$LOGFILE 

e@ SELECT on V$DATABASE 

e@ SELECT on V$THREAD 

e@ SELECT on ALL INDEXES 

@ SELECT on ALL OBJECTS 

e@ SELECT on DBA OBJECTS 

e@ SELECT on ALL TABLES 


If any of these privileges cannot be granted to a V$xxx, then grant them to the V_S$xx. 





Test Connection 
Click Test Connection to determine whether you established a connection with the remote computer that has 
the Oracle database. A dialog box opens to inform you whether the connection was successful. 








IMPORTANT 


Due to a known issue connection to the Oracle source database may fail if the CDC Designer is not run as an 
administrator. If connection fails, close and restart the CDC Designer using the Run as administrator option. 








After you finish entering information on this page, click Next to Select Oracle Tables and Columns. 


See Also 


How to Create the SQL Server Change Database Instance 
Edit Instance Properties 


(Co)alaemcen@)e-\a>) 


11/23/2021 * 2 minutes to read « Edit Online 
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When you add or edit the tables used in the CDC instance for the first time, you may be asked to connect to the 
Oracle database. You should enter the credentials of an Oracle user who can access the schema of the tables to 
be captured. Enter the following in this dialog box: 


Authentication 
Select one of the following: 


e Windows Authentication: Select this to use the current Windows domain credentials. You can use this 
option only if the Oracle database is configured to work with Windows authentication. 


e Oracle Authentication: If you select this option, you must type the User Name and Password for the 


user in the Oracle database you are connecting to. 


See Also 


Add Tables to a CDC Instance 
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Use the Select Oracle Tables and Columns page to select the tables from the Oracle source database where 
changes are captured. This page has the following elements: 


Options 
Table list 
The table list has three columns: 


e Oracle Table Name: The name of the table, including the table schema. 


e Capture Instance: The name of the capture instance used to name instance-specific change data capture 
objects. The capture instance cannot be NULL. 


If not specified, the name is derived from the source schema name plus the source table name in the 
format <schema-name>_<table-name> . The capture instance name cannot exceed 100 characters and must 
be unique within the database. 


You can click in any cell in this column to manually edit the capture_instance. 
e Security Role: The name of the database gating role used to control access to change data. 
You can click in any cell in this column to manually edit the security_role. 


Add Tables 
Click Add Tables to open the Table Selection dialog box where you can Select Oracle Tables for Capturing 
Changes. 


Edit 
Select a table from the list and select Edit to open the Properties dialog box for that table where you can Make 
Changes to the Tables Selected for Capturing Changes. 


Remove 


Select a table from the list and click Remove to remove the table from the CDC instance. 


After you Select Oracle Tables for Capturing Changes and/or Make Changes to the Tables Selected for Capturing 
Changes using the correct dialog boxes, click Next to Generate and Run the Supplemental Logging Script. 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Use this dialog box to select the tables that are included in the CDC instance. The tables selected are added to 
the list in the Select Tables and Columns page of the New Instance wizard. You can do the following in this 
dialog box. 


By default, no tables are included in the list of tables in this dialog box. You can select the check box at the top of 
the check box column to select all of the tables or search for specific tables. 


To search for specific tables 
Enter search criteria as follows, and then click Search: 


e Schema: Select a database schema from the list. Only tables that have that schema will be included in the 
list. 


e Table Name Pattern: Enter any string of characters. Only tables that include the character string entered 
are displayed. 





NOTE 


You can enter criteria in one or both of these fields. 





e Display first 1000 matching tables: By default this check box is selected. It limits the display to the first 
1000 matching tables. If you clear the check box, all tables that match the criteria are displayed. If there are a 
large number of tables, it may take a long time to display the list. 


To select tables to include in the CDC instance 


Click the check box next to any of the tables you want to include, and then click Add. The tables are added to the 
list in the New Instance Wizard Select Tables and Columns page. 


Click Close to close the dialog box without adding any additional tables. 





NOTE 


If you select a table that includes a non-supported data type, you will see an error message and the table will not be 
included. 
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In this dialog box, you can select specific columns from the selected table to capture changes from. You can also 
edit the Security Role and Capture Instance information. 


You can make the following changes to the tables you selected for capturing changes in this dialog box. 
Make changes to which columns are included in the CDC instance: 

Do one or both of the following: 

e Select the check box next to any additional column you want to include. 

e Clear the check box next to any column that you no longer want to include. 

Change the data type for a specific column: 


You can select a different data type for a specific column. You can only change the data type to a data type that is 
compatible with the original data type. 


To change the data type, click in the Data Type column and select a different data type. Only data types that are 
compatible with the original data type are available. 





NOTE 


If no additional data types can be selected, the drop-down list is not available. 





Change the Security Role 


Type a new name or edit the name of the security gating role in the Security Role field. 
Change or add a capture instance 


In the Capture Instance field enter a name for the capture instance. 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Use the Set up Tables for Capturing Changes page to run a script on the Oracle source database that will set up 
supplemental logging. 


To run the supplemental logging scripts 


Click Run Script to run the supplemental logging script on the tables defined for the CDC instance. This script 
instructs the Oracle database to write all columns of interest to its transaction logs when logging UPDATE 
operations to captured tables. This script is normally examined and executed by an Oracle system administrator. 


You can also run the scripts manually using SQL * Plus. 
To run the scripts manually 


Click Copy to paste the script to the clipboard. Open SQL* Plus and go to the directory with your Oracle source 
database. Paste the script into SQL*Plus to run it. 


To save the supplemental logging script in a text file, click Save as and browse to the location where you want 
to save the file. Give the file a name and click Save to save the file. 


Click Next to Generate Mirror Tables and CDC Capture Instances. 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Use the Generate Mirror Tables page to generate the mirror tables for the tables you included in the CDC 
instance 


Click Run to create the mirror tables. The progress for the creation of each table is displayed and a message is 
displayed to let you know whether each mirror table is completed successfully or with errors. If any errors occur, 
click Details to see a dialog box with an explanation of the error. 


If any of the tables fail to be created, you can choose to continue or delete any tables that failed before 
continuing. After you finish running the wizard, you can decide whether to fix the table in the Oracle source 
database or not use it in the CDC instance. If you fix the table, you can add it when you Edit Tables. 


Click Next to open the Finish page. 
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The Finish page summarizes the wizard process. Click Finish to close the wizard and generate all of the tables 
you defined in the Create CDC Instance wizard. 
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Use the Properties editor to make changes to the CDC instance after you create the initial configurations. You 
can do the following in the Properties editor. 


e Edit the Oracle Database Properties 

e Edit Tables 

e Add Tables to a CDC Instance 

e Edit the Table Properties 

e Review and Generate Supplemental Logging Scripts 
e Edit the Advanced Properties 


To open the Properties editor 


1. From the left pane in the CDC Designer Console, expand the service you are working with. 
2. Select the CDC instance where you want to edit the properties. 
3. From the Actions pane on the right of the CDC Designer Console, click Properties. 

You can also right-click the service in the left pane and select Properties. 


OR 


1. From the left pane in the CDC Designer Console, select the Service you are working with. 


2. From the list in the center of the CDC Designer Console, select the CDC instance where you want to edit 
the properties. 


3. From the Actions pane on the right of the CDC Designer Console, click Properties. 


You can also right-click the service from the list in the center of the CDC Designer Console and select 
Properties. 


Edit the Oracle Database Properties 
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Use the Oracle tab in the Properties editor to make changes to the description you provided in the Create CDC 
database page in the New Instance wizard and to make changes to the Oracle Log Mining database connection 
information. 


The following describes the information in the Oracle tab. 


Name 
The name of the CDC Instance that you entered in the Create CDC Database page in the New Instance wizard. 
This field is read only and you cannot edit this information. 


Description 
You can edit the description of the new instance or add one if you did not do so when creating the CDC Instance. 


Oracle Connect String 

The Oracle connect string to the computer with the Oracle database you are using. This field is read only and 
you cannot edit this information. This is because some changes to the connect string may point the Oracle CDC 
Instance to another Oracle database entirely, corrupting the CDC Instance state as stored in the 
cdc.xdbcdc_config table. If minor changes are needed, you can change the connect string directly in the 
configuration table using SQL Server Management Studio. 


Oracle Log Mining Authentication 
To enter the authentication credentials for the Oracle database that contains the log miner, select one of the 
following under Authentication: 


e Windows Authentication: Select this to use the current Windows domain credentials. You can use this 
option only if the Oracle database is configured to work with Windows authentication. 


e Oracle Authentication: If you select this option, you must type the User Name and Password for the 
user in the Oracle database you are connecting to. 


You can view the Oracle database properties in the viewer. When using the viewer the information is read only. 
The viewer also includes a list of the captured columns in the table. For information on how to access the viewer, 
see How to Manage a CDC Instance. 
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Use the Tables tab to make changes to the tables and columns that you selected from the Oracle source 
database. This tab has the following elements: 


Table list 
The table list has three columns: 


e Oracle Table Name: The name of the table, including the table schema. 


e Capture Instance: The name of the capture instance used to name instance-specific change data capture 
objects. The capture instance cannot be NULL. If not specified, the name is derived from the source 
schema name plus the source table name in the format <schema-name>_<table-name>. The capture 
instance name cannot exceed 100 characters and must be unique within the database. You can click in 
any cell in this column to manually edit the capture_instance. 


e Security Role: The name of the database role used to gain access to change data. You can click in any 
cell in this column to manually edit the security_role. 


Add Tables 
Click Add Tables to open the Table Selection dialog box where you can Add Tables to a CDC Instance. The first 
time this session that you access the Oracle database, you must Connect to Oracle. 


Edit 


Select a table from the list and select Edit to open the Properties dialog box for that table where you can Edit 
the Table Properties. 





NOTE 


You cannot edit type mapping for tables that already have mirror tables. You can do this for new tables only. 





Remove 


Select a table from the list and click Remove to remove the table from the CDC instance. 
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Use the Table Selection dialog box to add additional tables from the Oracle source to the CDC instance. The 
tables selected are added to the list in the Tables tab of the Properties editor. 


By default, no tables are included in the list of tables in this dialog box. You can select the (Select All) check box 
or search for specific tables. 


To search for specific tables 
Enter search criteria as follows, and then click Search: 


e Schema: Select a database schema from the list. Only tables that have that schema will be included in the 
list. 


e Table Name Pattern: Enter any string of characters. Only tables that include the character string entered 
are displayed. 





NOTE 


You can enter criteria in one or both of these fields. 





e Display first 1000 matching tables: By default this check box is selected. It limits the display to the first 
1000 matching tables. If you clear the check box, all tables that match the criteria are displayed. If there are a 
large number of tables, it may take a long time to display the list. 


To select tables to include in the CDC instance 


Click the check box next to any of the tables you want to include, and then click Add. The tables are added to the 
list in the New Instance Wizard Select Tables and Columns page. 


Click Close to close the dialog box without adding any tables. 


NOTE 


If you select a table that includes a non-supported data type, you will see an error message and the table will not be 
included. 


NOTE 


You can view the list of tables in the viewer. When using the viewer the information is read only. The viewer also includes a 


list of the captured columns in the table. For information on how to access the viewer, see How to Manage a CDC 
Instance. 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Use this dialog box to edit the specific columns from the selected table where changes are being captured. You 
can also edit the Security Role and Capture Instance information. 


To edit the columns to include in the CDC instance 


1. Do one or both of the following: 
e Select the check box next to any additional column you want to include. 
e Clear the check box next to any column that you no longer want to include. 


To edit the Security Role 


1. Type a new name or edit the name of the security role in the Security Role field. 


To create a new capture instance 


1. In the Security Role section, Name field enter a name for the capture instance. By default, the name 
entered in the field is the name of the current capture instance with NEW added to the end of the name 
(for example, old_instance_NEW). 


2. Save the capture instance as one of the following: 


e New Capture Instance: In this case a new capture instance is saved and the old capture instance 
is not deleted. 


Note: You can have no more than two capture instances per table. If there are already two capture 
instances, this option is not available. 


e Replace Existing: In this case the current capture instance is deleted and replaced by the capture 
instance you created. If there are two capture instances defined for this table, you must select one 
to replace. 


Note: You can remove a capture instance from the list of tables in the Table tab. 


After you finish entering the information in this dialog box, click OK to accept the changes. 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 
Use the Scripts tab to run or re-run a script on the Oracle source database that sets up supplemental logging. 
Before you run the scripts select one of the following: 


Include changes in this session 
Select this to run the script on any new table that was added to the CDC instance or on tables that were changed 
in any way using the Properties editor. 





NOTE 


If no changes were made to the tables in the CDC instance, the Oracle supplemental logging script area will be empty. 





Include all tables/capture instances 


Select this to run the script on all of the tables and capture instances in the CDC instance. 
After you select one of these options, run the supplemental logging script. 


To run the supplemental logging scripts 


1. Click Run Script to run the supplemental logging script on the tables defined for the CDC instance. This 
script instructs the Oracle database to write all columns of interest to its transaction logs when logging 
UPDATE operations to captured tables. This script is normally examined and executed by an Oracle 
system administrator. 


2. When you run the supplemental logging scripts, the Oracle Credentials for Running Script dialog box 
opens where you provide a valid Oracle user name and password. For information on how to provide the 
proper Oracle credentials, see Oracle Credentials for Running Script. 


You can also run the scripts manually using SQL*Plus, if necessary. 


To run the scripts manually 


1. Click Copy to paste the script to the clipboard. Open SQL* Plus and go to the directory with your Oracle 
source database. Paste the script into SQL*Plus to run it. 


To save the supplemental logging script in a text file 


1. Click Save as and browse to the location where you want to save the file. 


2. Give the file a name and click Save to save the file. 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Use the Advanced tab to add special properties to the CDC instance. 


To add advanced properties to the CDC instance 


1. Type the name of the property in the Name column. 


2. Type a valid value for the property in the Value column. 





NOTE 


You can view the Advanced Properties in the viewer. When using the viewer the information is read only. The 
viewer also includes a list of the captured columns in the table. 








For a description of the properties you can enter, see the available options table in cdc.xdbcdc_config. 
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Applies to: Q@sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


This section describes how to carry out tasks in the Change Data Capture Designer for Oracle by Attunity. 


Learn how to use the Oracle CDC Designer Console 


e@ How to Manage a CDC Service from the CDC Designer Console 
e How to Create the SQL Server Change Database Instance 

e How to Manage a CDC Instance 

e@ How to Edit the CDC Instance Properties 


© How to View the CDC Instance Properties 


How to Manage a CDC Service from the CDC 
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Applies to: Q sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 
This procedure describes how to use the CDC Designer Console to manage a CDC service. 


To manage a CDC service from the CDC Designer Console 


1. From the Start menu, select the CDC Designer Console. 
2. In the left pane, expand Change Data Capture. 
3. Select the service you want to manage. 


Note: If there are no services listed in the CDC Designer Console, you must create new instances using 
the CDC Service Configuration Console. For information about creating a new service, see the online help 
included with the service configuration console. 


4. You can carry out the following tasks for a CDC service: 
e Create aNew CDC Instance 
e Start All Instances (that are included in the selected CDC service) 
e Stop All Instances (that are included in the selected CDC service) 
For information about these tasks, see Manage a CDC Service. 


Other CDC service tasks are carried out using the CDC Service Configuration Console. For information about 
the tasks you can carry out in the service configuration console, see the online help included with the service 
configuration console. 


How to Create the SQL Server Change Database 
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Applies to: Q sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


This procedure describes how to use the CDC Designer Console to create CDC instances. 


To create CDC instances 


1. 


2. 


From the Start menu, select the CDC Designer Console. 


In the left pane, expand Change Data Capture. 


. Select the service where you want to create the new CDC instance. 


. From the Actions pane on the right side of the CDC Designer Console, select New Oracle CDC 


Instance. 


You can also right-click the service where you want to create the new CDC instance and select New 
Oracle CDC Instance. 


. Enter the required information in the New Instance wizard to create the new instance. For information 


about the information required for this wizard, see Use the New Instance Wizard. 


How to Manage a CDC Instance 
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This procedure describes how to use the CDC Designer Console to manage CDC instance operations at runtime. 


To manage CDC instance operations 


1. From the Start menu, select the CDC Designer Console. 


2. In the left pane, expand Change Data Capture then expand the service that contains the instance you 
want to view. 


3. Select the name of an instance you want to work with. 


4. From the Actions pane on the right side of the CDC Designer Console, click on the operation you want to 
carry out. 


You can also right-click the name of the instance in the left pane and select the operation you want to 
carry out. 


You can carry out the following tasks: 
e Start: To start capturing changes. 
e Stop: To stop capturing changes 


e Reset: Click Reset to reset the CDC instance to its initial (empty) state. This option is available 
when the CDC instance is stopped. All changes in the change tables and the CDC instance internal 
state are deleted. When the CDC instance is started later on, change capture will start from that 
point in time and only includes transactions that started after the CDC instance started. 


e Delete: To delete the CDC instance. 


e Oracle Logging Script: Click Oracle Logging Script to display the Oracle Logging script 
dialog box with the Oracle supplemental-logging script. For information on what you can do in 
this dialog box, see Oracle Supplemental Logging Script. 


Note: When you run the supplemental logging scripts, the Oracle Credentials for Running Script 
dialog box opens where you provide a valid Oracle user name and password. For information on 
how to provide the proper Oracle credentials, see Oracle Credentials for Running Script. 


e CDC Instance Deployment: To generate a deployment script for the CDC Instance. For 
information about this dialog box, see CDC Instance Deployment Script. 


For more information about these tasks, see Manage a CDC Instance. 


You can also select Properties to edit the CDC instance configuration properties. For more information about 
editing the CDC instance properties, see Edit Instance Properties. 


How to Edit the CDC Instance Properties 
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This procedure describes how to use the CDC Designer Console to edit the configuration properties for a CDC 
instance. 


To edit the CDC instance configuration properties 


1. From the Start menu, select the CDC Designer Console. 


2. In the left pane, expand Change Data Capture then expand the service that contains the instance with 
the properties that you want to edit. 


3. Select the name of the instance where you want to edit the properties. 
4. From the Actions pane on the right side of the CDC Designer Console, click Properties. 

You can also right-click the instance where you want to edit the properties and click Properties. 
5. In the Properties editor, edit the properties in the following tabs: 


e Oracle: Use the Oracle tab in the Properties editor to make changes to the description you 
provided in the Create CDC database page in the New Instance wizard and to make changes to the 
Oracle Log Mining database connection information. 


For information about what you can edit in this tab, see Edit the Oracle Database Properties. 


e Tables: Use the Tables tab to make changes to the tables and columns that you selected from the 
Oracle source database. 


For information about what you can edit in this tab, see Edit Edit Tables 


e Scripts: Use the Scripts tab to run or re-run a script on the Oracle source database that will set 
up supplemental logging. 


For information about what you can do in this tab, see Review and Generate Supplemental 
Logging Scripts. 


e Advanced: Use the Advanced tab to add special properties to the CDC instance. 


For information about what you can do in this tab, see Edit the Advanced Properties. 


How to View the CDC Instance Properties 


11/23/2021 * 2 minutes to read « Edit Online 





Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


This procedure describes how to use the CDC Designer Console to view information about the instances that 
you create to help manage the operation of the instances. 


To view information about a specific instance 


1. From the Start menu, select the CDC Designer Console. 


2. In the left pane, expand Change Data Capture then expand the service that contains the instance you 


want to view. 
3. Select the name of an instance you want to work with. 


The information about the instance is displayed in the center part of the CDC Designer Console. It is 
divided into four tabs. All of the tabs are read only. 


Status 
This tab displays the information about the current status of the change data capture for the instance. For 
information about what is displayed in this tab, see the Viewer Tabs section in Manage a CDC Instance. 


Oracle 
This tab displays general information about the CDC instance and the Oracle source database. For 
information about what is displayed in this tab, see Edit the Oracle Database Properties. 


Tables 
This tab displays information about the tables included in the change data capture. It also lists the 
columns that are captured. For information about what is displayed in this tab, see Edit Tables. 


Advanced 
This tab displays a list of advanced properties that you define in the properties editor. For information 
about what is displayed in this tab, see Edit the Advanced Properties. 
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One of the first steps when creating an Oracle CDC Instance is the creation of a CDC database on the target SQL 
Server instance. This CDC database is enabled for SQL Server CDC and this enablement requires a login that is a 
member of the sysadmin fixed-server role. 


When a user that starts the Create an Oracle CDC Instance wizard is not a member of the sysadmin fixed- 
server role, the Connect to SQL Server dialog box opens and requests the credentials for a member of the 

sysadmin role to carry out the Enable the database for SQL Server CDC task. When the CDC database is created, 
the sysadmin login is discarded and work resumes with the original SQL Server login used when the Oracle 
Designer Console was entered. 


Task List 


Enter the following information in the Connect to SQL Server dialog box. 


Server Name 
Type the name of the server where the SQL Server is located. 


Authentication 
Select one of the following: 


e Windows Authentication 


e SQL Server Authentication: If you select this option, you must type the Login and Password for the 
user in the SQL Server you are connecting to. 


The login must have a database role that allows access to the MSXCDCDB database. It is recommended that the 
login also have access to any additional databases being used or the user will not be able to view the data in 
those databases. 


Options 
Click the arrow to view available options to be configured. You can choose to leave these options with their 
default value. The available options are: 


e Connection Timeout: Type the time (in seconds) that the CDC Service for Oracle waits for a connection 
to the SQL Server before timing out. The default value is 15. 


e Execution Timeout: Type the time (in seconds) that the Oracle CDC Windows Service waits for a 
command to execute before timing out. The default value is 30. 


e Encrypt Connection: Select Encrypt Connection for communication between the Oracle CDC Service 
and the target SQL Server instance using an encrypted connection. 


e Advanced: Click Advanced and type any additional connection properties into the Advanced 
Connection Properties dialog box, if necessary. 


For information about the Advanced Connection Properties dialog box, see Advanced Connection 
Properties. 


See Also 


Create the SQL Server Change Database 
SQL Server Connection Required Permissions for the CDC Designer 


Advanced Connection Properties 


11/23/2021 * 2 minutes to read « Edit Online 





Applies to: Q@ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


Use the Advanced Connection Properties dialog box to add more connection parameters to the connection 
string. 


The additional connection parameters can be any ODBC connection parameter that is supported by the SQL 
Server database instance you are using. 


The parameters added using the Advanced Connection Properties dialog box are added to the parameters 
selected in the Connect to SQL Server dialog box. 


The last instance of each parameter provided overrides any previous instances of the parameter. Parameters 
added using the Advanced Connection Parameters dialog box follow and replace the parameters provided 
in the SQL Server Connection dialog box. For example, if the SQL Server Connection dialog box specifies 
SERVER1 as the Server name, and the Additional Connection Parameters page contains ;SERVER=SERVER2, 
the connection will be made to SERVER2. 


Parameters added using the Advanced Connection Properties dialog box are passed as plain text. 


IMPORTANT 


Do not include login credentials in the Advanced Connection Properties dialog box. They will not be encrypted when 


they are passed across the network. 





See Also 


Access the CDC Designer Console 
SQL Server Connection for Instance Creation 


Oracle Credentials for Running Script 
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To run the Oracle supplemental logging script from the Oracle CDC Designer console, the program prompts you 
for the credentials of the Oracle user who is running the script. To run this script, the Oracle user must have 


ALTER TABLE permission for all the tables to be captured and SELECT permission on the DBA_LOG_GROUPS 
view. 


Task List 

Enter the following in this dialog box: 
Authentication 

Select one of the following: 


e Windows Authentication: Select this to use the current Windows domain credentials. You can use this 
option only if the Oracle database is configured to work with Windows authentication. 


e Oracle Authentication: If you select this option, you must type the User Name and Password for the 


user in the Source Oracle database you are connecting to. 


See Also 


How to Manage a CDC Instance 
Review and Generate Supplemental Logging Scripts 


Oracle Supplemental Logging Script 
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This dialog box shows the script the Oracle supplemental logging script. 


When you prepare a CDC Instance for use, the CDC Designer creates an Oracle SQL script that sets up 
supplemental logging for the tables to be captured. The supplemental logging script tells Oracle that when a 
specific table is updated, the change records it writes to the transaction log should contain the data of all 
columns of interest, not just the columns that changed. 


Depending on the Oracle DBA policies in your organization, running the supplemental logging script may 
require a review and approval by an Oracle DBA. 


Options 
The following are the available options for how to execute the script. 


Run Script 

Runs the supplemental logging script on the tables defined for the CDC instance. To run this script, the Oracle 
user must have ALTER TABLE permission for all the tables to be captured and SELECT permission on the 
DBA_LOG_GROUPS view. In addition, the Oracle user must have the credentials for an Oracle database use with 
the required permissions. You can let the program prompt you for the Oracle credentials and then have it run 
the script. 


Save As 

Saves the script to a text file. This is used if an Oracle database administrator (DBA) needs to examine and 
execute the supplemental logging script, the program lets you save the script to a text file that you can later send 
to the Oracle DBA by email or by other means to be execute later (by using the SQL*Plus Oracle utility or other 
tool for running scripts on an Oracle database). 


Copy 
Copies the script to the clipboard. When ready you can paste the script in any location you need in case an 
Oracle database administrator (DBA) needs to examine and execute the supplemental logging script. 


See Also 


How to Manage a CDC Instance 
Manage a CDC Instance 


CDC Instance Deployment Script 


11/23/2021 * 2 minutes to read « Edit Online 





Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


The CDC Instance Deployment Script dialog box that displays the CDC instance deployment script. This script 
can be used to re-create the CDC database with all of its artifacts on a different SQL Server instance. 


At the completion of the deployment script, you should make sure of the following: 


e The deployment script assumes that the target SQL Server instance was prepared for Oracle CDC, by 
using the Oracle CDC Service Configuration Console or by using prepare script that program creates. 


e The part of the script that is used to enable the database for CDC needs to be run by a sysadmin . 


e The script does not preserve the Oracle log-mining password. This needs to be set manually after the 
script is run and the Oracle CDC Service is started. 


Select the following options in the CDC Instance Deployment Script dialog box. 


Save As 


Saves the script in a text file that you can save in any location you want. You can copy the file with the script to 
any other server to run it there. 


Copy 
Copies the script to the clipboard. You can then paste the script into the SQL Server Management Studio or any 
text editor to run the scripts later. 


See Also 


Prepare SQL Server for CDC 


SQL Server Connection Required Permissions for 


the CDC Designer 
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The CDC Designer Console requires connection information to SQL Server to perform its tasks. This topic 
describes the information that can be provided in the Connect to SQL Server dialog box for setting up the 
connection to SQL Server. 


The Connect to SQL Server dialog box opens when necessary, such as when the SQL Server connection 
information is not available or when the information exists but the connection does not have the required 
permissions. 


The following table describes the various tasks where a connection to SQL Server is required and the required 
permissions from the SQL Server login/user. 


TASK MINIMUM PERMISSIONS 


View the list of CDC Services and Instances using the db_datareader role on MSXDBCDC 
associated SQL Server instance. 


Start/Stop CDC Instance(s) db_datareader and db _datawriter roles on MSXDBCDC 
View the CDC Instance status. db_owner role on the CDC Instance database 

Create a new Oracle CDC Instance database. dbcreator fixed-server role 

Create a new Oracle CDC Instance. db_datareader role on MSXDBCDC 


db_owner role on the CDC database that was created. 


Get deployment scripts. db_datareader and db_datawriter roles on MSXDBCDC 


db_owner_ role on the relatedCDC database 


Change configuration and add/remove capture instances. db_datareader and db_datawriter roles on MSXDBCDC 


db_owner role on the related CDC database 


See Also 


Access the CDC Designer Console 
SQL Server Connection for Instance Creation 


Change Data Capture Service for Oracle by 


Attunity 
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The CDC Service for Oracle is a Windows service that scans Oracle transaction logs and captures changes to 
Oracle tables of interest into SQL Server change tables. The SQL change tables where the changes captured 
from Oracle are stored are the same type of change tables used in the native SQL Server Change Data Capture 
feature. This makes consuming these changes as easy as consuming changes made to SQL Server databases. 


Installation 


Download Microsoft Change Data Capture Designer and Service for Oracle by Attunity for corresponding SQL 
Server version from below links: 


Microsoft SQL Server 2012 Integration Services Attunity Oracle CDC Designer/Service Feature Pack 


Microsoft SQL Server 2016 Integration Services Attunity Oracle CDC Designer/Service Feature Pack 


Microsoft SQL Server 2017 Integration Services Attunity Oracle CDC Designer/Service Feature Pack 


Microsoft SQL Server 2019 Integration Services Feature Pack 


The CDC Service for Oracle can be installed on any supported Windows computer with access to the source 
Oracle database(s) being captured and the target SQL Server instance where the target CDC database resides. 
The CDC Service does not need a local installation of the Oracle database or the SQL Server database, only their 
supported clients. For information about where to install the required database components, see Database 
Prerequisites in this topic. 


The installation of the SQL Server CDC Service for Oracle places the service configuration UI and the service 
program in the selected location. The CDC Service for Oracle is configured separately using the Oracle CDC 
Service Configuration Console. For more information on configuring the Oracle CDC Service, see Change Data 
Capture Service for Oracle by Attunity F1 Help. 


The CDC Service for Oracle can be installed on any supported Windows computer where the SQL Server Native 
Client is installed; it does not need to be installed on the same computer where the target SQL Server is 
installed. 


Supported Windows Environments 
The Change Data Capture Service for Oracle by Attunity can run in the following Windows environments: 


e Windows 8 and 8.1 

e Windows 10 

e Windows Server 2012 and 2012 R2 
e Windows Server 2016 


Database Prerequisites 


To work with the CDC Service for Oracle you must install Oracle client that is compatible with Oracle database 
version. This is a prerequisite that should be obtained from Oracle and installed before installing the Oracle CDC 
Service. Additionally, you need to install the SQL Server ODBC Client using SQL Server Setup. 


The CDC Service for Oracle supports the following versions: 


Source Oracle Database 
e Oracle Database 10g Release 2 
e Oracle Database 11g Release 1 and Release 2 


e Oracle Database 12c in classic installation. (Multitenant installation is not supported.) 


Target SQL Server Database 


For a list of features that are supported by the editions of SQL Server, see Features Supported by the Editions of 
SQL Server. 


Running the Installation Program 


To install the CDC Service for Oracle, open the installation wizard for the Windows platform you are using 
(32/64-bit) and follow the directions on the screen. 


Uninstalling Change Data Capture Service for Oracle by Attunity 


You uninstall the CDC Service for Oracle using Control Panel, Programs and Features. 


Uninstalling the CDC Service does not delete the SQL Server databases created. For complete removal of the 
tool, you must remove the MSXDBCDC database and the specific CDC databases that were created in the target 
SQL Server instance you worked with. 


If you uninstall the CDC Service software from one machine and install it on another computer, you only need to 
provide the following definitions: 


e Service account 
e SQL Server connect string and credentials 
e The master password 


All the other definitions are stored in SQL Server and are available from the previous installation on another 
computer. 


In This Documentation 

e Change Data Capture Service for Oracle by Attunity System Architecture 
e The Oracle CDC Service 

e Change Data Capture Service for Oracle by Attunity F1 Help 


e Change Data Capture Service for Oracle by Attunity How to Guide 


See Also 


Working with the Oracle CDC Service 


Change Data Capture Service for Oracle by 


Attunity System Architecture 
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The CDC Service for Oracle captures changes made to selected tables in one or more source Oracle databases 
into SQL Server CDC databases located on a SQL Server instance. The following diagram shows the 
components that make up the CDC Service for Oracle. 
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This figure illustrates four platforms that are used. In many cases, these platforms can overlap, however this 
diagram represents a standard use case. For example, it makes sense that the Oracle and SQL Server databases 
each run on a separate computer and are not shared with the Oracle CDC Service platform or the platform from 
which the CDC Service is designed. The platforms illustrated in this figure are: 


e@ The Oracle CDC Service: This can be any supported Windows computer where the Oracle CDC Service is 
installed and run. This platform may also represent a cluster node in a Microsoft failover cluster (high 
availability configurations are discussed later in this document). 


@ The Oracle Database: This can be any computer where a supported version of the Oracle database runs. 
This includes any computer running Windows, Linux, or any other operating system supported by the 
version of the Oracle database installed. Note that the diagram shows this platform in plural because a 
single Oracle CDC Service can capture changes from multiple source Oracle databases. 


e The SQL Server: This can be any computer where the target SQL Server database (a supported SKU of 


SQL Server) runs. An Oracle CDC Service supports one SQL Server target where it stores change tables 


and service configuration. The SQL Server Platform may also represent a clustered instance of SQL 


Server or a mirrored instance of SQL Server using the Always On feature. 


e The Oracle CDC Designer: This can be any supported Windows computer that can access the source 


Oracle database and the target SQL Server database. 


The following table describes the components that run on the four platforms described above. 


COMPONENT/DESCRIPTION 


Oracle CDC Service: This is a Windows service where the 
change data capture activity takes place. 


Oracle CDC Service Configuration: This is a Microsoft 
Management Console snap-in that creates the Windows 
service and sets up its configuration. 


Oracle Database: A source Oracle database from which 
changes to select tables are captured. 


SQL Server Instance: A SQL Server instance where the CDC 
databases are hosted. This may be a clustered SQL Server 
Instance (failover cluster) or a mirrored database (Always 
On). 


COMPONENT CONSISTS OF: 


Oracle CDC Instance: A sub-process of the Oracle CDC 
Service that handles change data capture activity for a single 
source Oracle database (there is one Oracle CDC instance 
per source Oracle database). 


Oracle Log Reader: Reads Oracle transaction logs using the 
Oracle Client. 


Oracle Client: The Oracle Instant Client used for 
communication with Oracle. This is a prerequisite that should 
be obtained from Oracle and installed before installing the 
Oracle CDC Service. 


SQL Server Change Writer: This writes committed changes 
made to the captured Oracle table to SQL Serverchange 
tables. This component also maintains that capture state 
within the target SQL Server database. 


SQL ServerODBC Client: The Microsoft Native Client for SQL 
Server. This is a prerequisite component that should be 
obtained from Microsoft and installed before installing the 
Oracle CDC Service. 


SQL Server Client: The SQL ADO.NET client that ships with 
version 4 of the .NET framework. 


Log Miner: An Oracle component through which the Oracle 
transaction logs are read. 


Transaction Logs: The online and archived Oracle Redo Logs 
that are used by Oracle to ensure that the database can roll 
back transactions and recover from failures (in this case, the 
Oracle database must operate in archive-log mode). 


The MSXDBCDC Database: A database where information 
about the CDC Services working with this SQL Server 
Instance is kept. It also keeps information on the Oracle CDC 
Instances handled by each CDC Service. This database is 
created as part of the CDC Service creation process. 


The CDC Databases: SQL Server databases that store 
changes made to one of the source Oracle databases. The 
CDC Databases are enabled for SQL Server CDC so they 
have the SQL Server CDC tables and functions, making it 
easy to consume changes originating from Oracle. 


COMPONENT/DESCRIPTION COMPONENT CONSISTS OF: 


Oracle CDC Designer: A Microsoft Management Console SQL Server Client: The SQL ADO.NET client that ships with 
snap-in that helps create Oracle CDC Instances. Use this to version 4 of the .NET framework. 

select the tables and columns to be captured, provide Oracle 

connection information and manage the life cycle of CDC 

Instances. 


Oracle Client: The Oracle Instant Client used for 
communication with Oracle. This is a prerequisite component 
that should be obtained from Oracle and installed before 
installing the Oracle CDC Service. 


The Oracle CDC Service and its child Oracle CDC Instances can communicate only with the source Oracle 
database(s) and the target SQL Server instance as clients. They do not actively listen on any network and other 
protocols. The Oracle CDC Service monitors the CDC databases for configuration changes and updates its 
operation based on the updated configuration. 


i als @)g-\e(-6 G1 DIGay-laV/(e> 


11/23/2021 * 6 minutes to read « Edit Online 





Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


The Oracle CDC Service is a Windows service running the program xdbcdcsvc.exe. The Oracle CDC Service can 
be configured to run multiple Windows services on the same computer, each one with a different Windows 
service name. Creating multiple Oracle CDC Windows services on a single computer is often done to achieve a 
better separation between them, or when each needs to work with a different SQL Server instance. 


An Oracle CDC Service is created using the Oracle CDC Service Configuration console or is defined through the 
command-line interface built into the xdbcdcsvc.exe program. In both cases, each Oracle CDC Service created is 
associated with a single SQL Server instance (which may be clustered or mirrored with Always On setup) and 

the connection information (connect string and access credentials) are part of the service configuration. 


When an Oracle CDC Service is started, it tries to connect to the SQL Server instance it is associated with, get 
the list of Oracle CDC instances it needs to handle, and performs an initial environment validation. Errors during 
the service startup and any start/stop information are always written to the Windows application event log. 
When a connection to SQL Server is established, all errors and information messages are written to the 
dbo.xdbcdc_trace table in the MSXDBCDC database of the SQL Server instance. One of the checks made 
during startup is verification that no other Oracle CDC Service with the same name is currently working. If a 
service with the same name is currently connected from a different computer, the Oracle CDC Service enters a 
wait loop, waiting for the other service to disconnect before proceeding to handle the Oracle CDC work. 


When the Oracle CDC Service passes all the startup verifications, it checks the dbo.xdbcdc_databases table in 
the MSXDBCDC database for any enabled Oracle CDC Instances. For every enabled Oracle CDC Instance, the 
service starts a sub-process to handle that Oracle CDC Instance. 


When an Oracle CDC Instance starts, it accesses the SQL Server CDC database with the same name as the CDC 
Instance and retrieves its state from the previous run. It also verifies that everything is running properly. It then 
resumes processing changes; Reading the Oracle transaction logs and writing changes to the CDC database. 


The Oracle CDC Service periodically monitors the dbo.xdbcdc_tables table in the MSXDBCDC database to 
determine if there were any configuration changes to any of the Oracle CDC Instance configurations. If a change 
is found, the Oracle CDC Service notifies the Oracle CDC Instance that it should check its configuration for 
changes. Most configuration changes, such as adding and removing capture instances can be applied while the 
Oracle CDC instance is enabled, others require the Oracle CDC Instance to be restarted. 


When using the Oracle CDC Designer console, changes are automatically detected. When updating the Oracle 
CDC configuration directly using SQL, the following procedure should be called for the Oracle CDC Service to 
notice the configuration change: 


DECLARE @dbname nvarchar(128) = 'HRcdc' 
EXECUTE [MSXDBCDC].[dbo].[xdbcdc_update_config_version] @dbname 
GO 


The Oracle CDC Instance process updates its status in the system table cdc.xdbcdc_state and writes error 
information to the cdc.xdbcdc_trace table. The xdbcdc_state table is useful for monitoring the state of the 
Oracle CDC Instance. It provides up-to-date status, various counters (such as number of changes read from 
Oracle, number of changes written to SQL Server, number of committed transaction written and the current 
number of in-flight transactions) and latency indication. 


The Oracle CDC Instance configuration is saved in the cdc.xdbcdc_config table, which is the table that the 
Oracle CDC Designer console works with. Because the entire configuration of an Oracle CDC Instance is found in 
the target SQL Server instance and CDC databases, it is possible to create SQL Server deployment scripts for an 
Oracle CDC Instance. This is done using the Oracle CDC Service Configuration and Oracle CDC Designer 


consoles. 


Security Considerations 


The following describes the security requirements necessary to work with the CDC Service for Oracle. 


Protection of Source Oracle Data 


The Oracle CDC service does not require access to Oracle source data and is protected by ensuring that the log- 
mining credentials do not give SELECT permission on customer Oracle tables. 


Protection of Source Oracle Change Data 


The Oracle CDC service is provided with log-mining credentials that let the service capture changes made to any 
table in the Oracle database. Change data does not have the granular access permissions regular tables have, 
therefore accessing change data bypasses the built-in Oracle data access controls. 


Captured source Oracle tables have empty mirror tables with the same schema and table name in CDC 
database. The captured data is stored in SQL Server capture instances and offer the same protection as is 
provided for changes captured from SQL Server database. To gain access to the change data that is associated 
with a capture instance, the user must be granted select access to all the captured columns of the associated 
mirror table. In addition, if a gating role is specified when the capture instance is created, the caller must also be 
a member of the specified gating role. Other general change data capture functions for accessing metadata is 
accessible to all database users through the public role, although access to the returned metadata is usually also 
gated by using select access to the underlying source tables, and by membership in any defined gating roles. 


This means that users with the sysadmin fixed server role or the db_owner fixed database role have (by 
default) full access to the captured data, and further access can be granted either through gating roles or by 
granting select access to the captured columns. 


Protection of Source Oracle Log Mining Credentials 


The Oracle CDC service configuration, stored in the CDC database (in the cdc.xdbcdc_config table) includes the 


log mining user name and its associated password. 


The log mining password is stored encrypted by means of an asymmetric key with the fixed name 
xdbcdc_asym_key that is automatically created with the following command: 


USE [<cdc-database-name> ] 
CREATE ASYMMETRIC KEY xdbcdc_asym_key 
WITH ALGORITHM = RSA_1024 
ENCRYPTION BY PASSWORD = ‘<cdc-database-name><asym-key-password>' 


If a different algorithm is used, this key can be dropped and a new one by the same name and encrypted by the 


same password can be created. 


The asymmetric key password is the master password that is saved in the registry under the path 
HKLM\Software\Microsoft\XDBCDCSVC\\<service-name>. That key is accessible only to local 
administrators and to the Oracle CDC Windows service account. The key contains an encrypted binary value 
AsymmetricKeyPassword that stored the asymmetric key password. Access to this registry key is required to 
be able to access to the Oracle log mining credentials. 


To use the ENCRYPTION BY PASSWORD clause, the password must meet the Windows password policy 
requirements for the computer running the SQL Server instance. This is done by selecting the asymmetric key 


password according to that policy. 


If the asymmetric key password is lost, the log mining credentials for each of the Oracle CDC instances must be 
specified again in the Oracle CDC Service Designer. 


The asymmetric key is automatically created in the CDC database when the CDC service detects an Oracle 
instance CDC database that does not have this asymmetric key or when the key exists but the password does 
not match. 


Oracle CDC Service Windows Service Account 


The service account used with the Oracle CDC Windows service does not require any additional privileges. This 
account must be able to use both the Oracle Native Client API and the SQL Server Native Client ODBC API. It 
also needs to be able to access the service configuration key in the registry (this CDC Service Configuration 
console sets up the ACL for that). 


In This Section 

@ High Availability Support 

e SQL Server Connection Required Permissions for the CDC Service 
e User Roles 


e Working with the Oracle CDC Service 


See Also 


How to Manage a Local CDC Service 
Manage an Oracle CDC Service 
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The CDC Service for Oracle is designed for high availability. The following features provide part of the high 
availability support: 


e@ The CDC Service for Oracle does not use any file resource (local or otherwise). Its entire state is stored in 
the target SQL Server instance. This makes it easy to start the service on a different computer that uses 
the same SQL Server instance if the computer the service runs on fails. To reduce recovery time, long or 
long-running Oracle transactions are kept in a staging table in the target SQL Server, preventing the need 
to re-scan many Oracle transaction logs following a failure (or service restart). 


e The CDC Service for Oracle can use clustered SQL Server instances so it can recover after the SQL Server 
instance fails over to another cluster node. The Oracle CDC Service Computer Administrator only needs 
to specify the connection information to the clustered SQL Server instance when creating an Oracle CDC 
Service. 


e The CDC Service for Oracle can use the SQL ServerAlways On database mirroring feature. This support 
requires that the MSXDBCDC and all the CDC databases are in the same availability group. It also requires 
the Oracle CDC Service Computer Administrator to specify the appropriate Always On connection 
information to the SQL Server availability group (for example, the connection properties 

Failover_Partner and Network=dbmssocn ). This allows the CDC service to automatically resume processing 
ona secondary replication of the databases following a failover. 


e@ The CDC Service for Oracle can be configured as a generic service resource on a Windows failover cluster 
(along with, or separate from SQL Server), making it simple to fail over and fall back CDC processing with 
the cluster. To configure the CDC Service for Oracle as a resource in a failover cluster, the system 
administrator must set the CDC Service for Oracle as a Generic Service Resource on each node on the 
failover cluster. 


e The CDC Service for Oracle supports Oracle RAC, which allows it to communicate with the Oracle 
database and process logs even when one of the Oracle RAC nodes is down. 


SQL Server Connection Required Permissions for 


the CDC Service 
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The CDC Service Configuration Console requires connection information to SQL Server to perform their tasks. 


This topic describes the information that can be provided in the Connect to SQL Server dialog box for setting up 


the connection to SQL Server. 


The Connect to SQL Server dialog box opens when necessary, such as when the SQL Server connection 


information is not available or when the information exists but the connection does not have the required 


permissions. 


The following table describes the various tasks where a connection to SQL Server is required and the required 


permissions from the SQL Server login/user. 
TASK 


Prepare SQL Server Instance. 


Create an Oracle CDC Service-SQL Server login for use by 
the Oracle CDC service. 


Create an Oracle CDC Service-login to use for registering 
the new service in MSXDBCDC. 


Edit an Oracle CDC Service-login to use for updating the 
registration of the service in MSXDBCDC. 


Delete an Oracle CDC Service-login to use for updating the 
registration of the service in MSXDBCDC. 


See Also 


Connection to SQL Server 


Connection to SQL Server for Delete 


MINIMUM PERMISSIONS 


dbcreator  fixed-server role 


public fixed-server role 


db_datareader and db_datawriter roles on MSXDBCDC 


db_datareader and db_datawriter roles on MSXDBCDC 


db_datareader and db_datawriter roles on MSXDBCDC 
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This section describes the user roles for the Change Data Capture Service for Oracle by Attunity. The roles 
described are SQL Server database roles, Windows roles, or Oracle database roles. 


Windows User Roles 


The following describes the Windows user roles used by the Oracle CDC Service. 


Computer Administrator: Oracle CDC Service 


The computer administrator is a Windows user responsible for creating and maintaining the CDC Service on the 
computer. This user must belong to the group of local machine administrators. 


The tasks performed by the Oracle CDC Service Computer Administrator include: 
e Installing the CDC Service for Oracle software 
e Creating an Oracle CDC Windows service 


e Setting up the CDC Service connection to the target SQL Server instance (connection string and 
credentials) 


e Ensuring that the CDC Service Master Password with which Oracle log mining credentials are protected 
e Deleting a CDC Service Windows service 

e Uninstalling the CDC Service for Oracle software 

e Maintaining the CDC Service for Oracle software (for example, installing updates) 

e Starting and stopping a CDC Service Windows service 


When working with high-availability configurations, such as Microsoft failover clusters, the computer 
administrator must have additional responsibilities and permissions such as: 


e Installation and maintenance of the CDC Service for Oracle software on all cluster nodes. 


e Defining generic cluster service resources for the CDC Service’ Windows service on the various cluster 
nodes. 


e Acting as the computer administrator authorized as an administrator on the computer where the CDC 
Service for Oracle is installed. This person installs the CDC Service for Oracle and uses the CDC Service 
Configuration Console to configure a CDC Service for Oracle on a local computer. 


Service Account: Oracle CDC Service 


This is Oracle CDC Service Windows Service Account is a Windows account used for running the Oracle CDC 
Service (the Service Account). 


The only required privilege necessary for the service account is to be able to use the Oracle client and the SQL 
Server native client ODBC provider. This account does not need to access files unless required by specific 
providers (for example, if the Oracle client connection string references Oracle database instances in a 
tnsnames.ora file, then that file must be read-accessible to the service account). 


When creating an Oracle CDC Service on Windows Vista or Windows Server 2008, the default service account is 
the NETWORK SERVICE account. 


On Windows 7, Windows Server 2008 R2 and later, the default service account is NT Service\\<service-name>. 


When SQL Server runs on another machine or is a clustered SQL Server instance and there the service needs to 
connect to the target SQL Server using Windows authentication, then the service account should be a domain 


account. 


SQL Server User Roles 


The following describes the SQL Server user roles used by the Oracle CDC Service. 


Oracle CDC Service Administrator 


The CDC Service Administrator is a SQL Server user with full control over the Oracle CDC Service artifacts in the 
target SQL Server instance. The CDC Service Administrator uses the Oracle CDC Designer Console to design 
Oracle CDC Instances. 


The CDC Service Administrator should be granted the SQL Server fixed server roles public and dbcreator. 
The tasks performed by the CDC Service Administrator include: 


e Preparing a SQL Server instance to host Oracle CDC Instances (which are SQL Server databases). In this 
task, a special database called MSXDBCDC is created in the SQL Server instance. 


e Creating an Oracle CDC Instance SQL Server database. Task includes enabling the newly created SQL 
Server database for CDC, which requires a SQL Server system administrator (sysadmin). 


e Designing an Oracle CDC Instance. This task includes providing information about the source Oracle 
database and captured tables, which requires an Oracle database administrator. 


e Maintaining the Oracle CDC Instance over time, which includes adding/removing capture instances and 


updating configuration. 
e Enabling or disabling an Oracle CDC Instance. 
e Monitoring the state of an Oracle CDC Instance. 
e Troubleshooting issues that affect the Oracle CDC Instance. 


The CDC Service Administrator is, at least initially, in the db_owner fixed database role for the SQL Server CDC 
database associated with the Oracle CDC Instance. This gives the CDC Service Administrator access to the 
change data stored in the CDC database. Once created, the db_owner role of the CDC database can be assigned 
to a different user who can carry out all of the tasks listed above except for preparing a SQL Server instance and 
creating another Oracle CDC Instance). 


The CDC Service Administrator does not need to know the master password specified with the creation of the 
Oracle CDC Windows service. 


System Administrator 


The SQL Server system administrator is a SQL Server user and should be granted the fixed server sysadmin 
role on the SQL Server instance associated with the Oracle CDC Service(s). 


There is only one Oracle CDC specific task that carried out with the SQL Server System Administrator and that is 
to enable the SQL Server database for an Oracle CDC Instance for SQL Server CDC. This task is performed using 
the Oracle CDC Designer console when creating a new Oracle CDC Instance. 


Oracle CDC Service User 


The SQL Server Oracle CDC Service user is a SQL Server login which is used by the Oracle CDC Service to 


perform its work against the MSXDBCDC and all of the Oracle CDC Instances (CDC databases) handled by this 
service. 


The SQL Server Oracle CDC Service user should be granted the following: 


e Member of the fixed database roles db_dlladmin, db_datareader, and db_datawriter for all CDC 
databases handled by the server. 


e Member of the fixed database roles db_datareader and db_datawriter for the MSXDBCDC database. 


Because the Oracle CDC Service uses a single SQL Server login to work with all CDC databases and the 
MSXDBCDC database, this login should be mapped in all of these databases. 


Oracle CDC Change Consumer 


The Oracle CDC Change Consumer is a SQL Server user that consumes changes stored in the CDC tables in the 
SQL Server Oracle CDC Instance database. 


This user determines the user role that is required for accessing each of the CDC tables through the CDC 
functions generated by the SQL Server CDC infrastructure. If no user role is specified when a capture instance is 
specified, access to the changes is limited to the member of the db_owner fixed database role of the CDC 
database. 


Oracle User Roles 


The following describes the Oracle user roles used by the Oracle CDC Service. 


Database Administrator (DBA) 


The Oracle database administrator (DBA) is an Oracle database user. The tasks performed by the Oracle DBA 
include: 


e Setting the source Oracle database to work in ARCHIVELOG mode. 

e Setting up a log mining user with the required permissions. 

e Setting supplemental logging for captured tables. 

e Helping to restore archived transaction log files no longer available so they can be processed. 


The Oracle database administrator can get Oracle SQL scripts that need to run so they can be evaluated before 
running them. The Oracle database administrator can also directly run Oracle SQL scripts from the Oracle CDC 


Designer console. 


If the Oracle database administrator chooses to use the Oracle CDC Designer console, administrator's 
credentials are not kept except for the context (dialog) in which they were used. 


The Oracle database administrator works in coordination with the Oracle CDC Service administrator on the 


configuration of the SQL Server Oracle CDC Instances. 


Log Mining User 
The Oracle Log Miner user is a special Oracle database user that is granted the required privileges for accessing 
and processing the Oracle transaction logs. 


The credentials for this user are stored in the SQL Server Oracle CDC Instance database using asymmetric key 
encryption. They are accessible only to the Oracle CDC Service but not to the SQL Server Oracle CDC Instance 


database owner. 
The following list describes the required privileges of the log mining user should be granted: 


e SELECT on <any-captured-table> 


e SELECT ANY TRANSACTION 

e EXECUTE on DBMS_LOGMNR 

e@ SELECT on V$LOGMNR_CONTENTS 
e SELECT on V$ARCHIVED_LOG 

e SELECT on V$LOG 

e SELECT on V$LOGFILE 

e SELECT on V$DATABASE 

e SELECT on V$§THREAD 

e@ SELECT on ALL_INDEXES 

e SELECT on ALL_OBJECTS 

e SELECT on DBA_OBJECTS 

e SELECT on ALL_TABLES 

If any of these privileges cannot be granted to a V$xxx, then they should be granted to the V $xxx. 


Schema User 
The Oracle Schema User is an Oracle user with read access to the schema of the Oracle tables to be captured. 
This user is necessary when working with the Oracle CDC Designer console to retrieve the list of Oracle schema, 


tables to be captured and their columns, indexes and keys. 


The credentials for this user are never stored. They are requested by the CDC Designer console each time they 
are needed and they are kept for the rest of the UI sessions. 
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This section describes some important concepts of the Oracle CDC Service. The concepts included in this section 
are: 


e The MSXDBCDC Database 
This section describes the tables that are included in this database and how it is important to CDC. 
e The CDC Databases 


This section provides a brief description of the CDC databases. These databases are created using the 
Oracle CDC Designer Console. See the documentation included with your installation of the CDC 
Designer Console for more information about the CDC databases. 


e Using the Command Line to Configure the CDC Service 


This section describes the command-line commands that can be used to configure the Oracle CDC 
Service. 


The MSXDBCDC Database 


The MSXDBCDC (Microsoft External-Database CDC) database is a special database that is required when using 
the CDC Service for Oracle with a SQL Server instance. 


The name of this database cannot be changed. If a database called MSXDBCDC exists on the host SQL Server 
instance and contains tables other than those defined by the CDC Service for Oracle, the host SQL Server 
instance cannot be used. 


The main uses for this database are to: 


e Serve asa registry of Oracle CDC Services associated with a SQL Server instance. This information is 
used for the service configuration and design components and to support coordination of multiple CDC 


services by the same name on different nodes over which one is the active one. 


e Serve as a registry of the Oracle CDC instances contained in a SQL Server instance, the CDC service that 
handles each instance, and the configuration version each uses. This information is equivalent to the 
is_cdc_enabled column in the sys.databases table of the master database. The CDC service 
periodically scans the dbo.xdbcdc_databases table to identify changes made to the CDC configuration 
or to the list of captured instances. 


e Hold sysadmin-owned stored procedures that help create and maintain CDC instances. These are similar 
to the system procedures that are used for the implementation of the SQL Server CDC feature. 


Creating the MSXDBCDC Database 


An MSXDBCDC database must be created before the Oracle CDC Service can be defined. You can create only 
one MSXDBCDC database on a SQL Server instance. The MSXDBCDC database is created when you prepare a 
SQL Server database for Oracle CDC. This can be done by using the Oracle CDC Service Configuration Console 
or by running a creation script that is generated by the CDC Service Configuration Console. 


The owner of this database is the Oracle CDC Service Administrator, who can control all of the Oracle CDC 
instances hosted under the SQL Server instance. 


See also: 
How to Prepare SQL Server for CDC 


The MSXDBCDC Database Tables 
This section describes the following tables in the MSXDBCDC database. 


e dbo.xdbcdc_trace 
e dbo.xdbcdc_databases 
e dbo.xdbcdc_services 


dbo.xdbcdc_trace 


This table stores tracing information for the Oracle CDC Service. The information stored in this table includes 
notable status changes and trace records. 


The Oracle CDC Service writes error records and some of the information records to both the Windows event 
log and the trace table. In some cases the trace table may not be accessible, in which case the error information 


is accessible from the event log. 


The following describes the items that are included in the dbo.xdbcdc_trace table. 


ITEM DESCRIPTION 
timestamp The exact UTC timestamp when the trace record was written. 
type Contains one of the following values. 

ERROR 

INFO 

TRACE 
node The name of the node on which the record was written. 
status The status code that is used by the state table. 
sub_status The substatus code that is used by the state table. 
status_message The status message that is used by the state table. 
source The name of the Oracle CDC component that produced the 


trace record. 


text_data Additional text data for cases when the error or trace record 
contains a textual payload. 


binary_data Additional binary data for cases when the error or trace 
record contains a binary payload. 


The Oracle CDC instance will delete old trace table rows according to the change tables retention policy. 


dbo.xdbcdc_databases 


This table contains the names of CDC Service for Oracle CDC databases in the current SQL Server instance. Each 
database corresponds to an Oracle CDC instance. The Oracle CDC Service uses this table to determine which 


instances to start or stop and which instances to reconfigure. 


The following table describes the items that are included in the dbo.xdbcdc_databases table. 


ITEM 


name 


config_version 


cdc_service_name 


enabled 


dbo.xdbcdc_services 


DESCRIPTION 


The name of the Oracle database in the SQL Server instance. 


The timestamp (UTC) for the last change in the 
corresponding CDC database xdbcdc_config table or the 
timestamp (UTC) for the current row in this table. 


The UPDATE trigger enforces a value of GETUTCDATE() for 
this item. config_version lets the CDC service identify the 
CDC instance that needs to be checked for configuration 
change or for enabling/disabling. 


This item determines which Oracle CDC Service handles the 
selected Oracle database. 


Indicates whether the Oracle CDC instance is active (1) or 
disabled (0). When the Oracle CDC Service starts only the 
instances marked enable (1) are started. 


Note: An Oracle CDC instance can become disabled due to 
an error that is not retryable. In this case, the instance must 
be restarted manually after the error is resolved. 


This table lists the CDC services associated with the host SQL Server instance. This table is used by the CDC 
Designer Console to determine the list of CDC services that are configured for the local SQL Server instance. It is 


also used by the CDC service to ensure that only one running Windows service handles a given Oracle CDC 


Service name. 


The following describes the capture state items that are included in the dbo.xdbcdc_databases table. 


ITEM 


cdc_service_name 


cdc_service_sql_login 


ref_count 


DESCRIPTION 


The name of the Oracle CDC Service (the Windows service 
name). 


The name of the SQL Server login used by the Oracle CDC 
Service to connect to the SQL Server instance. A new SQL 
User named cdc_service is created and associated with this 
login name and is then added as a member of the 
db_ddladmin, db_datareader and db_datawriter fixed 
database roles for each CDC database handled by the 
service. 


This item counts the number of machines where the same 
Oracle CDC Service is installed. It gets incremented with 
each addition of same-named Oracle CDC service, and it is 
decremented when such a service is removed. When the 
counter reaches zero, this row is deleted. 


ITEM DESCRIPTION 


active_service_node The name of the Windows node that currently handles the 
CDC service. When the service is stopped correctly, this 
column is set to null, indicating that there is no longer an 
active service. 


active_service_heartbeat This item tracks the current CDC service to determine if it 
still active. 


This item is updated with the current database UTC 
timestamp for the active CDC service at regular intervals. 
The default interval is 30 seconds, however the interval is 
configurable. 


When a pending CDC service detects that the heartbeat was 
not updated after the configured interval has passed, the 
pending service attempts to take over the active CDC 
service role. 


options This item specifies the secondary options, such as tracing or 
tuning. It is written in the form of name[=value]|[; ]. The 
options string uses the same semantics as the ODBC 
connection string. If the option is Boolean (with a value of 
yes/no), the value can include the name only. 


trace has the following possible values. 
true 

on 

false 

off 


<class name>|[,class name>] 


The default value is false. 


service_heartbeat_interval is the time interval (in 
seconds) for the service to update the 
active_service_heartbeat column. The default value is 30. 
The maximum value is 3600. 


service_config_polling_interval is the polling interval (in 
seconds) for the CDC service to check for configuration 
changes. The default value is 30. The maximum value is 
3600. 


sql_command_timeout is the command timeout that 


works with the SQL Server. The default value is 1. The 
maximum value is 3600. 


The MSXDBCDC Database Stored Procedures 
This section describes the following stored procedures in the MSXDBCDC database. 


e dbo.xcbcdc_reset_db(Database Name) 


e dbo.xdbcdc_disable_db(dbname) 

@ dbo.xcbcdc_add_service(svcname,sqlusr) 
e dbo.xdbcdc_start(dbname) 

e dbo.xdbcdc_stop(dbname) 


dbo.xcbcdc_reset_db(Database Name) 


This procedure clears the data of an Oracle CDC instance. It is used: 


e Torestart data capturing while disregarding previous data, for example following source database 


recovery or following inactivity where some of the Oracle transaction logs are not available. 
e When there is a corruption in the CDC state (specifically in the any cdc.*tables data). 
The dbo.xcbcdc_reset_db procedure performs the following tasks: 
e Stops the CDC instance (if active). 
e Truncates the change tables, the cdc_Ilsn_mapping table, and the cdc_ddl_history table. 
e Clears the cdc_xdbcdc_state table. 


e Clears the start_lsn column for each row of the cdc_change_table. 


To use the dbo.xcbcdc_reset_db procedure, the user must be a member of the db_owner database role for 
the CDC Instance database being named or else member of the sysadmin or serveradmin fixed server role. 


For more information about the CDC tables, see The CDC Databases in the help system in the CDC Designer 
Console. 


dbo.xdbcdc_disable_db(dbname) 


The dbo.xcbcdc_disable_db procedure performs the following task: 


e Removes the entry for the selected CDC database in the MSXDBCDC.xdbcdc_databases table. 


To use the dbo.xcbcdc_disable_db procedure, the user must be a member of the db_owner database role for 
the CDC instance being named or a member of the sysadmin or serveradmin fixed server role. 


For more information about the CDC tables, see The CDC Databases in the help system in the CDC Designer 


Console. 


dbo.xcbcdc_add_service(svcname,sqlusr) 


The dbo.xcbcdc_add_service procedure adds an entry to the MSXDBCDC.xdbcdc_services table and adds 
an increment of one to the ref_count column for the service name in the MSXDBCDC.xdbcdc_services table. 
When the ref_count is 0, it deletes the row. 


To use the dbo.xcbcdc_add_service<service name, username> procedure, the user must be a member of 
the db_owner database role for the CDC instance database being named or a member of the sysadmin or 


serveradmin fixed server role. 


dbo.xdbcdc_start(dbname) 


The dbo.xdbcdc_start procedure sends a start request to the CDC service that handles the selected CDC 
instance to start the change processing. 


To use the dbo.xcdcdc_start procedure, the user must be a member of the db_owner database role for the 
CDC database or be a member of either the sysadmin or serveradmin roles for the SQL Server instance. 


dbo.xdbcdc_stop(dbname) 


The dbo.xdbcdc_stop procedure sends a stop request to the CDC service that handles the selected CDC 
instance to stop the change processing. 


To use the dbo.xcdcdc_stop procedure, the user must be a member of the db_owner database role for the 
CDC database or be a member of either the sysadmin or serveradmin roles for the SQL Server instance. 


The CDC Databases 


Each Oracle CDC instance used in a CDC service is associated with a specific SQL Server database called the 
CDC Database. This SQL Server database is hosted in the SQL Server instance associated with the Oracle CDC 
Service. 


The CDC Database contains a special cdc schema. The Oracle CDC Service uses this schema with table names 
with the prefix xdbcdc_. This schema is used for security and consistency purposes. 


Both the Oracle CDC instance and the CDC databases are created using the Oracle CDC Designer Console. For 
more information about the CDC databases, see the documentation included with your installation of the Oracle 
CDC Designer Console. 


Using the Command Line to Configure the CDC Service 


You can operate the Oracle CDC Service program (xdbcdcsvc.exe) from the command line. The CDC service 
program is a native 32-bit/64-bit Windows executable file. 


See also 
How to Use the CDC Service Command-Line Interface 


Service Program Commands 


The section describes the following commands that are used to configure the CDC service. 
e Config 
e Create 
e Delete 


Config 


Use config to update an Oracle CDC Service configuration from a script. The command can be used to update 
only specific parts of the CDC service configuration (for example, only the connection string without knowing 
the asymmetric key password). The command must be run by a computer administrator. The following is an 
example of the config command. 


"<path>xdbcdcsvc.exe" config 
<cdc-service-name> 
[connect= <sql-server-connection-string> ] 
[key= <asym-key-password> ] 
[svcacct= <windows-account> <windows-password> ] 
[sqlacct= <sql-username> <sql-password>] 


Where: 
cdc-service-name is the name of the CDC service to be updated. This is a required parameter. 


sql-server-connection-string is the connect string to be updated. If the connect string contains spaces or 
quotes then it must be wrapped in double-quotation marks ("). Embedded quotes are escaped by doubling the 
quotation marks. 


asym-key-password is the password to be updated. 


windows-account, windows-password are the Windows account credentials for the service that is being 
updated. 


sql-username, sql-password are the SQL Server authentication credentials being updated. If sqlacct has both 
an empty username and empty password, then the Oracle CDC Service connects to SQL Server using Windows 
authentication. 


Note: Any parameter that contains spaces or double quotes must be wrapped with double quotes ("). 
Embedded double quotation marks must be doubled (for example to use "A#B" D as a password enter ""A#B"" 
D"). 


Create 


Use create to create an Oracle CDC Service from a script. The command must be run by a computer 


administrator. The following is an example of the create command: 


"<path>xdbcdcsvc.exe" create 
<cdc-service-name> 
[connect= "<sql-server-connection-string>" ] 
[key= <asym-key-password> ] 
[svcacct <windows-account> <windows-password> ] 
[sqlacct <sql-username> <sql-password>] 


Where: 


cdc-service-name is the name of the newly created service. If there is already a service with this name, the 
program returns an error. You should not use long names or names with spaces. The characters "/" and "\" are 
not valid characters in a service name. This is a required parameter. 


sql-server-connection-string is the connect string to use to connect to the SQL Server instance that is 
associated with the new Oracle CDC Service. 


asym-key-password is the password that protects the asymmetric key used for storing the source database 
log-mining credentials. 


windows-account, windows-password are the account name and password associated with the Oracle CDC 
Service being created. 


sql-username, sql-password are the SQL Server account name and password used to connect to the SQL 
Server instance. If both of these parameters are empty, then CDC Service for Oracle connects to SQL Server 
using Windows authentication. 


Note: Any parameter that contains spaces or double quotes must be wrapped with double quotes ("). 
Embedded double quotation marks must be doubled (for example to use "A#B" D as a password enter ""A#B"" 
D'; 


Delete 


Use Delete to cleanly delete the Oracle CDC Service from a script. This command must be run by a computer 


administrator. The following is an example of the Delete command. 


"<path>xdbcdcsvc.exe" delete 
<cdc-service-name> 


Where: 


cdc-service-name is the name of the CDC service to be deleted. 


Note: Any parameter that contains spaces or double quotes must be wrapped with double quotes ("). 
Embedded double quotation marks must be doubled (for example to use "A#B" D as a password enter ""A#B"" 
D"). 


See Also 


How to Use the CDC Service Command-Line Interface 
How to Prepare SQL Server for CDC 
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Applies to: Q@sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 
You use the CDC Service Configuration Console to define a local Oracle CDC Service, update it, and delete it. 
The topics in this section help provide information about the information you need to provide when using the 


CDC Service Configuration Console. 


In This Section 


e® Connection to SQL Server 

® Connection to SQL Server for Delete 

® Create and Edit an Oracle CDC Service 

e@ Manage an Oracle CDC Service 

e@ Prepare SQL Server for CDC 

e Prepare SQL Server for Oracle CDC-View Script 


e Work with CDC Services 
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When a login without a database role that includes write permission (for example the db_owner role) to the 
MSXDBCDC database attempts to create an Oracle CDC instanced, the Connect to SQL Server dialog box is 
displayed. 


In this dialog box you must enter the credentials for a login that has write permission to the MSXDBCDC 
database, such the db_owner database role to create the new Oracle CDC instance. 


Enter the following information in the Connect to SQL Server dialog box. 


Server Name 


Type the name of the server where the SQL Server is located. 


Authentication 


Select one of the following: 
e Windows Authentication 


e SQL Server Authentication: If you select this option, you must type the Login and Password for the 
user in the SQL Server you are connecting to. 


Options 


Click the arrow to view available options to be configured. You can choose to leave these options with their 
default value. The available options are: 


e Connection Timeout: Type the time (in seconds) the program waits for the SQL Server connection to be 
established before producing a timeout error. The default value is 15. 


e Execution Timeout: Type the time (in seconds) that the program waits for SQL command execution to 
finish before producing a timeout error. The default value is 30. 


e Encrypt Connection: Select Encrypt Connection to ensure that the SQL Server connection that being 
established is encrypted to guarantee privacy. 


e Advanced: Click Advanced and type any additional connection properties into the Advanced 


Connection Properties dialog box, if necessary. 


See Also 


SQL Server Connection Required Permissions for the CDC Service 


Connection to SQL Server for Delete 
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When a login without a database role that includes write permission (for example the db_owner role) to the 
MSXDBCDC database attempts to delete an Oracle CDC instance, the Connect to SQL Server dialog box is 
displayed. 


In this dialog box you must enter the credentials for a login that has write permission to the MSXDBCDC 
database, such the db_owner database role to delete the Oracle CDC instance. 


Enter the following information in the Connect to SQL Server dialog box. 


Server Name 


Type the name of the server where the SQL Server is located. 


Authentication 
Select one of the following: 


e Windows Authentication 


e SQL Server Authentication: If you select this option, you must type the Login and Password for the 
user in the SQL Server you are connecting to. 


Options 
Click the arrow to view available options to be configured. You can choose to leave these options with their 
default value. The available options are: 


e Connection Timeout: Type the time (in seconds) the program waits for the SQL Server connection to be 
established before producing a timeout error. The default value is 15. 


e Execution Timeout: Type the time (in seconds) that the program waits for SQL command execution to 
finish before producing a timeout error. The default value is 30. 


e Encrypt Connection: Select Encrypt Connection to ensure that the SQL Server connection that being 
established is encrypted to guarantee privacy. 


e Advanced: Click Advanced and type any additional connection properties into the Advanced 


Connection Properties dialog box, if necessary. 


See Also 


SQL Server Connection Required Permissions for the CDC Service 
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Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 
You create and edit a new Oracle CDC Windows Service from the CDC Service Configuration Console. 


To create a new Oracle CDC Windows service, select Local CDC Services from the left pane, then click New 
Service from the Actions pane. You can also right-click Local CDC Services and select New Service. The 
New Oracle CDC Windows Service dialog box opens. 


OR 


To edit the CDC service properties, select the service that you want to edit the properties for and click 
Properties from the Actions pane. You can also right-click the service you are working with and select 
Properties. The CDC Service Properties dialog box opens. 


Enter the following information in the New Oracle CDC Windows Service dialog box or the CDC Service 
Properties dialog box. 


Service Name 
Type the name of the new Oracle CDC Windows Service. You should not use long names, if possible. The 
characters / and \ cannot be used in the service name. 





NOTE 


This option is not available when editing the service. You cannot change the name of a Windows service that already 
exists. 











Description 
Type a description of the service to help identify it. 


Service Account 
Select one of the following to determine under which account to run the service: 


e Local System Account 
This is not recommended because it gives too many permissions to the service. 
e This Account 


On Windows Vista or Windows Server 2008, the default service account is the NETWORK SERVICE 
account. 


On Windows 7, Windows Server 2008 R2 and later, the default service account is NT Service\\<service- 


name>. 


Using these accounts lets you work without using passwords because a password is not necessary for 
these accounts. In addition these accounts provide only the necessary permissions required for the 
Oracle CDC Service to run. 


You can use a local or domain Windows account for the service account. In this case, you must enter the 
Password for that account. This account can be for the local host or a domain account. Be sure to update 
the password when it is changed using Local Services in the Windows Control Panel. 


Server name: Select the target SQL Server instance to connect to (for example, \\<computer_name>\ 
<instance_name>). The server instance last connected to is displayed by default. 


Authentication 
Select one of the following: 


e Windows Authentication: If you select this option, the Oracle CDC service connects to the target SQL 
Server instance using the service account identity. If the SQL Server instance is running on a different 
computer, Windows Authentication must be used with domain accounts. 


e SQL Server Authentication: If you select this option, you must type the User Name and Password 
for the SQL Server login you want to use. The Oracle CDC service uses these credentials when connecting 
to the target SQL Server instance. 


The SQL Server login used by the Oracle CDC Service only needs to be a member of the public fixed-server role, 
no other privileges are needed. Once new Oracle CDC Instances are added, that login will gain db_owner 
access to the associated SQL Server CDC databases. 


To create the Oracle CDC Windows Service definition, the program needs update access to the MSXDBCDC 
database in the associated SQL Server instance. When you click OK, a dialog box prompts the user to enter a 
SQL Server login with an update access to the MSXDBCDC database. 


For information about the data you must type into the Connect to SQL Server dialog box, see Connection to SQL 
Server. 


Options 
Click the arrow to view available options to be configured. You can choose to leave these options with their 
default value. The available options are: 


e Connection Timeout: Type the time (in seconds) that the CDC Service for Oracle waits for a connection 
to the SQL Server before timing out. The default value is 15. 


e Execution Timeout: Type the time (in seconds) that the Oracle CDC Windows Service waits for a 
command to execute before timing out. The default value is 30. 


e Encrypt Connection: Select Encrypt Connection for communication between the Oracle CDC Service 
and the target SQL Server instance using an encrypted connection. 


e Advanced: Type any additional connection properties, if necessary. 


Master Password 
Enter a password to be used by the Oracle CDC Windows Service to protect the Oracle log-mining credentials. 


The same master password must also be used when other instances of the same service are configured on other 
nodes on a cluster in high-availability configuration. If you lose or modify the master password, all log mining 
passwords stored in Oracle CDC Instance databases must be re-entered using the CDC Designer console. 


See Also 


How to Create and Edit a CDC Service 
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You can use the CDC Service Configuration Console to manage a specific CDC Service. 

To select the CDC service you want to work with 

1. From the left pane in the CDC Service Configuration Console, expand Local CDC Services. 

2. Select the CDC service you want to work with. 


You can also right-click the CDC service you want to work with and select the desired action. See What 
can you do with a CDC Service. 


OR 
1. Select Local CDC Services from the left pane in the CDC Service Configuration Console. 


2. From the middle section of the CDC Service Configuration Console, select the service you want to work 
with. 


You can also right-click the CDC service you want to work with and select the desired action. See What 
can you do with a CDC Service. 


What can you do with a CDC Service 


You can carry out the following actions when working with a CDC service. 


Delete the service 


From the Actions pane on the right side of the CDC Service Configuration Console, click Delete to delete the 
service. 


You can also right-click the CDC service you want to delete and select Delete. 
Note: If the service is running when deleting the service, the service is stopped before being deleted. 


To delete the Oracle CDC Windows Service definition, the program needs update access to the MSXDBCDC 
database in the associated SQL Server instance. When you click OK to delete the service, the program attempts 
to delete the Oracle CDC Service registration in the MSXDBCDC database. If the program cannot delete the 
Oracle CDC Service registration because it does not have the proper permissions, it prompts the user to enter a 
SQL Server login with update permissions to the MSXDBCDC database. 


For information about the data you must enter in the Connect to SQL Server dialog box, see Connection to SQL 
Server for Delete. 


Edit the CDC Service Properties 


From the Actions pane on the right side of the CDC Service Configuration Console, click Properties. 


You can also right-click the CDC service where you want to edit the properties and select Properties. 


See Also 


How to Manage a Local CDC Service 
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The Oracle CDC service requires all target SQL Server instances to contain the MSXDBCDC database. You create 
this database using the Prepare SQL Server action in the CDC Service Configuration Console. This creates a 
special script that is run to create the required tables, stored procedures, and other required artifacts for this 
database. This task is done one time only for each target SQL Server instance. 


For more information about the MSXDBCDC database, see The MSXDBCDC Database. 


In the CDC Service Configuration Console, click Prepare SQL Server. If this option is not available, make sure 
that Local CDC Services is selected in the left pane of the console. 


Options 
Server Name 


Type the name of the server where the SQL Server is located. 


Authentication 


Select one of the following: 
e Windows Authentication 


e SQL Server Authentication: If you select this option, you must type the User Name and Password 
for the user in the SQL Server you are connecting to. 


To prepare the SQL Server instance for Oracle CDC, the login must have write permission to the MSXDBCDC 
database. Enter the credentials for a login that has write permission to the MSXDBCDC database, such as a 
member of the sysasmin role. 


Options 
Click the arrow to view available options to be configured. You can choose to leave these options with their 


default value. The available options are: 


e Connection Timeout: Type the time (in seconds) that the CDC Service for Oracle waits for a connection 
to the SQL Server before timing out. The default value is 15. 


e Execution Timeout: Type the time (in seconds) that the Oracle CDC Windows Service waits for a 
command to execute before timing out. The default value is 30. 


e Encrypt Connection: Select Encrypt Connection for communication between the Oracle CDC Service 
and the target SQL Server instance using an encrypted connection. 


e Advanced: Type any additional connection properties, if necessary. 


View Script 


Click View Script to view a read-only version of the setup script. A SQL Server system administrator can copy 
this script into the SQL Server Management Console to edit it, if necessary. For more information about the 
Prepare SQL Server Script, see Prepare SQL Server for Oracle CDC-View Script. 


See Also 


How to Work with CDC Services 
How to Prepare SQL Server for CDC 
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This dialog box shows the Prepare SQL script that creates the MSXDBCDC database. This database is must be on 
a SQL Server instance for it to be used with Oracle CDC for SQL Server. 


Do the following in the Prepare SQL Server Script dialog box. 


Save As 
Saves the script in a text file that you can save in any location you want. You can then run the scripts at a later 
time by pasting the script into the SQL Server Management Studio. 


Copy 
Copies the script to the clipboard. You can then paste the script into the SQL Server Management Studio to run 
them and create the MSXDBCDC database. 


See Also 


Prepare SQL Server for CDC 
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You can use the CDC Service Configuration Console to create a new CDC service and to prepare a SQL Server 
database for CDC. 


Options 


Prepare SQL Server 
Select this option from the Actions pane on the right side of the CDC Service Configuration Console. 


You can also right-click Local CDC Services and select Prepare SQL Server. 
The Preparing SQL Server Instance for Oracle CDC dialog box opens. 


For information on how to use this dialog box, see Prepare SQL Server for CDC. For information on how to 
enable a SQL Server instance for CDC, see How to Prepare SQL Server for CDC. 


Create a new CDC service 
Click New Service from the Actions pane on the right side of the CDC Service Configuration Console. 


You can also right-click Local CDC Services and select New Service. 


The New Oracle CDC Service dialog box opens. 


See Also 


How to Work with CDC Services 
Create and Edit an Oracle CDC Service 
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This section describes how to carry out tasks in the CDC Service Configuration Console. 


Learn how to use the CDC Service for Oracle Service Configuration UI 


How to Create and Edit a CDC Service 

How to Manage a Local CDC Service 

How to Prepare SQL Server for CDC 

How to Use the CDC Service Command-Line Interface 


How to Work with CDC Services 


How to Create and Edit a CDC Service 
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These procedures describe how to create and edit a new Oracle CDC Service from the CDC Service 
Configuration Console. 


This procedure requires a Windows user with administrator privileges on the computer where the Oracle CDC 
service is configured. 


To create a new CDC service 


1. From the Start menu, select CDC Service Configuration for Oracle. 
2. From the left pane, right click Local CDC Services and select New Service 
You can also click New Service from the Actions pane. 


3. Type or enter the required information in the New Oracle CDC Service dialog box. See Create and Edit an 
Oracle CDC Service for information on how to enter information in the New Oracle CDC Service dialog 
box. 


The SQL Server login provided in the New Oracle CDC Service dialog box is used by the Oracle CDC 
Service when the service runs. This login only needs to be a member of the public fixed-server role, no 
other privileges are needed. Once new Oracle CDC Instances are added, that login receives db_owner 
access to the associated SQL Server CDC databases. 


4. When you finish entering the required information, click OK. 


To create the Oracle CDC Windows Service definition, the program needs update access to the 
MSXDBCDC database in the associated SQL Server instance. When you click OK, a dialog box prompts 
the user to enter a SQL Server login with an update access to the MSXDBCDC database. 


For information about the data you must type into the Connect to SQL Server dialog box, see Connection 
to SQL Server. 


5. Click OK to close the New Oracle CDC Service dialog box. 


To edit a CDC service 


1. From the Start menu, select CDC Service Configuration for Oracle. 


2. From the left pane, select Local CDC Services then right-click the local service you want to edit and 
select Properties. 


You can also select the service you are working with in the middle and then from the Actions pane, click 
Properties. 


3. Type or enter the required information in the CDC Service Properties dialog box. See Create and Edit an 
Oracle CDC Service for information on how to enter information in the CDC Service Properties dialog 
box. 


4. When you finish entering the required information, Click OK, the Connect to SQL Server dialog box 
opens. 


When a login without write permission to the MSXDBDCDC database attempts to create a new Oracle 


CDC instance an error message is displayed. Click OK in that dialog box to display the Connect to SQL 
Server dialog box. In this dialog box you must enter the credentials for a login that has write permission 
to the MSXDBCDC database, such the db_owner database role. 


For information about the data you must type into the Connect to SQL Server dialog box, see Connection 
to SQL Server. 


5. Click OK in the Connect to Oracle dialog box. Both dialog boxes close and the service is updated and 
registered. 


See Also 


Change Data Capture Designer for Oracle by Attunity 
Create and Edit an Oracle CDC Service 
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This procedure describes how to use the CDC Service Configuration Console to manage specific CDC services. 


To manage a specific CDC Service 


1. From the Start menu, select the CDC Service Configuration for Oracle. 
2. From the left pane in the CDC Service Configuration Console, expand Local CDC Services. 
3. Select the CDC service you want to work with. 
You can also right-click the CDC service you want to work with and select the desired action. 
OR 


Select Local CDC Services from the left pane in the CDC Service Configuration Console then select the 
service you want to work with from the middle section of the CDC Service Configuration Console. 


You can also right-click the CDC service you want to work with and select the desired action. 
4. You can carry out the following tasks when working with a CDC service. 
e Delete the service 


From the Actions pane on the right side of the CDC Service Configuration Console, click Delete 
to delete the service. 


You can also right-click the CDC service you want to delete and select Delete. 


Note: If the service is running when deleting the service, the service is stopped before being 
deleted. 


To delete an Oracle CDC Windows Service definition, the program needs update access to the 
MSXDBCDC database in the associated SQL Server instance. When you click OK to delete the 
service, the program attempts to delete the Oracle CDC Service registration in the MSXDBCDC 
database. If it fails due to lack of permissions, a dialog box is displayed to prompt the user to enter 
a SQL Server login with an update access to the MSXDBCDC database. 


For information about the data you must enter in the Connect to SQL Server dialog box, see 
Manage an Oracle CDC Service and Connection to SQL Server for Delete. 


e Edit the CDC Service Properties 


From the Actions pane on the right side of the CDC Service Configuration Console, click 
Properties. 


You can also right-click the CDC service where you want to edit the properties and select 


Properties. 


See Also 


Manage an Oracle CDC Service 
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The Oracle CDC service requires all target SQL Server instances to contain the MSXDBCDC database. You create 
this database using the Prepare SQL Server action in the CDC Service Configuration Console.This task is done 
one time only for each target SQL Server instance. 


The following describes how to prepare a SQL Server database for Oracle Change Data Capture using the CDC 
Service Configuration Console. This process creates the MSXDBCDC database and defines the required tables, 
stored procedures, and other required artifacts. 


Preparing the SQL Server for Oracle CDC is done by the Oracle CDC Service Administrator. For more 
information about the CDC Service Administrator role, see User Roles. 


To enable SQL Server for CDC 


1. From the Start menu, select the CDC Service Configuration for Oracle. 
2. From the left pane, select Local CDC Services then from the Actions pane, click Prepare SQL Server. 
You can also right-click Local CDC Services and select Prepare SQL Server. 


3. Enter the required information in the Preparing SQL Server Instance for Oracle CDC dialog box. For 
information on how to enter the required information into this dialog box, see Prepare SQL Server for 
CDC. 


To Prepare the SQL Server instance for Oracle CDC, the login must have write permission to the 
MSXDBCDC database. Enter the credentials for a login that has write permission to the MSXDBCDC 
database, such as a member of the sysasmin role. 


Note: You can click View Script to view a read-only version of the setup script. A SQL Server system 
administrator can copy this script into the SQL Server Management Console to edit and execute it, if necessary. 


See Also 


Prepare SQL Server for CDC 
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The Oracle CDC service program, xdbcdcsvc.exe, normally runs the Oracle CDC Windows service but it can be 
invoked directly from the command line to create, or delete an Oracle CDC Windows service. 


To use the command line 


1. From the Start menu, open the command-line console. Type cmd in the run or search box to open the 
console. 


2. At the command prompt, type cd and the full path to the folder where the CDC Service for Oracle is 
installed. 


3. Type the command that you need to carry out one of the possible tasks. 
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This procedure describes how to use the CDC Service Configuration Console to prepare a SQL Server instance 
to work with Oracle CDC Services and to create a new CDC service. 


To work with CDC services 


1. From the Start menu, select the CDC Service Configuration for Oracle. 
2. From the left pane, select Local CDC Services (the root level). 
3. You carry out the one or both of the following tasks: 

e Prepare SQL Server 


Select this option from the Actions pane on the right side of the CDC Service Configuration 
Console. 


You can also right-click Local CDC Services and select Prepare SQL Server. 
The Preparing SQL Server Instance for Oracle CDC dialog box opens. 


To prepare the SQL Server instance for Oracle CDC services, the login must have a SQL Server 
login with the dbcreator fixed server role. This login is used to create the MSXDBCDC database 
that is required for adding Oracle CDC Services and, later on, Oracle CDC Instances. 


For information on how to use this dialog box, see Prepare SQL Server for CDC. For information 
on how to enable a SQL Server instance for CDC, see How to Prepare SQL Server for CDC. 


e Create a new CDC service 


Click New Service from the Actions pane on the right side of the CDC Service Configuration 
Console. 


You can also right-Click Local CDC Services and select New Service. 
The New Oracle CDC Service dialog box opens. 


For information on how to use this dialog box, see Create and Edit an Oracle CDC Service. For 
information on how to create or edit a CDC service, see How to Create and Edit a CDC Service. 


The SQL Server login used by the Oracle CDC Service only needs to be a member of the public 
fixed-server role, no other privileges are needed. However, to create the Oracle CDC Service, the 
login must have write permission to the MSXDBCDC database, for example the db_owner 
database role must be assigned to the login. When a login without write permission to the 
MSXDBDCDC database attempts to create a new Oracle CDC instance an error message is 
displayed. Click OK in that dialog box to display the Connect to SQL Server dialog box. 


For information on how to enter the credentials for a login that has write permission to the 
MSXDBCDC database, such the db_owner database role, see Create and Edit an Oracle CDC 
Service and Connection to SQL Server. 


See Also 
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The Microsoft Connector for SAP BW consists of a set of three components that let you extract data from, or 
load data into, an SAP Netweaver BW version 7 system. 


The Microsoft Connector for SAP BW for SQL Server 2016 is a component of the SQL Server 2016 Feature Pack. 
To install the Connector for SAP BW and its documentation, download and run the installer from the SQL Server 
2016 Feature Pack web page. 


IMPORTANT 


Microsoft does not anticipate providing an updated version of the Connector for SAP BW. Microsoft does not own the 
source code for the SAP BW components, which were developed by a third party, and as a result cannot update them. 
Consider purchasing the latest SAP connectivity components from a Microsoft ISV partner such as Theobald Software. 


Microsoft's ISV partners have adapted their SAP connectivity components for SSIS for installation in Azure. 








IMPORTANT 


The documentation for the Microsoft Connector for SAP BW assumes familiarity with the SAP Netweaver BW 
environment. For more information about SAP Netweaver BW, or for information about how to configure SAP Netweaver 


BW objects and processes, see your SAP documentation. 


IMPORTANT 


Extracting data from SAP Netweaver BW requires additional SAP licensing. Check with SAP to verify these requirements. 











Components 


The Microsoft Connector for SAP BW has the following components: 


e SAP BW Source-The SAP BW source is a data flow source component that lets you extract data from an 
SAP Netweaver BW version 7 system. 


e SAP BW Destination-The SAP BW destination is a data flow destination component that lets you load 
data into an SAP Netweaver BW version 7 system. 


e SAP BW Connection Manager-The SAP BW connection manager connects either an SAP BW source or 
SAP BW destination to an SAP Netweaver BW version 7 system. 


For a walkthrough that demonstrates how to configure and use the SAP BW connection manager, source, and 
destination, see the white paper, Using SQL Server Integration Services with SAP BI 7.0. This white paper also 
shows how to configure the required objects in SAP BW. 


Documentation 


This Help file for the Microsoft Connector for SAP BW contains the following topics and sections: 


Installing the Microsoft Connector for SAP BW 
Describes the installation requirements for the Microsoft Connector for SAP BW. 


Microsoft Connector for SAP BW Components 
Describes each component of the Microsoft Connector for SAP BW. 


Microsoft Connector for SAP BW F1 Help 
Describes the user interface of each component of the Microsoft Connector for SAP BW. 


Installing the Microsoft Connector for SAP BW 
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The Microsoft Connector for SAP BW for SQL Server 2016 is a component of the SQL Server 2016 Feature Pack. 
To install the Connector for SAP BW and its documentation, download and run the installer from the SQL Server 
2016 Feature Pack web page. 


IMPORTANT 


Microsoft does not anticipate providing an updated version of the Connector for SAP BW. Microsoft does not own the 
source code for the SAP BW components, which were developed by a third party, and as a result cannot update them. 
Consider purchasing the latest SAP connectivity components from a Microsoft ISV partner such as Theobald Software. 


Microsoft's ISV partners have adapted their SAP connectivity components for SSIS for installation in Azure. 








IMPORTANT 


The documentation for the Microsoft Connector for SAP BW assumes familiarity with the SAP Netweaver BW 
environment. For more information about SAP Netweaver BW, or for information about how to configure SAP Netweaver 


BW objects and processes, see your SAP documentation. 


IMPORTANT 
Extracting data from SAP Netweaver BW requires additional SAP licensing. Check with SAP to verify these requirements. 











Required SAP Files 


To use the Microsoft Connector for SAP BW, you do not have to install the SAP Front End software (SAP GUI) on 
the local computer. 


However you must copy the SAP .NET connector file, librfc32.dll, into the system subfolder in the Windows 
folder. (Typically, this folder location is C:\Windows\system32.) 


Considerations for 64-bit Computers 


The Microsoft Connector for SAP BW fully supports the 64-bit version of Microsoft Windows. On a 64-bit 
computer, the Microsoft Connector for SAP BW has the following additional requirements: 


e Torun packages in 64-bit mode on any 64-bit Windows operating system, copy the 64-bit version of the 
SAP GUI file, librfc32.dll, into the system32 folder of the Windows folder. (Typically, this file location is 
C:\Windows\system32.) 


e Torun packages in 32-bit mode on any 64-bit Windows operating system, copy the SAP GUI file, 
librfc32.dll, into the SysWow64 folder of the Windows folder. (Typically, this folder location is 
C:\Windows\SysWow64.) 


Microsoft Connector for SAP BW Components 
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This section contains topics that describe the three components of the Microsoft Connector 1.1 for SAP BW: 
e SAP BW connection manager 

e SAP BW source 


e SAP BW destination 


IMPORTANT 


Microsoft does not anticipate providing an updated version of the Connector for SAP BW. Microsoft does not own the 
source code for the SAP BW components, which were developed by a third party, and as a result cannot update them. 
Consider purchasing the latest SAP connectivity components from a Microsoft ISV partner such as Theobald Software. 


Microsoft's ISV partners have adapted their SAP connectivity components for SSIS for installation in Azure. 


IMPORTANT 


The documentation for the Microsoft Connector 1.1 for SAP BW assumes familiarity with the SAP Netweaver BW 
environment. For more information about SAP Netweaver BW, or for information about how to configure SAP Netweaver 
BW objects and processes, see your SAP documentation. 











In This Section 


SAP BW Connection Manager 
Describes the SAP BW connection manager. The connection manager connects the SAP BW source or the SAP 
BW destination to an SAP Netweaver BW version 7 system. 


SAP BW Source 
Describes the SAP BW source that lets you extract data from an SAP Netweaver BW system. 


SAP BW Destination 
Describes the SAP BW destination that lets you load data into an SAP Netweaver BW system. 


Microsoft Connector for SAP BW F1 Help 
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This section contains the F1 Help topics for the three components of the Microsoft Connector 1.1 for SAP BW. 
These topics are also available from the user interface by pressing the F1 key, or by clicking Help on wizard 


pages and dialog boxes. 


IMPORTANT 


Microsoft does not anticipate providing an updated version of the Connector for SAP BW. Microsoft does not own the 
source code for the SAP BW components, which were developed by a third party, and as a result cannot update them. 
Consider purchasing the latest SAP connectivity components from a Microsoft ISV partner such as Theobald Software. 
Microsoft's ISV partners have adapted their SAP connectivity components for SSIS for installation in Azure. 











IMPORTANT 


The documentation for the Microsoft Connector 1.1 for SAP BW assumes familiarity with the SAP Netweaver BW 
environment. For more information about SAP Netweaver BW, or for information about how to configure SAP Netweaver 


BW objects and processes, see your SAP documentation. 


In This Section 


SAP BW Connection Manager F1 Help 


SAP BW Connection Manager Editor 


SAP BW Source F1 Help 


SAP BW Source Editor (Connection Manager Page) 
SAP BW Source Editor (Columns Page) 

SAP BW Source Editor (Error Output Page) 

SAP BW Source Editor (Advanced Page) 

Look Up RFC Destination 

Look Up Process Chain 

Request Log 


Preview 


SAP BW Destination F1 Help 


SAP BW Destination Editor (Connection Manager Page) 
SAP BW Destination Editor (Mappings Page) 
SAP BW Destination Editor (Error Output Page) 


SAP BW Destination Editor (Advanced Page) 





© Look Up InfoPackage 

e Create New InfoObject 

© Create InfoCube for Transaction Data 
e@ Look Up InfoObject 

@ Create InfoSource 

e@ Create InfoSource for Transaction Data 
@ Create InfoSource for Master Data 


e@ Create InfoPackage 


See Also 
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The Microsoft Connector 1.1 for SAP BW has received certification from SAP for integration with SAP 
NetWeaver. 


SAP" Certified 


Integration with SAP NetWeaver® 


The following table describes the details of the certification. 
SAP INTERFACE SAP RELEASE LEVELS CERTIFICATION DATE RELATED COMPONENT 


BW_OHS 7.0 - SAP Business Intelligence 7.0 December 2012 Source 
NetWeaver Business 

Intelligence - Open Hub 

Service 7.0 


BW-STA 3.5 - Staging BAPIs Business Intelligence 3.5, December 2012 Destination 
for SAP BW 3.5 7.0 


Integration Services Tutorials 
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This section contains tutorials Integration Services. 
e SSIS How to Create an ETL Package 


e Deploy Packages with SSIS 


SSIS How to Create an ETL Package 
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In this tutorial, you learn how to use SSIS Designer to create a simple Microsoft SQL Server Integration Services 
package. The package that you create takes data from a flat file, reformats the data, and then inserts the 
reformatted data into a fact table. In following lessons, the package is expanded to demonstrate looping, 
package configurations, logging, and error flow. 


When you install the sample data that the tutorial uses, you also install the completed versions of the packages 
that you create in each lesson of the tutorial. By using the completed packages, you can skip ahead and begin 
the tutorial at a later lesson if you like. If this tutorial is your first time working with packages or the new 
development environment, we recommend that you begin with Lesson1. 


What is SQL Server Integration Services (SSIS)? 


MicrosoftSQL Server Integration Services (SSIS) is a platform for building high-performance data integration 
solutions, including extraction, transformation, and load (ETL) packages for data warehousing. SSIS includes 
graphical tools and wizards for building and debugging packages; tasks for performing workflow functions such 
as FTP operations, executing SQL statements, and sending e-mail messages; data sources and destinations for 
extracting and loading data; transformations for cleaning, aggregating, merging, and copying data; a 
management database, ssispB , for administering package execution and storage; and application 
programming interfaces (APIs) for programming the Integration Services object model. 


What You Learn 


The best way to become acquainted with the new tools, controls, and features available in Microsoft SQL Server 
Integration Services is to use them. This tutorial walks you through SSIS Designer to create a simple ETL 
package that includes looping, configurations, error flow logic, and logging. 


Prerequisites 


This tutorial is intended for users familiar with fundamental database operations, but who have limited exposure 
to the new features available in SQL Server Integration Services. 


To run this tutorial, you have to have the following components installed: 
e SQL Server and Integration Services. To install SQL Server and SSIS, see Install Integration Services. 


e The AdventureWorksDW2012 sample database. To download the AdventureWorksDW2012 
database, download AdventureWorksDW2012.bak from AdventureWorks sample databases and restore the 
backup. 


e Thesample data files. The sample data is included with the SSIS lesson packages. To download the 
sample data and the lesson packages as a Zip file, see SQL Server Integration Services Tutorial Files. 


° Most of the files in the Zip file are read-only to prevent unintended changes. To write output to a file or 
to change it, you may have to turn off the read-only attribute in the file properties. 


o The sample packages assume that the data files are located in the folder 


C:\Program Files\Microsoft SQL Server\100\Samples\Integration Services\Tutorial\Creating a Simple 
ETL Package 


. If you unzip the download to another location, you may have to update the file path in multiple 
places in the sample packages. 


Lessons in This Tutorial 


Lesson 1: Create a Project and Basic Package with SSIS 
In this lesson, you create a simple ETL package that extracts data from a single flat file, transforms the data using 
lookup transformations and finally loads the result into a fact table destination. 


Lesson 2: Adding Looping with SSIS 
In this lesson, you expand the package you created in Lesson 1 to take advantage of new looping features to 
extract multiple flat files into a single data flow process. 


Lesson 3: Add Logging with SSIS 
In this lesson, you expand the package you created in Lesson 2 to take advantage of new logging features. 


Lesson 4: Add Error Flow Redirection with SSIS 
In this lesson, you expand the package you created in lesson 3 to take advantage of new error output 
configurations. 


Lesson 5: Add SSIS Package Configurations for the Package Deployment Model 
In this lesson, you expand the package you created in Lesson 4 to take advantage of new package configuration 
options. 


Lesson 6: Using Parameters with the Project Deployment Model in SSIS 
In this lesson, you expand the package you created in Lesson 5 to take advantage of using new parameters with 
the project deployment model. 


Lesson 1: Create a project and basic package with 


SSIS 
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In this lesson, you create a simple ETL package that extracts data from a single flat file source, transforms the 
data using two lookup transformations, and writes the transformed data to a copy of the FactCurrencyRate 
fact table in the AdventureWorksDW2012 sample database. As part of this lesson, you learn how to create 
new packages, add and configure data source and destination connections, and work with new control flow and 
data flow components. 


Before creating a package, you need to understand the formatting used in both the source data and the 
destination. Then, you be ready to define the transformations necessary to map the source data to the 
destination. 


Prerequisites 
This tutorial relies on Microsoft SQL Server Data Tools, a set of example packages, and a sample database. 
e To install the SQL Server Data Tools, see Download SQL Server Data Tools. 
e@ To download all of the lesson packages for this tutorial: 
1. Navigate to Integration Services tutorial files. 
2. Select the DOWNLOAD button. 
3. Select the Creating a Simple ETL Package.zip file, then select Next. 
4. After the file downloads, unzip its contents to a local directory. 


e To install and deploy the AdventureWorksDW2012 sample database, see Install and configure 
AdventureWorks sample database - SQL. 


Look at the source data 


For this tutorial, the source data is a set of historical currency data in a flat file named 
SampleCurrencyData.txt. The source data has the following four columns: the average rate of the currency, a 
currency key, a date key, and the end-of-day rate. 


Here is an example of the source data in the SampleCurrencyData.txt file: 


1.00070049USD9/3/@5 0:001.001201442 
1.00020004USD9/4/@5 0:001 
1.00020004USD9/5/@5 0:001.001201442 
1.00020004USD9/6/@5 0:001 
1.00020004USD9/7/85 0:001.00070049 
1.00070049USD9/8/85 0:000.99980004 
1.0@0070049USD9/9/@5 0:001.001502253 
1.0@0070049USD9/10/05 @:000.99990001 
1.00020004USD9/11/05 @:001.001101211 
1.@0020004USD9/12/05 @:000.99970009 


When working with flat file source data, it's important to understand how the Flat File connection manager 
interprets the flat file data. If the flat file source is Unicode, the Flat File connection manager defines all columns 
as [DT_WSTR] with a default column width of 50. If the flat file source is ANSI-encoded, the columns are defined 
as [DT_STR] with a default column width of 50. You probably have to change these defaults to make the string 
column types more applicable for your data. You need to look at the data type of the destination, and then 
choose that type within the Flat File connection manager. 


Look at the destination data 


The destination for the source data is a copy of the FactCurrencyRate fact table in AdventureWorksDW. The 
FactCurrencyRate fact table has four columns, and has relationships to two dimension tables, as shown in the 
following table. 


COLUMN NAME DATA TYPE LOOKUP TABLE LOOKUP COLUMN 
AverageRate float None None 
CurrencyKey int (FK) DimCurrency CurrencyKey (PK) 
DateKey int (FK) DimDate DateKey (PK) 
EndOfDayRate float None None 


Map the source data to the destination 


Our analysis of the source and destination data formats indicates that lookups are necessary for the 
CurrencyKey and DateKey values. The transformations that perform these lookups get those values by using 
the alternate keys from the DimCurrency and DimDate dimension tables. 


FLAT FILE COLUMN TABLE NAME COLUMN NAME DATA TYPE 
0 FactCurrencyRate AverageRate float 

1 DimCurrency CurrencyAlternateKey nchar (3) 

2 DimDate FullDateAlternateKey date 

3 FactCurrencyRate EndOfDayRate float 


Lesson tasks 


This lesson contains the following tasks: 

e Step 1: Create a new Integration Services project 

e Step 2: Add and configure a Flat File connection manager 
@ Step 3: Add and configure an OLE DB connection manager 
e Step 4: Add a Data Flow task to the package 

@ Step 5: Add and configure the flat file source 


e Step 6: Add and configure the lookup transformations 


e Step 7: Add and configure the OLE DB destination 
e Step 8: Annotate and format the Lesson 1 package 


e Step 9: Test the Lesson 1 package 


Start the lesson 


Step 1: Create a new integration services project 


Lesson 1-1: Create a new Integration Services 
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The first step in creating a package in Integration Services is to create an Integration Services project. This 
example project includes templates for the data sources, data source views, and packages that make up a data 
transformation solution. 


The packages that you create in this Integration Services tutorial interpret the values of locale-sensitive data. If 
your computer isn't configured to use the regional option English (United States), you need to set additional 
properties in the package. 


The packages that you use in lessons 2 through 6 are copied from the package you create in this lesson. 





NOTE 


If you haven't already, see the Lesson 1 prerequisites. 





Create a new Integration Services project 
1. On the Windows Start menu, search for and select Visual Studio (SSDT). 
2. In Visual Studio, select File > New > Project to create a new Integration Services project. 


3. In the New Project dialog box, expand the Business Intelligence node under Installed, and select 
Integration Services Project in the Templates pane. 


4. In the Name box, change the default name to SSIS Tutorial. To use a folder that already exists, clear the 
Create directory for solution check box. 


5. Accept the default location, or select Browse to browse to locate the folder you want to use. In the 
Project Location dialog box, select the folder and then Select Folder. 


6. Select OK. 


By default, an empty package titled Package.dtsx is created and added to your project under SSIS 
Packages. 


7. InSolution Explorer, right-click Package.dtsx, select Rename, and rename the default package to 


Lesson 1.dtsx. 


Go to next task 


Step 2: Add and configure a Flat File connection manager 


Lesson 1-2: Add and configure a Flat File connection 


manager 
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In this task, you add a Flat File connection manager to the package that you just created. A Flat File connection 
manager enables a package to extract data from a flat file. Using the Flat File connection manager, you can 
specify the file name and location, the locale and code page, and the file format, including column delimiters, to 
apply when the package extracts data from the flat file. In addition, you can manually specify the data type for 
the individual columns, or use the Suggest Column Types dialog box to automatically map the columns of 
extracted data to Integration Services data types. 


You must create a new Flat File connection manager for each file format you're working with. Because this 
tutorial extracts data from multiple flat files that all have the same data format, you only need to add and 
configure one Flat File connection manager for the example package. 


In this lesson, you configure the following properties in your Flat File connection manager: 


e Column names: Since the flat file does not have column names, the Flat File connection manager 
creates default column names. These default names are not useful for identifying what each column 
represents. Change the default names to names that match the fact table into which the flat file data is to 
be loaded. 


e Data mappings: The data type mappings that you specify for the Flat File connection manager are used 
by all flat file data source components that reference this connection manager. You can either manually 
map the data types by using the Flat File connection manager, or you can use the Suggest Column 
Types dialog box. In this task, you view the mappings suggested in the Suggest Column Types dialog 
box and then manually create the necessary mappings in the Flat File Connection Manager Editor 
dialog box. 





NOTE 

The Flat File connection manager provides locale information about the data file. If your computer is not configured to use 
the regional option English (United States), you must set additional properties in the Flat File Connection 
Manager Editor dialog box. 





Add a Flat File connection manager to the SSIS package 


1. In the Solution Explorer pane, right-click on Connection Managers and select New Connection 
Manager. 


2. In the Add SSIS Connection Manager dialog, select FLATFILE, then Add. 


3. In the Flat File Connection Manager Editor dialog box, for Connection manager name, enter 
Sample Flat File Source Data. 


4. Select Browse. 
5. In the Open dialog box, locate the SampleCurrencyData.txt file on your computer. 


6. Clear the Column names in the first data row checkbox. 





Set locale-sensitive properties 


1. In the Flat File Connection Manager Editor dialog box, select General. 
2. Set Locale to English (United States) and Code page to 1252. 


Rename columns in the Flat File connection manager 


1. In the Flat File Connection Manager Editor dialog box, select Advanced. 
2. In the property pane, make the following changes: 

e Change the Column 0 name property to AverageRate. 

e Change the Column 1 name property to CurrencylD. 

e Change the Column 2 name property to CurrencyDate. 

e Change the Column 3 name property to EndOfDayRate. 


Remap column data types 


By default, all four of the columns are initially set to a string data type [DT_STR] with an OutputColumnWidth 
of 50. 


1. In the Flat File Connection Manager Editor dialog box, select Suggest Types. 


Integration Services automatically suggests appropriate data types based on the first 200 rows of data. 
You can also change these suggestion options to sample more or less data, to specify the default data 


type for integer or Boolean data, or to add spaces as padding to string columns. 


For now, make no changes to the options in the Suggest Column Types dialog box, and select OK to 
have Integration Services suggest data types for columns. This action returns you to the Advanced pane 
of the Flat File Connection Manager Editor dialog box, where you can view the column data types 
suggested by Integration Services. Alternately, if you select Cancel, no suggestions are made to column 
metadata and the default string (DT_STR) data type is used. 


In this tutorial, Integration Services suggests the data types shown in the second column of the following 
table for the data from the SampleCurrencyData.txt file. The fourth column provides the data types 


required for the columns in the destination, which are defined in a subsequent step. 


FLAT FILE COLUMN SUGGESTED TYPE DESTINATION COLUMN DESTINATION TYPE 
AverageRate float [DT_R4] FactCurrencyRate.Average float 
Rate 
Currency|D string [DT_STR] DimCurrency.CurrencyAlt nchar(3) 
ernateKey 
CurrencyDate date [DT_DATE] DimDate.FullDateAlternat date 
eKey 
EndOfDayRate float [DT_R4] FactCurrencyRate.EndOfD float 
ayRate 


The data type suggested for the CurrencyID column is incompatible with the data type of the field in the 
destination table. Because the data type of Dimcurrency.CurrencyAlternateKey is nchar(3), CurrencyID 
must be changed from string [DT_STR] to Unicode string [DT_WSTR]. In addition, the field 
DimDate.FullDateAlternateKey is defined as a date data type, so the type for CurrencyDate needs to be 
changed from date [DT_Date] to database date [DT_DBDATE]. 


2. In the list, select the CurrencyID column and in the property pane, change the Data Type of column 
CurrencylD from string [DT_STR] to Unicode string [DT_WSTR]. 


3. In the property pane, change the data type of column CurrencyDate from date [DT_DATE] to database 
date [DT_DBDATE]. 


4. Select OK. 


Go to next task 


Step 3: Add and configure an OLE DB connection manager 


See also 


Flat File connection manager 


Integration Services data types 


Lesson 1-3: Add and configure an OLE DB 
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After you add a Flat File connection manager to connect to the data source, you add an OLE DB connection 
manager to connect to the data destination. An OLE DB connection manager enables a package to extract data 
from or load data into any OLE DB-compliant data source. Using an OLE DB connection manager, you can 
specify the server, the authentication method, and the default database for the connection. 


In this task, you create an OLE DB connection manager that uses Windows Authentication to connect to the local 
instance of AdventureWorksDW2012. This OLE DB connection manager is also referenced by other 
components that you create later in this tutorial, such as the Lookup transformation and the OLE DB destination. 


Add and configure an OLE DB connection manager 


1. In the Solution Explorer pane, right-click on Connection Managers and select New Connection 
Manager. 


2. In the Add SSIS Connection Manager dialog, select OLEDB, then select Add. 
3. In the Configure OLE DB Connection Manager dialog box, select New. 
4. For Server name, enter localhost. 


When you specify localhost as the server name, the connection manager connects to the default instance 
of SQL Server on the local computer. To use a remote instance of SQL Server, replace localhost with the 
name of the server to which you want to connect. 


5. In the Log on to the server group, verify that Use Windows Authentication is selected. 


6. In the Connect to a database group, in the Select or enter a database name box, type or select 
AdventureWorksDW2012. 


7. Select Test Connection to verify that the connection settings you have specified are valid. 
8. Select OK. 
9. Select OK. 


10. In the Connection Managers pane, verify that localhost.AdventureWorksDW2012 is selected. 


Go to next task 


Step 4: Add a Data Flow task to the package 


See also 


OLE DB connection manager 


Lesson 1-4: Add a Data Flow task to the package 
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After you've created the connection managers for the source and destination data, you add a Data Flow task to 
your package. The Data Flow task defines the data flow engine that moves data between sources and 
destinations, and provides the functionality for transforming, cleaning, and modifying data as it is moved. The 
Data Flow task is where most of the work of an extract, transform, and load (ETL) process occurs. 





NOTE 


SQL Serverlntegration Services separates data flow from control flow. 











Add a Data Flow task 


1. Select the Control Flow tab. 


2. Inthe SSIS Toolbox pane, expand Favorites, and drag a Data Flow Task onto the design surface of the 
Control Flow tab. 





NOTE 


If the SSIS Toolbox isn't available, select the SSIS menu, and then select SSIS Toolbox to display it. 





3. On the Control Flow design surface, right-click the new Data Flow Task, select Rename, and change 
the name to Extract Sample Currency Data. 


Provide unique names for all components that you add to a design surface. For ease of use and 
maintainability, the names should describe the function of each component. Following these naming 
guidelines allows your Integration Services packages to be self-documenting. Another way to document 
your packages is by using annotations. For more information about annotations, see Use annotations in 
packages. 


4. Right-click the Data Flow task, select Properties, and in the Properties window, verify that the LocalelD 


property is set to English (United States). 


Go to next task 


Step 5: Add and configure the Flat File source 


See also 


Data Flow task 


Lesson 1-5: Add and configure the Flat File source 


11/23/2021 * 2 minutes to read « Edit Online 





Applies to: Q@ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


In this task, you add and configure a Flat File source to your package. A Flat File source is a data flow component 
that uses metadata defined by a Flat File connection manager. This metadata specifies the format and structure 
of the data to be extracted from the flat file by a transform process. The Flat File source extracts data from a 
single flat file, using the format definitions in the Flat File connection manager. 


For this task, you configure the Flat File source to use the Sample Flat File Source Data connection manager 
that you previously created. 


Add a Flat File source component 


1. To open the Data Flow designer, either double-click on the Extract Sample Currency Data data flow 
task, or select the Data Flow tab. 


2. Inthe SSIS Toolbox, expand OtherSources, and then drag a Flat File Source onto the design surface 
of the Data Flow tab. 


3. On the Data Flow design surface, right-click the newly added Flat File Source, select Rename, and 
change the name to Extract Sample Currency Data. 


4. Double-click the Flat File source to open the Flat File Source Editor dialog. 

5. In the Flat file connection manager field, select Sample Flat File Source Data. 
6. Select Columns and verify that the names of the columns are correct. 

7. Select OK. 

8. Right-click the Flat File source and select Properties. 


9. In the Properties window, verify that the LocalelD property is set to English (United States). 


Go to next task 


Step 6: Add and configure the Lookup transformations 


See also 


Flat File source 
Flat File Connection Manager 
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After you have configured the Flat File source to extract data from the source file, you define the Lookup 
transformations needed to obtain the values for CurrencyKey and DateKey. A Lookup transformation 
performs a lookup by joining data in the specified input column to a column in a reference dataset. The 
reference dataset can be an existing table or view, a new table, or the result of an SQL statement. In this tutorial, 
the Lookup transformation uses an OLE DB connection manager to connect to the database that contains the 
source data of the reference dataset. 





NOTE 


You can also configure the Lookup transformation to connect to a cache that contains the reference dataset. For more 
information, see Lookup transformation. 











In this task, you add and configure the following two Lookup transformation components to the package: 


e One transformation that does a lookup of values from the CurrencyKey column of the DimCurrency 
dimension table, based on matching CurrencyID column values from the flat file. 


e One transformation that does a lookup of values from the DateKey column of the DimDate dimension 
table, based on matching CurrencyDate column values from the flat file. 


In both cases, the Lookup transformation uses the OLE DB connection manager you previously created. 


Add and configure the Lookup Currency Key transformation 


1. Inthe SSIS Toolbox, expand Common, and then drag Lookup onto the design surface of the Data 
Flow tab. Place Lookup directly below the Extract Sample Currency Data source. 


2. Select the Extract Sample Currency Data flat file source and drag its blue arrow onto the newly added 
Lookup transformation to connect the two components. 


3. On the Data Flow design surface, select Lookup in the Lookup transformation, and change the name to 
Lookup Currency Key. 


4. Double-click the Lookup Currency Key transformation to display the Lookup Transformation 
Editor. 


5. On the General page, make the following selections: 

a. Select Full cache. 

b. In the Connection type area, select OLE DB connection manager. 
6. On the Connection page, make the following selections: 


a. In the OLE DB connection manager dialog box, ensure that 
localhost.AdventureWorksDW2012 is displayed. 


b. Select Use results of an SQL query, and then enter or paste the following SQL statement: 


SELECT * FROM [dbo].[DimCurrency] 
WHERE [CurrencyAlternateKey ] 
IN (‘ARS', ‘AUD', ‘BRL', ‘CAD', ‘CNY’, 
'DEM', 'EUR', 'FRF', 'GBP', ‘JPY’, 
'MXN', ‘SAR’, 'USD', 'VEB') 
c. Select Preview to verify the query results. 


7. On the Columns page, make the following selections: 


a. In the Available Input Columns panel, drag CurrencyID to the Available Lookup Columns 
panel and drop it on CurrencyAlternateKey. 


b. In the Available Lookup Columns list, select the check box to the left of CurrencyKey. 
8. Select OK to return to the Data Flow design surface. 
9. Right-click the Lookup Currency Key transformation and select Properties. 


10. In the Properties window, verify that the LocalelD property is English (United States) and the 
DefaultCodePage property is 1252. 


Add and configure the Lookup Date Key transformation 


1. Inthe SSIS Toolbox, drag Lookup onto the Data Flow design surface. Place this Lookup directly below 
the Lookup Currency Key transformation. 


2. Select the Lookup Currency Key transformation and drag its blue arrow onto the new Lookup 
transformation to connect the two components. 


3. In the Input Output Selection dialog, select Lookup Match Output in the Output list box, and then 
select OK. 


4. On the Data Flow design surface, select the name Lookup in the newly added Lookup transformation 
and change that name to Lookup Date Key. 


5. Double-click the Lookup Date Key transformation. 
6. On the General page, select Partial cache. 
7. On the Connection page, make the following selections: 


a. In the OLEDB connection manager dialog, ensure that localhost.AdventureWorksDW2012 
is displayed. 


b. In the Use a table or view box, enter or select [dbo].[DimDate]. 
8. On the Columns page, make the following selections: 


a. In the Available Input Columns panel, drag CurrencyDate to the Available Lookup 
Columns panel and drop it on FullDateAlternateKey. If you see a message indicating a data 
type mismatch, change the data type of CurrencyDate to [DT_DBDATE]. 


b. In the Available Lookup Columns list, select the check box to the left of DateKey. 
9. On the Advanced page, review the caching options. 


10. Select OK to return to the Data Flow design surface. 


11. Right-click the Lookup Date Key transformation and select Properties. 
12. In the Properties window, verify that the LocalelD property is English (United States) and the 


DefaultCodePage property is 1252. 


Go to next task 


Step 7: Add and configure the OLE DB destination 


See also 


Lookup transformation 


Lesson 1-7: Add and configure the OLE DB 
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Your package can now extract data from the flat file source and transform that data into a format compatible 
with the destination. The next task is to load the transformed data into the destination. To load the data, you add 
an OLE DB destination to the data flow. The OLE DB destination can use a database table, view, or a SQL 
command to load data into a variety of OLE DB-compliant databases. 


In this task, you add and configure an OLE DB destination to use the OLE DB connection manager that you 
previously created. 


Add and configure the sample OLE DB destination 


1. Inthe SSIS Toolbox, expand Other Destinations, and drag OLE DB Destination onto the design 
surface of the Data Flow tab. Place the OLE DB Destination directly below the Lookup Date Key 
transformation. 


2. Select the Lookup Date Key transformation and drag its blue arrow over to the new OLE DB 
Destination to connect the two components together. 


3. Inthe Input Output Selection dialog, in the Output list box, select Lookup Match Output, and then 
select OK. 


4. On the Data Flow design surface, select the name OLE DB Destination in the new OLE DB 
Destination component, and change that name to Sample OLE DB Destination. 


5. Double-click Sample OLE DB Destination. 


6. Inthe OLE DB Destination Editor dialog, ensure that localhost.AdventureWorksDW2012 is 
selected in the OLE DB Connection manager box. 


7. Inthe Name of the table or the view box, enter or select [dbo].[FactCurrencyRate]. 


8. If a table named NewFactCurrencyRate currently exists, delete it now. You will create the table in the 
next step. 


9. Select the New button to create a new table. Change the name of the table in the script from Sample 
OLE DB Destination to NewFactCurrencyRate. Select OK. 


10. Upon selecting OK, the dialog closes and the Name of the table or the view automatically changes to 
NewFactCurrencyRate. 


11. Select Mappings. 


12. Verify that the AverageRate, CurrencyKey, EndOfDayRate, and DateKey input columns are mapped 
correctly to the destination columns. If same-named columns are mapped, the mapping is correct. 


13. Select OK. 
14. Right-click the Sample OLE DB Destination destination and select Properties. 


15. In the Properties window, verify that the LocalelD property is set to English (United States) and the 


DefaultCodePage property is set to 1252. 


Go to next task 


Step 8: Annotate and format the Lesson 1 package 


See also 


OLE DB destination 
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Now that you've completed the configuration of the Lesson 1 package, it's probably time to tidy up the package 
layout. If the shapes in the control and data flow layouts are different sizes, or not laid out evenly, the package 
may be more difficult to understand. 


SQL Server Data Tools provides tools to easily format the package layout. The formatting features include the 
ability to make shapes the same size, align shapes, and change the horizontal and vertical spacing between 
shapes. 


Another way to improve the understanding of package functionality is to add annotations that describe package 
functionality. 


In this task, you use the formatting features in SQL Server Data Tools to improve the layout of the data flow and 
also to add an annotation. 


Format the layout of the data flow 

1. If the Lesson 1 package isn't already open, double-click Lesson 1.dtsx in Solution Explorer. 
2. Select the Data Flow tab. 

3. To select all the data flow components at once, use Edit > Select All. 

4. On the Format menu, select Make Same Size, and then select Both. 

5. With the data flow objects selected, on the Format menu, select Align, and then select Centers. 


6. With the data flow objects selected, on the Format menu, point to Vertical Spacing, and then select 
Make Equal. 


Add an annotation to the data flow 
1. Right-click anywhere in the background of the data flow design surface and then select Add Annotation. 
2. Enter or paste the following text in the annotation box. 


The data flow extracts data from a file, looks up values in the CurrencyKey column in the DimCurrency 
table and the DateKey column in the DimDate table, and writes the data to the NewFactCurrencyRate 
table. 


To wrap the text in the annotation box, place the cursor where you want to start a new line and press 
Enter. 


If you don't add text to the annotation box, the box disappears when you click outside it. Because of this 
behavior, if you want to paste text in the annotation box then copy the text to the clipboard before 
selecting Add Annotation. 


Go to next task 


Step 9: Test the Lesson 1 package 


Lesson 1-9: Test the Lesson 1 package 
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In this tutorial, you've done the following tasks: 

e Created a new SSIS project. 

e Configured the connection managers for the package to connect to the source and destination data. 


e Added a data flow that takes the data from a flat file source, performs the necessary Lookup 
transformations on the data, and configures the data for the destination. 


Your package is now complete and ready to test! 


Check the package components 


Before you test the package, verify that the control and data flows in the Lesson 1 package contain the objects 
shown in the following diagrams. 


Control Flow 


we Extract Sample Currency Data 


Data Flow 


B, Extract Sample Currency Data 


(BE sample OLE DB Destination 


Run the Lesson 1 package 


1. On the Debug menu, select Start Debugging. 


The package runs, resulting in 1,097 rows successfully added into the NewFactCurrencyRate fact table 
in AdventureWorksDW2012. To verify this result, select the Data Flow tab. 


2. After the package has completed running, on the Debug menu, select Stop Debugging. 


Go to next lesson 


Lesson 2: Add looping with SSIS 


See also 


Execution of projects and packages 
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In Lesson 1: Create a project and basic package with SSIS, you created a package that extracts data from a single 
flat file source. The data is then transformed using Lookup transformations. Finally, the package loads the data 
into a copy of the FactCurrencyRate fact table in the AdventureWorksDW2012 sample database. 


An extract, transform, and load (ETL) process typically extracts data from multiple flat file sources. Extracting data 
from multiple sources requires an iterative control flow. Microsoft Integration Services can easily add iteration 
or looping to packages. 


Integration Services provides two types of containers for looping through packages: the Foreach Loop container 
and the For Loop container. The Foreach Loop container uses an enumerator for the looping, while the For Loop 
container typically uses a variable expression. This lesson uses the Foreach Loop container. 


The Foreach Loop container enables a package to repeat the control flow for each member of a specified 
enumerator. With the Foreach Loop container, you can enumerate: 


e ADO recordset rows 

e ADO .Net schema information 

e File and directory structures 

e@ System, package, and user variables 

e@ Enumerable objects in a variable 

e Items ina collection 

e Nodes in an XML Path Language (XPath) expression 


e SQL Server Management Objects (SMO) 


In this lesson, you modify Lesson 1's example ETL package to use a Foreach Loop container, and set a user- 
defined package variable for the package. That variable is then used to iterate through the matching files in the 
sample folder. 


In this lesson, you won't modify the data flow, only the control flow. 





NOTE 


If you haven't already, see the Lesson 1 prerequisites. 





Lesson tasks 


This lesson contains the following tasks: 
e Step 1: Copy the Lesson 1 package 
e Step 2: Add and configure the Foreach Loop container 


e Step 3: Modify the Flat File connection manager 


e Step 4: Test the Lesson 2 tutorial package 


Start the lesson 


Step 1: Copy the Lesson 1 package 


See also 


For Loop container 


Lesson 2-1: Copy the Lesson 1 package 
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In this task, you create a copy of the Lesson 1.dtsx package. If you didn't complete Lesson 1, you can use the 
completed lesson 1 package that is included with this tutorial. You use the new copy throughout the rest of 
Lesson 2. 


Create the Lesson 2 package 
Use this procedure if you're copying the completed Lesson 1. To copy the sample Lesson 1, see the next section. 


1. If SQL Server Data Tools isn't already open, select Start > All Programs > Microsoft SQL Server 
2017, and then select SQL Server Data Tools. 


2. On the File menu, select Open > Project/Solution, select the SSIS Tutorial folder and select Open, 
and then double-click SSIS Tutorial.sIn. 


3. In Solution Explorer, right-click Lesson 1.dtsx, and then select Copy. 
4. In Solution Explorer, right-click SSIS Packages, and then select Paste. 
By default, the copied package is named Lesson 2.dtsx. 
5. In Solution Explorer, double-click Lesson 2.dtsx to open the package 
6. Right-click anywhere in the background of the Control Flow design surface and select Properties. 
7. In the Properties window, change the Name property to Lesson 2. 


8. Select the box for the ID property, select the drop-down arrow, and then select <Generate New ID>. 


Use the sample Lesson 1 package 


1. Open SQL Server Data Tools and open the SSIS Tutorial project. 

2. InSolution Explorer, right-click SSIS Packages and select Add Existing Package. 

3. In the Add Copy of Existing Package dialog, in Package location, select File system. 

4. Select the browse (...) button, navigate to Lesson 1.dtsx on your computer, and then select Open. 


5. Copy and paste the Lesson 1 package as described in steps 3-8 in the previous section. 


Go to next task 


Step 2: Add and configure the Foreach Loop container 


Lesson 2-2: Add and configure the Foreach Loop 
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In this task, you add the ability to loop through a folder of flat files and apply Lesson 1's data flow 
transformation to each of those flat files. You do this by adding and configuring a Foreach Loop container to the 
control flow. 


The Foreach Loop container that you add must be able to connect to each flat file in the folder. Because all the 
files in the folder have the same format, the Foreach Loop container can use the same Flat File connection 
manager to connect to each of these files. The Flat File connection manager that the container uses is the one 
you created in Lesson 1. 


Currently, the Flat File connection manager from Lesson 1 connects to only one specific flat file. To iteratively 
connect to each flat file in the folder, you have to configure both the Foreach Loop container and the Flat File 
connection manager as follows: 


e Foreach Loop container: You map the enumerated value of the container to a user-defined package 
variable. The container then uses this variable to dynamically modify the ConnectionString property of 
the Flat File connection manager and iteratively connect to each flat file in the folder. 


e Flat File connection manager: You modify the connection manager that was created in Lesson 1 by 
using a user-defined variable to populate the connection manager's ConnectionString property. 


The procedures in this task show you how to create and modify the Foreach Loop container to use a user- 
defined package variable, and to add the data flow task into the loop. You'll learn how to modify the Flat File 
connection manager to use that user-defined variable in the next task. 


After you have made these modifications to the package, when the package is run, the Foreach Loop Container 
iterates through all files in the Sample Data folder. Each time a file is found that matches the criterion, the 
Foreach Loop Container populates the new variable with the file name, maps that variable to the 
ConnectionString property of the Sample Currency Data Flat File connection manager, and then runs the data 
flow against that file. In this way, each iteration of the Foreach Loop the Data Flow task consumes a different flat 
file. 





NOTE 


Because MicrosoftIntegration Services separates control flow from data flow, any looping that you add to the control flow 
won't require modification to the data flow. Therefore, the Lesson 1 data flow does not have to be changed. 











Add a Foreach Loop container 


1. InSQL Server Data Tools, select the Control Flow tab. 


2. Inthe SSIS Toolbox, expand Containers, and then drag a Foreach Loop Container onto the design 
surface of the Control Flow tab. 


3. Right-click the new Foreach Loop Container and select Edit. 


4. In the Foreach Loop Editor dialog, on the General page, for Name, enter Foreach File in Folder. 


I 


Select OK. 


. Right-click the Foreach Loop container, select Properties, and in the Properties window verify that the 
LocalelD property is set to English (United States). 


Configure the enumerator for the Foreach Loop container 


1 


2: 


3. 


. Double-click Foreach File in Folder to reopen the Foreach Loop Editor. 
Select Collection. 

On the Collection page, select Foreach File Enumerator. 

. Inthe Enumerator configuration group, select Browse. 


. In the Browse for Folder dialog box, locate the folder on your machine that contains the Currency_*.txt 
files included with the sample data. 


. Inthe Files box, enter Currency_*.txt. 


Map the enumerator to a user-defined variable 


ile 


2: 


5 


Select Variable Mappings. 


On the Variable Mappings page, in the Variable column, select the empty cell and select <New 
Variable...>. 


. Inthe Add Variable dialog box, for Name enter varFileName. 





NOTE 


Variable names are case-sensitive. 





. Select OK. 


. Select OK again to exit the Foreach Loop Editor dialog. 


Add the data flow task to the loop 


e Drag the Extract Sample Currency Data data flow task onto the Foreach File in Folder Foreach Loop 


container. 


Go to next task 


Step 3: Modify the Flat File connection manager 


See also 


Configure a Foreach Loop container 


U 


se variables in packages 


Lesson 2-3: Modify the Flat File connection 


manager 
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In this task, you modify the Flat File connection manager from Lesson 1. That Flat File connection manager is 

configured to statically load a single file. To enable the Flat File connection manager to iteratively load files, you 

change the ConnectionString property of the connection manager to use the user-defined variable 
User::varFileName , which contains the path of the file to be loaded at run time. 


By modifying the connection manager to use the value of the user-defined variable to change the 
ConnectionString property, the connection manager connects to different flat files. At run time, each iteration of 
the Foreach Loop container updates the User::varFileName variable. Updating the variable, in turn, causes the 
connection manager to connect to a different flat file, and the data flow task to process a different set of data. 


Configure the Flat File connection manager to use a variable 
1. In the Connection Managers pane, right-click Sample Flat File Source Data, and select Properties. 


2. In the Properties window make sure the PackagePath starts with \Package.Connections. If not, in the 
Connection Managers pane, right-click Sample Flat File Source Data, and select Convert to 
Package Connection 


3. In the Properties window, for Expressions, select the empty cell, and then select the ellipsis button (...). 
4. In the Property Expressions Editor dialog, in the Property column, select ConnectionString. 

5. In the Expression column, select the ellipsis button (...) to open the Expression Builder dialog box. 

6. In the Expression Builder dialog, expand the Variables node. 

7. Drag the variable User::varFileName into the Expression box. 

8. Select OK to close the Expression Builder dialog. 


9. Select OK again to close the Property Expressions Editor dialog. 


Go to next task 


Step 4: Test the Lesson 2 tutorial package 


Lesson 2-4: Test the Lesson 2 tutorial package 
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With the Foreach Loop container and the Flat File connection manager now configured, the Lesson 2 package 
can iterate through the 14 flat files in the Sample Data folder. Each time a file name matches the specified 
criterion, the Foreach Loop container populates the user-defined variable with the file name. This variable, in 
turn, updates the ConnectionString property of the Flat File connection manager, which connects to that flat file. 
The Foreach Loop container then runs the unmodified data flow task against the data in that flat file. 


NOTE 

If you ran the package from Lesson 1, you need to delete the records from the dbo.NewFactCurrencyRate table in the 
AdventureWorksDW2012 database before you run the package from this lesson. Lesson 2 attempts to insert records 
already inserted in Lesson 1, which causes an error. 





Check the package layout 


Before you test the package, verify that the control and data flows in the Lesson 2 package contains the objects 
shown in the following diagrams. Lesson 2's data flow is the same as Lesson 1. 


Control Flow 


A Foreach File in Folder ~ 


we Extract Sample Currency Data 


Data Flow 


BR, Extract Sample Currency Data 


BE sample OLE De Destination 


Test the Lesson 2 tutorial package 





1. In Solution Explorer, right-click Lesson 2.dtsx and select Execute Package. 


The package runs. You can verify the status of each loop in the Output window, or by selecting the 
Progress tab. For example, you can see that 1,097 rows were added to the destination table from the file 


Currency_VEB.txt. 


2. After the package has completed running, on the Debug menu, select Stop Debugging. 


Go to next lesson 


Lesson 3: Add logging with SSIS 


See also 


Execution of projects and packages 


Lesson 3: Add logging with SSIS 
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Microsoft Integration Services includes logging features that let you troubleshoot and monitor package 
execution by providing a trace of task and container events. The logging features are flexible. You can enable 
logging at the package level, or on individual tasks or containers within the package. You select which events 
you want to log, and create multiple logs against a single package. 


Log providers create the logs. Each log provider can write logging information to different formats and 
destination types. Integration Services provides the following log providers: 


e Text file 

e@ SQL Server Profiler 
e Windows Event log 
e SQL Server 


e XML file 


In this lesson, you create a copy of the package that you created in Lesson 2: Add Looping with SSIS. Working 
with this new package, you then add and configure logging to monitor specific events during package execution. 
If you haven't completed either of the previous lessons, you can also copy the completed Lesson 2 package 
included with the tutorial. 





NOTE 


If you haven't already, see the Lesson 1 prerequisites. 





Lesson tasks 

This lesson contains the following tasks: 
e Step 1: Copy the Lesson 2 package 

e Step 2: Add and configure logging 


e Step 3: Test the Lesson 3 package 


Start the lesson 


Step 1: Copy the Lesson 2 package 


Lesson 3-1: Copy the Lesson 2 package 
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In this task, you create a copy of the Lesson 2.dtsx package from Lesson 2. If you didn't complete Lesson 2, you 
can add the completed lesson 2 package included with this tutorial to the project, and then copy it instead. You 
use this new copy throughout the rest of Lesson 3. 


Create the Lesson 3 package 
Use this procedure if you're copying the completed Lesson 2. To copy the sample Lesson 2, see the next section. 


1. If SQL Server Data Tools isn't already open, select Start > All Programs > Microsoft SQL Server 
2017, and then select SQL Server Data Tools. 


2. On the File menu, select Open > Project/Solution, select the SSIS Tutorial folder and select Open, 
and then double-click SSIS Tutorial.sIn. 


3. In Solution Explorer, right-click Lesson 2.dtsx, and then select Copy. 
4. In Solution Explorer, right-click SSIS Packages, and then select Paste. 
By default, the name of the copied package is Lesson 3.dtsx. 
5. InSolution Explorer, double-click Lesson 3.dtsx to open the package 
6. Right-click anywhere in the background of the Control Flow design surface and select Properties. 
7. In the Properties window, change the Name property to Lesson 3. 


8. Select the box for the ID property, select the drop-down arrow, and then select <Generate New ID>. 


Add the completed Lesson 2 package 


1. Open SQL Server Data Tools and open the SSIS Tutorial project. 

2. InSolution Explorer, right-click SSIS Packages and select Add Existing Package. 

3. In the Add Copy of Existing Package dialog, in Package location, select File system. 

4. Select the browse (...) button, navigate to Lesson 2.dtsx on your machine, and then select Open. 


5. Copy and paste the Lesson 3 package as described in steps 3-8 in the previous section. 


Go to next task 


Step 2: Add and configure logging 


Lesson 3-2: Add and configure logging 
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In this task, you enable logging for the data flow in the Lesson 3.dtsx package. Then, you configure a Text File log 
provider to log the PipelineExecutionPlan and PipelineExecuteTrees events. The Text Files log provider creates 
logs that are easy to view and transport. The simplicity of these log files makes these files useful during the 
basic testing phase of a package. You can also view the log entries in the Log Events window of SSIS Designer. 


Add logging to the package 


1. On the SSIS menu, select Logging. 
In Visual Studio 2019, the SSIS menu is located under Extensions -> SSIS. Make sure you have the Data 
Flow tab selected and not Control Flow 


2. In the Configure SSIS Logs dialog, in the Containers pane, make sure the topmost object is selected. 
This object represents the Lesson 3 package. 


3. On the Providers and Logs tab, in the Provider type box, select SSIS log provider for Text files, 
and then select Add. 


Integration Services adds a new Text File log provider to the package, with the default name SSIS log 
provider for text files. You can now configure the new log provider. 


4. In the Name column, enter Lesson 3 Log File. 
5. Optionally, modify the Description. 


6. In the Configuration column, select <New Connection> to specify where Integration Services writes 
log information. 


In the File Connection Manager Editor dialog box, for Usage type, select Create file, and then select 
Browse. By default, the Select File dialog opens the project folder, but you can save log information to 
any location. 


7. In the Select File dialog, in the File name box enter TutorialLog.log and select Open. 
8. Select OK to close the File Connection Manager Editor dialog. 


9. In the Containers pane, expand all nodes of the package container hierarchy, and then clear all check 
boxes, including the Extract Sample Currency Data check box. Now select the check box for Extract 
Sample Currency Data to get only the events for this node. 





NOTE 


If the state of the Extract Sample Currency Data check box appears dimmed instead of selected, the task uses 
the log settings of the parent container and you cannot enable the log events that are specific to the task. To 
resolve this instance, clear the parent check box. 








10. On the Details tab, in the Events column, select the PipelineExecutionPlan and 
PipelineExecutionTrees events. 


11. Select Advanced to review the details that the log provider writes to the log for each event. By default, all 


information categories are automatically selected for the events you specify. 
12. Select Basic to hide the information categories. 


13. On the Provider and Logs tab, in the Name column, select Lesson 3 Log File. After you have created 
a log provider for your package, you can optionally deselect it to turn off logging, without having to 
delete and re-create a log provider. 


14. Select OK. 


Go to next task 


Step 3: Test the Lesson 3 package 


Lesson 3-3: Test the Lesson 3 tutorial package 
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In this task, you run the Lesson 3.dtsx package. As the package runs, the Log Events window lists the log 
entries that SSIS writes to the log file by the log provider. After the package finishes execution, you can view the 
contents of the log file. 


Check the package layout 


Before you test the package, verify the control and data flows in the Lesson 3 package resemble the objects 
shown in the following diagrams. The control flow should be the same as lesson 2, and the data flow should be 
the same as lessons 1 and 2. 


Control Flow 


| ] Foreach File in Folder 


we Extract Sample Currency Data 


Data Flow 


BP, Extract Sample Currency Data 


BE sample OLE De Destination 


Run the Lesson 3 tutorial package 


1. On the SSIS menu, select Log Events. 
2. On Debug menu, select Start Debugging. 


3. After the package has completed running, on the Debug menu, select Stop Debugging. 


Examine the generated log file 


e Using Notepad or any other text editor, open the TutorialLog.log file. 


e Acomplete description of the information generated for the PipelineExecutionPlan and 
PipelineExecutionTrees events is beyond the scope of this tutorial. In the log file, you can see that the 
first line lists the information fields specified in the Details tab of the Configure SSIS Logs dialog box. 
You can also see that Integration Services logged the two events that you selected, 
PipelineExecutionPlan and PipelineExecutionTrees, for each iteration of the Foreach Loop. 


Next lesson 


Lesson 4: Add error flow redirection with SSIS 


Lesson 4: Add error flow redirection with SSIS 
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To handle errors that may occur in the transformation process, Microsoft Integration Services lets you decide on 
a per-component and per-column basis how to handle data that Integration Services can't transform. You can 
choose to ignore a failure in certain columns, redirect the entire failed row, or fail the component. By default, 
components in Integration Services are configured to fail when errors occur. The failed component in turn 
causes the package to fail and processing then stops. 


Rather than letting failures stop package execution, you may configure and handle potential processing errors 
as they occur. One option is to ignore failures altogether so your package always runs successfully. You can also 
redirect the failed row to another processing path, where the data and the error can be persisted, examined, or 
reprocessed. 


In this lesson, you create a copy of the package that you developed in Lesson 3: Add logging with SSIS. Working 
with this new package, you create a corrupted version of one of the sample data files. The corrupted file causes a 
processing error to occur when you run the package. 


To handle the error data, you add and configure a Flat File destination that writes any failed rows to an error file. 


Before Integration Services writes error data to the file, you include a Script component that gets error 
descriptions. You then reconfigure the Lookup Currency Key transformation to redirect any data that couldn't be 
processed to the Script transformation. 


Prerequisites 





NOTE 


If you haven't already, see the Lesson 1 prerequisites. 





Lesson task 

This lesson contains the following tasks: 
e Step 1: Copy the Lesson 3 package 

e Step 2: Create a corrupted file 


e Step 3: Add error flow redirection 


Step 4: Add a Flat File destination 


e Step 5: Test the Lesson 4 tutorial package 


Start the lesson 


Step 1: Copy the Lesson 3 package 


Lesson 4-1: Copy the Lesson 3 package 
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In this task, you create a copy of the Lesson 3.dtsx package from Lesson 3. If you did not complete lesson 3, you 
can add the completed lesson 3 package that is included with the tutorial to the project, and then make a copy of 
it to work with. You use this new copy throughout the rest of Lesson 4. 


Create the Lesson 4 package 
Use this procedure if you're copying the completed Lesson 3. To copy the sample Lesson 3, see the next section. 


1. If SQL Server Data Tools isn't already open, select Start > All Programs > Microsoft SQL Server 
2017, and then select SQL Server Data Tools. 


2. On the File menu, select Open > Project/Solution, select the SSIS Tutorial folder and select Open, 
and then double-click SSIS Tutorial.sIn. 


3. In Solution Explorer, right-click Lesson 3.dtsx, and then select Copy. 
4. In Solution Explorer, right-click SSIS Packages, and then select Paste. 
By default, the name of the copied package is Lesson 4.dtsx. 
5. In Solution Explorer, double-click Lesson 4.dtsx to open the package 
6. Right-click anywhere in the background of the Control Flow design surface and select Properties. 
7. In the Properties window, change the Name property to Lesson 4. 


8. Select the box for the ID property, select the drop-down arrow, and then select <Generate New ID>. 


Add the completed Lesson 3 package 


1. Open SQL Server Data Tools and open the SSIS Tutorial project. 

2. InSolution Explorer, right-click SSIS Packages and select Add Existing Package. 

3. In the Add Copy of Existing Package dialog box, in Package location, select File system. 

4. Select the browse (...) button, navigate to Lesson 3.dtsx on your machine, and then select Open. 


5. Copy and paste the Lesson 3 package as described in steps 3-8 in the previous section. 


Go to next task 


Step 2: Create a corrupted file 


Lesson 4-2: Create a corrupted file 
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To demonstrate the configuration and handling of transformation errors, you need a sample flat file that, when 
processed, causes a component to fail. 


In this task, you create a copy of an existing sample flat file. You then open the file in Notepad and edit the 
CurrencylD column to contain an erroneous value, which fails the lookup. When the corrupted file is processed, 
the lookup failure causes the Currency Key Lookup transformation to fail and therefore fail the rest of the 
package. After you've created the corrupted sample file, you run the package to view the package failure. 


Create a corrupted sample flat file 


1. In Notepad or any other text editor, open the Currency_VEB.txt file. 
2. Use the text editor's find and replace feature to find all instances of VEB and replace them with BAD. 


3. In the same folder as the other sample data files, save the modified file as Currency_BAD.txt. 





NOTE 


Make sure that you save Currency_BAD.txt in the same folder as the other sample data files. 





4. Close your text editor. 


Verify that an error occurs during run time 


1. On the Debug menu, select Start Debugging. 


On the third iteration of the data flow, the Lookup Currency Key transformation tries to process the 
Currency_BAD.txt file, and the transformation fails. The failure of the transformation causes the whole 
package to fail. 


2. On the Debug menu, select Stop Debugging. 
3. On the design surface, select the Execution Results tab. 


4. Browse through the log and verify that the following unhandled error occurred: 


[Lookup Currency Key[27]] Error: Row yielded no match during lookup. 


NOTE 


The number 27 is the ID of the component. This value is assigned when you build the data flow, and the value in 


your package may be different. 





Go to next task 


Step 3: Add error flow redirection 


Lesson 4-3: Add error flow redirection 
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In the previous task, the Lookup Currency Key transformation cannot generate a match when the 
transformation tries to process the corrupted sample flat file, which produces an error. Because the 
transformation uses the default settings for error output, any error causes the transformation to fail. When the 
transformation fails, the rest of the package also fails. 


Rather than permitting the transformation to fail, you can configure the component to redirect the failed row to 
another processing path, by using the error output. Using a separate error processing path provides more 
options. For instance, you could clean the data and then reprocess the failed row. Or, you could save the failed 
row along with its error information for later verification and reprocessing. 


In this task, you configure the Lookup Currency Key transformation to redirect any rows that fail to the error 
output. In the error branch of the data flow, Integration Services writes these rows to a file. 


By default the two extra columns in an Integration Services error output, ErrorCode and ErrorColumn, contain 
only a numeric error code and the ID of the column in which the error occurred. In this task, before the package 
writes the failed rows to the file, you use a Script component to access the Integration Services API and get a 
description of the error. 


Configure an error output 


1. Inthe SSIS Toolbox, expand Common, and then drag Script Component onto the design surface of 
the Data Flow tab. Place Script to the right of the Lookup Currency Key transformation. 


2. In the Select Script Component Type dialog box, select Transformation, and select OK. 


3. To connect the two components, select the Lookup Currency Key transformation and then drag its red 
arrow onto the new Script transformation. 


The red arrow represents the error output of the Lookup Currency Key transformation. By using the 
red arrow to connect the transformation to the Script component, you redirect any processing errors to 
the Script component, which processes the errors and sends them to the destination. 


4. Inthe Configure Error Output dialog box, in the Error column, select Redirect row, and then select 
OK. 


5. On the Data Flow design surface, select the name Script Component in the new ScriptComponent, 
and change that name to Get Error Description. 


6. Double-click the Get Error Description transformation. 


7. Inthe Script Transformation Editor dialog box, on the Input Columns page, select the ErrorCode 
column. 


8. On the Inputs and Outputs page, expand Output 0, select Output Columns, and then select Add 
Column. 


9. In the Name property, enter ErrorDescription and set the DataType property to Unicode string 
[DT_WSTR]. 


10. On the Script page, verify that the LocalelD property is set to English (United States). 


11. Select Edit Script to open Microsoft Visual Studio Tools for Applications (VSTA). In the 
InputO_ProcessInputRow method, enter or paste the following code: 


[Visual Basic] 


Row.ErrorDescription = 
Me.ComponentMetaData.GetErrorDescription(Row.ErrorCode) 


[Visual C#] 
Row.ErrorDescription = this.ComponentMetaData.GetErrorDescription(Row.ErrorCode) ; 


The completed subroutine looks like the following code: 


[Visual Basic] 


Public Overrides Sub Input@_ProcessInputRow(ByVal Row As Input@Buffer) 


Row.ErrorDescription = 
Me .ComponentMetaData.GetErrorDescription(Row.ErrorCode) 


End Sub 
[Visual C#] 


public override void Input@_ProcessInputRow(Input@Buffer Row) 
{ 


Row.ErrorDescription = this.ComponentMetaData.GetErrorDescription(Row.ErrorCode) ; 


12. On the Build menu, select Build Solution to build the script and save your changes, and then close 
VSTA. 


13. Select OK to close the Script Transformation Editor dialog box. 


Go to next task 


Step 4: Add a Flat File destination 


Lesson 4-4: Add a Flat File destination 
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The error output of the Lookup Currency Key transformation redirects any data rows that failed the lookup to 
the Script transformation operation. To provide more information about the errors that occurred, the Script 
transformation runs a script that gets each error's description. 


In this task, you save all this information about the failed rows to a delimited text file for later processing. To 
save the failed rows, you add and configure a Flat File connection manager for the text file that contains the 
error data and a Flat File destination. By setting properties on the Flat File connection manager that the Flat File 
destination uses, you can specify how the Flat File destination formats and writes the text file. For more 
information, see Flat File connection manager and Flat File destination. 


Add and configure a Flat File destination 


1. Select the Data Flow tab. 


2. Inthe SSIS Toolbox, expand Other Destinations, and drag Flat File Destination onto the data flow 
design surface. Put the Flat File Destination directly underneath the Get Error Description 
transformation. 


3. Select the Get Error Description transformation, and then drag the blue arrow onto the new Flat File 
Destination. 


4. On the Data Flow design surface, select the name Flat File Destination in the new Flat File 
Destination transformation, and change that name to Failed Rows. 


5. Right-click the Failed Rows transformation, select Edit, and then in the Flat File Destination Editor, 
select New. 


6. In the Flat File Format dialog box, verify that Delimited is selected, and then select OK. 


7. Inthe Flat File Connection Manager Editor, in the Connection Manager Name box enter Error 
Data. 


8. In the Flat File Connection Manager Editor dialog box, select Browse, and locate the folder in which 
to store the file. 


9. In the Open dialog box, for File name, enter ErrorOutout.txt, and then select Open. 


10. In the Flat File Connection Manager Editor dialog box, verify that Locale is English (United 
States) and Code page is 1252 (ANSI-Latin 1). 


11. In the options pane, select Columns. 


In addition to the columns from the source data file, there are three new columns: ErrorCode, 
ErrorColumn, and ErrorDescription. These columns are the error output of the Lookup Currency Key 
transformation and the script in the Get Error Description transformation. You can use these columns to 
troubleshoot the cause of the failed row. 


12. Select OK. 


13. Inthe Flat File Destination Editor, clear the Overwrite data in the file check box. 


Clearing this check box persists the errors over multiple package executions by appending each new run's 
error output. 


14. In the Flat File Destination Editor, select Mappings to verify that all the columns are correct. Create 
mappings for any columns that are not mapped. Optionally, you can rename the columns in the 
destination. 


15. Select OK. 


Go to next task 


Step 5: Test the Lesson 4 tutorial package 


Lesson 4-5: Test the Lesson 4 package 
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At run time, the corrupted file Currency_BAD.txt fails to generate a match within the Currency Key Lookup 
transformation. Because you configured the error output of Currency Key Lookup to redirect failed rows to the 
new Failed Rows destination, the component doesn't fail, and the package runs successfully. Integration Services 
writes all failed error rows to ErrorOutput.txt. 


In this task, you test the revised error output configuration by running the package. After successful package 
execution, you view the contents of the ErrorOutput.txt file. 


NOTE 


If you don't want to accumulate error rows in the ErrorOutput.txt file, manually delete the file content between package 


runs. 





Check the package layout 


Before you test the package, verify that the control flow and the data flow in the Lesson 4 package are similar to 
the following diagrams: 


Control Flow 
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Run the Lesson 4 tutorial package 


1. On the Debug menu, select Start Debugging. 


2. After the package has completed running, on the Debug menu, select Stop Debugging. 


View the contents of the ErrorOutput.txt file 


In Notepad or any other text editor, open the ErrorOutput.txt file. The default column order is: AverageRate, 
CurrencylD, CurrencyDate, EndOfDateRate, ErrorCode, ErrorColumn, ErrorDescription. 


All the rows in the file contain the unmatched CurrencylD value "BAD", ErrorCode value -1071607778, 
ErrorColumn value 0, and ErrorDescription value "Row yielded no match during lookup". The value of 
ErrorColumn is 0 because the error isn't column-specific, rather, the lookup operation failed. 


Next lesson 


Lesson 5: Add SSIS package configurations for the package deployment model 


Lesson 5: Add SSIS package configurations for the 


Package Deployment Model 
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Package configurations let you set run-time properties and variables from outside the development 
environment. Configurations allow you to develop packages that are flexible and easy to both deploy and 
distribute. Microsoft Integration Services offers the following configuration types: 


e XML configuration file 
e@ Environment variable 

e Registry entry 

e Parent package variable 


e SQL Server table 


In this lesson, you modify the example Integration Services package that you created in Lesson 4: Add error flow 
redirection with SSIS to use the Package Deployment Model and take advantage of package configurations. You 
can also copy the completed Lesson 4 package included with this tutorial. 


Using the Package Configuration Wizard, you create an XML configuration that updates the Directory property 
of the Foreach Loop container. You use a package-level variable mapped to the Directory property. After you 
create the configuration file, you modify the value of the variable from outside the development environment to 
a new sample data folder path. When you run the package again, the configuration file populates the value of 
the variable, and the variable in turn updates the Directory property. The package then iterates through the 
files in the new data folder, rather than in the original hard-coded folder. 





NOTE 


If you haven't already, see the Lesson 1 prerequisites. 





Lesson tasks 


This lesson contains the following tasks: 

e Step 1: Copy the Lesson 4 package 

e Step 2: Enable and configure package configurations 

e Step 3: Modify the directory property configuration value 


e Step 4: Test the Lesson 5 package 


Start the lesson 


e Step 1: Copy the Lesson 4 package 


Lesson 5-1: Copy the Lesson 4 package 
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In this task, you create a copy of the Lesson 4.dtsx package from Lesson 4. If you did not complete lesson 4, 
you can add the completed lesson 4 package that is included with the tutorial to the project, and then make a 
copy of it to work with. You use this new copy throughout the rest of Lesson 5. 


Create the Lesson 5 package 
Use this procedure if you're copying the completed Lesson 4. To copy the sample Lesson 4, see the next section. 


1. If SQL Server Data Tools isn't already open, select Start > All Programs > Microsoft SQL Server 
2017, and then select SQL Server Data Tools. 


2. On the File menu, select Open > Project/Solution, select the SSIS Tutorial folder, and select Open. 
Then, double-click SSIS Tutorial.sIn. 


3. In Solution Explorer, right-click Lesson 4.dtsx and then select Copy. 
4. In Solution Explorer, right-click SSIS Packages and then select Paste. 
By default, the name of the copied package is Lesson 4.dtsx. 
5. In Solution Explorer, double-click Lesson 4.dtsx to open the package. 
6. Right-click anywhere in the background of the Control Flow design surface and select Properties. 
7. In the Properties window, change the Name property to Lesson 5. 


8. Select the box for the ID property, select the drop-down arrow, and then select <Generate New ID>. 


Add the completed Lesson 4 package 


1. Open SQL Server Data Tools and open the SSIS Tutorial project. 

2. InSolution Explorer, right-click SSIS Packages and select Add Existing Package. 

3. In the Add Copy of Existing Package dialog box, in Package location, select File system. 

4. Select the browse (...) button, navigate to Lesson 4.dtsx on your machine, and then select Open. 


5. Copy and paste the Lesson 4 package as described in steps 3-8 in the previous section. 


Go to next task 


Step 2: Enable and configure package configurations 


Lesson 5-2: Enable and configure package 


lo) nlite |Ule-lifelars 


11/23/2021 + 3 minutes to read * Edit Online 





Applies to: @ sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


In this task, you convert the project to the Package Deployment Model and enable package configurations using 
the Package Configuration Wizard. You use this wizard to generate an XML configuration file that contains 
configuration settings for the Directory property of the Foreach Loop container. The value of the Directory 
property is supplied by a new package-level variable that you can update at run time. You also populate a new 
sample data folder to use for testing. 


Create a package-level variable mapped to the Directory property 


1. Select the background of the Control Flow tab in SSIS Designer. This selection sets the scope for the 
variable you create to the package. 


2. On the SSIS menu, select Variables. 
3. In the Variables window, select the Add Variable icon. 


4. Inthe Name box, enter varFolderName. 





IMPORTANT 


Variable names are case-sensitive. 





5. Verify that the Scope box shows the name of the package, Lesson 5. 
6. Set the value of the Data Type box of the varFolderName variable to String. 
7. Return to the Control Flow tab and double-click the Foreach File in Folder container. 


8. On the Collection page of the Foreach Loop Editor, select Expressions and then select the ellipsis 
button (...). 


9. In the Property Expressions Editor, select in the Property list and then select Directory. 
10. In the Expression box, select the ellipsis button (...). 


11. In the Expression Builder, expand the Variables and Parameters folder and drag the variable 
User::varFolderName to the Expression box. 


12. Select OK to exit the Expression Builder. 
13. Select OK to exit the Property Expressions Editor. 


14. Select OK to exit the Foreach Loop Editor. 


Enable package configurations 


1. On the Project Menu, select Convert to Package Deployment Model. 


2. Select OK on the warning prompt and, once the conversion is complete, select OK in the Convert to 


10. 


Malls 


12. 


13; 


14. 


oe 


16. 


7. 


Package Deployment Model dialog box. 


. Select the background of the Control Flow tab in SSIS Designer. 
. On the SSIS menu, select Package Configurations. 


. Inthe Package Configurations Organizer dialog box, select Enable Package Configurations and 


then select Add. 


. On the welcome page of the Package Configuration Wizard, select Next. 


. On the Select Configuration Type page, verify that the Configuration type is set to XML 


configuration file. 


. On the Select Configuration Type page, select Browse. 


. The Select Configuration File Location dialog box opens to the project folder. 


In the Select Configuration File Location dialog box, for File name enter SSISTutorial and then 
select Save. 


On the Select Configuration Type page, select Next. 


On the Select Properties to Export page, in the Objects pane, expand Variables, expand 
varFolderName, expand Properties and then select Value. 


On the Select Properties to Export page, select Next. 


On the Completing the Wizard page, enter a configuration name for the configuration, such as SSIS 
Tutorial Directory configuration. The configuration name is displayed in the Package 
Configuration Organizer dialog box. 


Select Finish. 
Select Close. 


The wizard creates a configuration file, named SSIS Tutorial.dtsConfig, that contains configuration 
settings for the Value of the variable that in turn sets the Directory property of the enumerator. 





NOTE 


A configuration file typically contains complex information about the package properties, but for this tutorial the 


only configuration information should be as follows: 








<Configuration 
ConfiguredType="Property" 
Path="\Package.Variables[User: :varFolderName].Properties[Value]" 
ValueType="String"> 
<ConfiguredValue></ConfiguredValue> 
</Configuration> 


Create and populate a new sample data folder 


A, 


2: 


3 


In Windows Explorer, at the root level of your drive (for example, C:\), create a folder named New 
Sample Data. 


Locate the sample files on your computer and copy three of the files from the folder. 


In the New Sample Data folder, paste the copied files. 


Go to next task 


Step 3: Modify the Directory property configuration value 


Lesson 5-3: Modify the Directory property 


configuration value 
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In this task, you modify the configuration setting, stored in the SSIS Tutorial.dtsConfig file, to set the Value 
property of the package-level variable User::varFolderName . The variable updates the Directory property of the 
Foreach Loop container. The modified value points to the New Sample Data folder that you created in the 
previous task. After you modify the configuration setting and run the package, the Directory property is 
updated from the variable in the configuration file. Previously, the Directory property value was part of the 
package. 


Modify the configuration setting of the Directory property 


1. In Notepad or any other text editor, locate and open the SSIS Tutorial.dtsConfig configuration file that 
you created by using the Package Configuration Wizard in the previous task. 


2. Change the value of the ConfiguredValue element to match the path of the New Sample Data folder 
that you created in the previous task. Don't surround the path in quotes. If the New Sample Data folder 
is at the root level of your drive (for example, C:\), the updated XML should be similar to the following 
sample: 


<?xml version="1.0"?> 
<DTSConfiguration> 
<DTSConfigurationHeading> 
<DTSConfigurationFileInfo GeneratedBy="DOMAIN\UserName" GeneratedFromPackageName="Lesson 5" 
GeneratedFromPackageID="{F4475E73-59E3-478F -8EB2-B10AFEE1D3FA}" GeneratedDate="6/10/2018 8:16:50 
AM"/> 
</DTSConfigurationHeading> 
<Configuration ConfiguredType="Property” 
Path="\Package.Variables[User: :varFolderName].Properties[Value]" ValueType="String"> 
<ConfiguredValue>C:\New Sample Data</ConfiguredValue> 
</Configuration> 
</DTSConfiguration> 


The heading information GeneratedBy, GeneratedFromPackagelD, and GeneratedDate are different 
in your file. The element to note is the Configuration element. The Value property of the variable, 
User: :varFolderName , NOW contains C:\New Sam ple Data. 


3. Save the change, and then close the text editor. 


Go to next task 


Step 4: Test the Lesson 5 package 


Lesson 5-4: Test the Lesson 5 package 
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At run time, your package obtains the value for the Directory property from a configuration variable, rather 
than from the directory name specified when you created the package. The value of the variable comes from the 
SSISTutorial.dtsConfig XML file. 


To verify that the package updates the Directory property with the new value during run time, run the package. 
Because only three sample data files are in the new directory, the data flow runs only three times. 


Checking the Package Layout 


Before you test the package, verify that the control and data flows in the Lesson 5 package are similar to the 
objects shown in the following diagrams: 


Control Flow 


A Foreach File in Folder a 


we Extract Sample Currency Data 


Data Flow 
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Test the Lesson 5 package 


1. On the Debug menu, select Start Debugging. 


2. After the package has completed running, on the Debug menu, select Stop Debugging. 


Next lesson 


Lesson 6: Use parameters with the Project Deployment Model in SSIS 


Lesson 6: Use parameters with the Project 


Deployment Model in SSIS 
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SQL Server 2012 introduced a new deployment model where you can deploy your projects to the Integration 
Services server. The Integration Services server enables you to manage and run packages, and to configure 
runtime values for packages. 


In this lesson, you modify the package that you created in Lesson 5: Add SSIS package configurations for the 
Package Deployment Model to use the Project Deployment Model. You replace the configuration value with a 
parameter to specify the sample data location. You can also copy the completed Lesson 5 package that is 
included with the tutorial. 


By using the Integration Services Project Configuration Wizard, you convert the project to the Project 
Deployment Model. This model uses a parameter rather than a configuration value to set the Directory property. 
This lesson partially covers the steps you would follow to convert existing SSIS packages to the new Project 
Deployment Model. 


When you run the package again, the Integration Services server uses the parameter to populate the value of 
the variable. The variable in turn updates the Directory property. The package iterates through the files in the 
data folder specified by the new parameter. 





NOTE 


If you haven't already, see the Lesson 1 prerequisites. 





Lesson tasks 


This lesson contains the following tasks: 

1. Step 1: Copy the Lesson 5 package 

2. Step 2: Convert the project to the Project Deployment Model 
3. Step 3: Test the Lesson 6 package 


4. Step 4: Deploy the Lesson 6 package 


Start the lesson 


Step 1: Copy the Lesson 5 package 


Lesson 6-1: Copy the Lesson 5 package 
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In this task, you create a copy of the Lesson 5.dtsx package from Lesson 5. If you did not complete Lesson 5, 
you can add the completed Lesson 5 package included with the tutorial to the project, and then make a copy of 
it to work with. You use this new copy throughout the rest of Lesson 6. 


IMPORTANT 


After copying the Lesson 5 package, if you currently have the packages from the previous lessons in your solution, right- 
click each package from lessons 1-5 and select Exclude From Project. When done you should have only Lesson 


6.dtsx in your solution. 








Create the Lesson 6 package 
Use this procedure if you're copying the completed Lesson 5. To copy the sample Lesson 5, see the next section. 


1. If SQL Server Data Tools isn't already open, select Start > All Programs > Microsoft SQL Server 
2017, and then select SQL Server Data Tools. 


2. On the File menu, select Open > Project/Solution, select the SSIS Tutorial folder and select Open, 
and then double-click SSIS Tutorial.sIn. 


3. In Solution Explorer, right-click Lesson 5.dtsx, and then select Copy. 
4. In Solution Explorer, right-click SSIS Packages, and then select Paste. 
By default, the name of the copied package is Lesson 5.dtsx. 
5. In Solution Explorer, double-click Lesson 5.dtsx to open the package 
6. Right-click anywhere in the background of the Control Flow design surface and select Properties. 
7. In the Properties window, change the Name property to Lesson 6. 


8. Select the box for the ID property, select the drop-down arrow, and then select <Generate New ID>. 


Add the completed Lesson 5 package 


1. Open SQL Server Data Tools and open the SSIS Tutorial project. 

2. InSolution Explorer, right-click SSIS Packages and select Add Existing Package. 

3. In the Add Copy of Existing Package dialog box, in Package location, select File system. 

4. Select the browse (...) button, navigate to Lesson 5.dtsx on your machine, and then select Open. 


5. Copy and paste the Lesson 5 package as described in steps 3-8 in the previous section. 


Go to next task 


Step 2: Convert the project to the Project Deployment Model 


Lesson 6-2: Convert the project to the Project 


Deployment Model 
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In this task, you use the Integration Services Project Conversion Wizard to convert the project to the Project 
Deployment Model. 


1. On the Project menu, select Convert to Project Deployment Model. 


2. On the Integration Services Project Conversion Wizard Introduction page, review the steps and 
then select Next. 


3. On the Select Packages page, in the Packages list, clear all checkboxes except Lesson 6.dtsx, and then 
select Next. 


4. On the Specify Project Properties page, select Next. 
5. On the Update Execute Package Task page, select Next. 


6. On the Select Configurations page, make sure the Lesson 6.dtsx package is selected in the 
Configurations list, then select Next. 


7. On the Create Parameters page, make sure the Lesson 6.dtsx package is selected. Verify the Scope is 
Package in the Configuration Properties list, and then select Next. 


8. On the Configure Parameters page, verify that the values for Name and Value are the same ones 
specified in Lesson 5 for the variable and configuration value, then select Next. 


9. On the Review page, in the Summary pane, notice that the wizard used the information from the 
configuration file to set the Properties that are converted. 


10. Select Convert. 


After the conversion completes, you see a warning message that the changes aren't saved until you save 
the project. Select OK to close the warning dialog. 


11. On the Integration Services Project Conversion Wizard, select Close. 
12. InSQL Server Data Tools, select the File menu, then select Save to save the converted package. 


13. Select the Parameters tab and verify that the package now contains a parameter for VarFolderName. 
That parameter value is the same path specified for the New Sample Data folder in Lesson 5's 
configuration file. 


Go to next task 


Step 3: Test the Lesson 6 package 


Lesson 6-3: Test the Lesson 6 package 
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At run time, your package gets the value for the Directory property from the VarFolderName parameter. 


To verify that the package updates the Directory property, execute the package. Because you copied three 
sample data files to the new directory, the data flow runs three times. 


Check the package layout 


Before you test the package, verify that the control and data flows in the Lesson 6 package are similar to the 
objects shown in the following diagrams: 


Control Flow 
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Test the Lesson 6 package 
1. On the Debug menu, select Start Debugging. 


2. After the package has completed running, on the Debug menu, select Stop Debugging. 


Go to next task 


Step 4: Deploy the Lesson 6 package 
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Deploying the package involves adding the package to the SSISDB catalog in Integration Services on an instance 
of SQL Server. In this lesson, you add the Lesson 6 package to the SSISDB catalog, set the new parameter, and 
execute the package. For this lesson, you use SQL Server Management Studio to add the Lesson 6 package to 
the SSISDB catalog, and deploy the package. After deploying the package, you modify the parameter to point to 
a new location and then run the package. 

In this task, you: 


1. Add the package to the SSISDB catalog in the SSIS node in SQL Server. 
2. Deploy the package. 
3. Set the package parameter value. 


4. Execute the package in SSMS. 


Locate or add the SSISDB catalog 


1. Select Start > All Programs > Microsoft SQL Server 2017, and then select SQL Management 
Studio. 


2. On the Connect to Server dialog box, verify the default settings, and then select Connect. To connect, 
the Server name must be the name of the computer where SQL Server is installed. If the Database 
Engine is a named instance, the Server name must be the instance name in the format 


<computer_name>\<instance_name>. 
3. In Object Explorer, expand Integration Services Catalogs. 
4. If there are no catalogs listed under Integration Services Catalogs, then add the SSISDB catalog. 
5. To add the SSISDB catalog, right-click Integration Services Catalogs and select Create Catalog. 
6. On the Create Catalog dialog box, select Enable CLR Integration. 
7. In the Password box, enter a password and then enter it again in the Retype Password box. 


8. Select OK to add the SSISDB catalog. 


Add the package to the SSISDB catalog 


1. In Object Explorer, right-click SSISDB and select Create Folder. 

2. In the Create Folder dialog box, enter SSIS Tutorial in the Folder name box, and select OK. 

3. Expand the SSIS Tutorial folder, right-click Projects, and select Import Packages. 

4. On the Integration Services Project Conversion Wizard Introduction page, select Next. 


5. On the Locate Packages page, make sure that File system is selected in the Source list, then select 
Browse. 


6. On the Browse For Folder dialog box, browse to the folder containing this SSIS Tutorial project, then 


select OK. 
7. Select Next. 


8. On the Select Packages page, you should see all six packages from the SSIS Tutorial. In the Packages list, 
select Lesson 6.dtsx, then select Next. 


9. On the Select Destination page, enter SSIS Tutorial Deployment in the Project Name box then 
select Next. 


10. Select Next on each of the remaining wizard pages until you get to the Review page. 
11. On the Review page, select Convert. 
12. After the conversion completes, select Close. 


When you close the Integration Services Project Conversion Wizard, SSIS displays the Integration Services 
Deployment Wizard. You use this wizard now to deploy the Lesson 6 package. 


1. On the Integration Services Deployment Wizard Introduction page, review the steps for deploying 
the project, then select Next. 


2. On the Select Destination page, verify the server name is the instance of SQL Server containing the 
SSISDB catalog, and the path shows SSIS Tutorial Deployment, and then select Next. 


3. On the Review page, review the Summary then select Deploy. 
4. When the deployment completes, select Close. 
5. In Object Explorer, right-click Integration Services Catalogs and select Refresh. 


6. Expand Integration Services Catalogs then expand SSISDB. Continue to expand the tree under SSIS 
Tutorial until you have completely expanded the project. You should see Lesson 6.dtsx under the 
Packages node of the SSIS Tutorial Deployment node. 


7. To verify that the package is complete, right-click Lesson 6.dtsx and select Configure. On the 
Configure dialog box, select Parameters, and verify that there is an entry with Lesson 6.dtsx as the 
Container, VarFolderName as the Name, and the path to New Sample Data as the value, and then 
select Close. 


Create and populate a new sample data folder 


1. In Windows Explorer, at the root level of your drive (for example, C:\), create a folder named Sample 
Data Two. 


2. Open the Sample Data folder from the Lesson 1 prerequisites and then copy any three of the sample 
files. 


3. Browse to the Sample Data Two folder and paste the copied files. 


Change the package parameter to point to the new sample data 
1. In Object Explorer, right-click Lesson 6.dtsx, and select Configure. 


2. On the Configure dialog box, change the parameter value to the path to Sample Data Two, for 
example, C:\Sample Data Two. 


3. Select OK to close the Configure dialog box. 


Test the Lesson 6 package deployment 


1. In Object Explorer, right-click Lesson 6.dtsx and select Execute. 
2. On the Execute Package dialog box, select OK. 
3. On the message dialog box, select Yes to open the Overview Report. 


The Overview Report for the package displays the name of the package and a status summary. The Execution 
Overview section shows the result from each task in the package. The Parameters Used section shows the 
names and values of all parameters used in the package execution, including VarFolderName. 


Deploy Packages with SSIS 
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Microsoft SQL Server Integration Services provides tools that make it easy to deploy packages to another 
computer. The deployment tools also manage any dependencies, such as configurations and files that the 
package needs. In this tutorial, you will learn how to use these tools to install packages and their dependencies 
on a target computer. 


First, you will perform tasks to prepare for deployment. You will create a new Integration Services project in SQL 
Server Data Tools (SSDT) and add existing packages and data files to the project. You will not create any new 
packages from scratch; instead, you will work only with completed packages that were created just for this 
tutorial. You will not modify the functionality of the packages in this tutorial; however, after you have added the 
packages to the project, you might find it useful to open the packages in SSIS Designer and review the contents 
of each package. By examining the packages, you will learn about package dependencies such as log files and 
about other interesting features of the packages. 


In preparation for deployment, you will also update the packages to use configurations. Configurations make 
the properties of packages and package objects updatable at run time. In this tutorial, you will use 
configurations to update the connection strings of log and text files and the locations of the XML and XSD files 
that the package uses. For more information, see Package Configurations and Create Package Configurations. 


After you have verified that the packages run successfully in SQL Server Data Tools (SSDT), you will create the 
deployment bundle to use to install the packages. The deployment bundle will consist of the package files and 
other items that you added to the Integration Services project, the package dependencies that Integration 
Services automatically includes, and the deployment utility that you built. For more information, see Create a 
Deployment Utility. 


You will then copy the deployment bundle to the target computer and run the Package Installation Wizard to 
install the packages and package dependencies. The packages will be installed in the msdb SQL Server database, 
and the supporting and ancillary files will be installed in the file system. Because the deployed packages use 
configurations, you will update the configuration to use new values that enable packages to run successfully in 
the new environment. 


Finally, you will run the packages in SQL Server Management Studio by using the Execute Package Utility. 


It is the goal of this tutorial to simulate the complexity of real-life deployment issues that you may encounter. 
However, if it is not possible for you to deploy the packages to a different computer, you can still do this tutorial 
by installing the packages in the msdb database on a local instance of SQL Server, and then running the 
packages from SQL Server Management Studio on the same instance. 


Estimated time to complete this tutorial: 2 hours 


What You Learn 


The best way to become acquainted with the new tools, controls, and features available in Microsoft SQL Server 
Integration Services is to use them. This tutorial walks you through the steps to create an Integration Services 
project and then add the packages and other necessary files to the project. After the project is complete, you will 
create a deployment bundle, copy the bundle to the destination computer, and then install the packages on the 
destination computer. 


Prerequisites 


This tutorial is intended for users who are already familiar with fundamental file system operations, but who 
have limited exposure to the new features available in SQL Server Integration Services. To better understand 
basic Integration Services concepts that you will put to use in this tutorial, you might find it useful to first 
complete the following Integration Services tutorial: SSIS How to Create an ETL Package. 


On the source computer 


The computer on which you create the deployment bundle must have the following components installed: 


e@ SQL Server. (Download a free evaluation or developer edition of SQL Server from SQL Server 
downloads.) 


e Sample data, completed packages, configurations, and a Readme. To download the sample data and the 
lesson packages as a Zip file, see SQL Server Integration Services Tutorial Files. Most of the files in the Zip 
file are read-only to prevent unintended changes. To write output to a file or to change it, you may have 
to turn off the read-only attribute in the file properties. 


e The AdventureWorks2014 sample database. To download the AdventureWorks2014 database, 
download AdventureWorks2014.bak from AdventureWorks sample databases and restore the backup. 


e You must have permission to create and drop tables in the AdventureWorks database. 
e SQL Server Data Tools (SSDT). 


On the destination computer 


The computer to which you deploy packages must have the following components installed: 


e SQL Server. (Download a free evaluation or developer edition of SQL Server from SQL Server 
downloads.) 


e Sample data, completed packages, configurations, and a Readme. To download the sample data and the 
lesson packages as a Zip file, see SQL Server Integration Services Tutorial Files. Most of the files in the Zip 
file are read-only to prevent unintended changes. To write output to a file or to change it, you may have 
to turn off the read-only attribute in the file properties. 


e The AdventureWorks2014 sample database. To download the AdventureWorks2014 database, 
download AdventureWorks2014.bak from AdventureWorks sample databases and restore the backup. 


@ SQL Server Management Studio. 
e SQL Server Integration Services. To install SSIS, see Install Integration Services. 


e You must have permission to create and drop tables in the AdventureWorks database, and to run SSIS 
packages in SQL Server Management Studio. 


e You must have read and write permission on the sysssispackages table in the msdb SQL Server system 


database. 


If you plan to deploy packages to the same computer as the one on which you create the deployment bundle, 


that computer must meet requirements for both the source and destination computers. 


Lessons in This Tutorial 


Lesson 1: Preparing to Create the Deployment Bundle 
In this lesson, you will get ready to deploy an ETL solution by creating a new Integration Services project and 
adding the packages and other required files to the project. 


Lesson 2: Create the Deployment Bundle in SSIS 


In this lesson, you will build a deployment utility and verify that the deployment bundle includes the necessary 
files. 


Lesson 3: Install SSIS Packages 
In this lesson, you will copy the deployment bundle to the target computer, install the packages, and then run the 
packages. 


Lesson 1: Preparing to Create the Deployment 


BiUlarelts) 


11/23/2021 + 2 minutes to read * Edit Online 





Applies to: Q sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


In this lesson, you will create the working folders and environment variables that support the tutorial, create an 
Integration Services project, add several packages and their supporting files to the project, and implement 
configurations in packages. 


Integration Services deploys packages on a project basis; therefore, as the first step in creating the deployment 
bundle, you must collect all the packages and package dependencies into one Integration Services project. 
Frequently it is useful to include other information with the deployed packages: for example you will also add to 
the project a Readme file that provides basic documentation for this group of packages. 


After you have added the packages and files, you will add configurations to packages that do not already use 
configurations. The configurations update properties of packages and package objects at run time. In a later 
lesson, you will modify the values of these configurations during package deployment to support the packages 
in the deployed-to environment. 


After you have added the configurations, you should open the packages in SSIS Designer, the Integration 
Services graphical tool for building ETL packages, and examine the properties of packages and package 
elements as well as the package configurations to better understand the issues that the deployment needs to 
address. For example, one of the packages extracts data from text files, so the location of the data files must be 
updated before the deployed packages will run successfully. 


Estimated time to complete this lesson: 1 hour 


Lesson Tasks 


This lesson contains the following tasks: 


e@ Step 1: Creating Working Folders and Environment Variables 


Step 2: Creating the Deployment Project 


Step 3: Adding Packages and Other Files 


Step 4: Adding Package Configurations 


e Step 5: Testing the Updated Packages 


Start the Lesson 


Step 1: Creating Working Folders and Environment Variables 


Lesson 1-1 - Creating Working Folders and 
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In this task, you will create the working folder (C\Deploymenttutorial) and the new system environment 
variables ( DataTransfer and LoadXxMLData ) that you will use in later tutorial tasks. 


The working folder is at the root of the C drive. If you must use a different drive or location, you can do that. 
However, you need to note this location and then use it wherever the tutorial refers to the location of the 
DeploymenttTutorial working folder. 


In a later lesson, you will deploy packages that are saved to the file system to the sysssispackages table in the 
msdb SQL Server database. Ideally you will deploy the Integration Services packages to a different computer. If 
that is not possible, you can still learn a lot from doing this tutorial by deploying the packages to an instance of 
SQL Server that is on the local computer. The environment variables that are used on the local and destination 
computers have the same variable names, but different values are stored in the variables. For example, on the 
local computer, the value of the environment variable DataTransfer references the C\Deploymenttutorial folder, 
whereas on the target computer the environment variable DataTransfer references the 


C\Deploymenttutoriallnstall folder. 


If you plan to deploy to the local computer, you need to create only one set of environment variables; however, 
you will need to update the value of the environment variables to an appropriate value before you do the local 
deployment. 


If you plan to deploy the packages to a different computer, you must create two sets of environment variables: 
one set for the local computer, and one set for the destination computer. You can create only the variables for the 
source computer now, and create the variables for the destination computer later, but you must have both the 
folder and environment variables available on the destination computer before you can install the packages on 
that computer. 


To create the local working folder 


1. Right-click the Start menu, and click Explore. 

2. Click Local Disk (C:). 

3. On the File menu, point to New, and then click Folder. 
4. Rename New Folder to Deploymenttutorial. 


To create local environment variables 


1. On the Start menu, click Control Panel. 

2. In Control Panel, double-click System. 

3. In the System Properties dialog box, click the Advanced tab, and then click Environment Variables. 
4. Inthe Environment Variables dialog box, in the System variables frame, click New. 


5. In the New System Variable dialog box, type DataTransfer in the Variable name box, and 
C:\DeploymenttTutorial\datatransferconfig.dtsconfig in the Variable value box. 


6. Click OK. 


7. Click New again, and type LoadXML Data in the Variable name box, and 
C:\Deploymenttutorial\loadxmldataconfig.dtsconfig in the Variable value box. 


8. Click OK to exit the Environment Variables dialog box. 
9. Click OK to exit the System Properties dialog box. 


10. Optionally, restart your computer. If you do not restart the computer, the name of the new variable will 
not be displayed in the Package Configuration Wizard, but you can still use it. 


To create destination environment variables 


1. On the Start menu, click Control Panel. 

2. In Control Panel, double-click System. 

3. In the System Properties dialog box, click the Advanced tab, and then click Environment Variables. 
4. Inthe Environment Variables dialog box, in System variables frame, click New. 


5. Inthe New System Variables dialog box, type DataTransfer in the Variable name box, and 
C:\DeploymenttTutoriallnstall\datatransferconfig.dtsconfig in the Variable value box. 


6. Click OK. 


7. Click New again, and type LoadXMLData in the Variable name box, and 
C:\DeploymenttTutoriallnstall\loadxmldataconfig.dtsconfig in the Variable value box. 


8. Click OK to exit the Environment Variables dialog box. 
9. Click OK to exit the System Properties dialog box. 


10. Optionally, restart your computer. 


Next Task in Lesson 


Step 2: Creating the Deployment Project 
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In Integration Services, the deployable unit is an Integration Services project. Before you can deploy packages, 
you must create a new Integration Services project and add all the packages and any ancillary files that you 
want to deploy with the packages to that project. 


To create the Integration Services project 


1. Click Start, point to All Programs, point to Microsoft SQL Server, and then click SQL ServerSQL 
Server Data Tools. 


2. On the File menu, point to New, and then click Project to create a new Integration Services project. 
3. In the New Project dialog box, select Integration Services Project in the Templates pane. 


4. In the Name box, change the default name to Deployment Tutorial. Optionally, clear the Create 
directory for solution check box. 


5. Accept the default location, or click Browse to locate the folder you want to use. 
6. In the Project Location dialog box, click the folder, and then click Open. 
7. Click OK. 


8. By default, an empty package, named Package.dtsx, is created and added to your project. However, you 
will not use this package; instead, you will add existing packages to the project. Because all the packages 
in a project will be included in the deployment, you should delete Package.dtsx. To delete it, right-click it, 
and then click Delete. 


Next Task in Lesson 


Step 3: Adding Packages and Other Files 


See Also 


Integration Services (SSIS) Projects 


Lesson 1-3 - Adding Packages and Other Files 
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In this task, you will add existing packages, ancillary files that support individual packages, and a Readme to the 
Deployment Tutorial project that you created in the previous task. For example, you will add an XML data file 
that contains the data for a package and a text file that provides Readme information about all the packages in 
the project. 


When you deploy packages to a test or production environment, you typically do not include the data files in the 
deployment, but instead use configurations to update the paths of the data sources to access test or production 
versions of the data files or databases. For instructional purposes, this tutorial includes data files in the package 
deployment. 


The packages and the sample data that the packages use are installed when you install the SQL Server samples. 
You will add the following packages to the Deployment Tutorial project: 


e DataTransfer. Basic package that extracts data from a flat file, evaluates column values to conditionally 
keep rows in the dataset, and loads data into a table in the AdventureWorks database. 


e LoadXMLData. Data-transfer package that extracts data from an XML data file, evaluates and aggregates 
column values, and loads data into a table in the AdventureWorks database. 


To support the deployment of these packages, you will add the following ancillary files to the Deployment 
Tutorial project. 


PACKAGE FILE 
DataTransfer NewCustomers.txt 
LoadXMLData orders.xml and orders.xsd 


You will also add a Readme, which is a text file that provides information about the Deployment Tutorial project. 


The paths used in the following procedures assume that the SQL Server samples were installed in the default 
location, C:\Program Files\Microsoft SQL Server\120\Samples\Integration Services\. If you installed the samples 
to a different location, you should use that location instead in the procedures. 


In the next task, you will add configurations to the DataTransfer and LoadXMLData packages. All configurations 
are stored in XML files, and you will use a system environment variable to specify the location of the files. After 
you create the configuration files, you will add them to the project. 


To add packages to the Deployment Tutorial project 


1. If SQL Server Data Tools (SSDT) is not already open, click Start, point to All Programs, point to 
Microsoft SQL Server, and then click SQL Server Data Tools. 


2. On the File menu, click Open, click Project/Solution, click the Deployment Tutorial folder and click 
Open, and then double-click Deployment Tutorial.sin. 


3. In Solution Explorer, right-click Deployment Tutorial, click Add, and then click Existing Package. 


4. Inthe Add Copy of Existing Package dialog box, in Package location, select File System. 


5. Click the browse (...) button, navigate to C:\Program Files\Microsoft SQL 
Server\100\Samples\Integration Services Tutorial\Deploying Packages\Completed Packages, select 
DataTransfer.dtsx, and then click Open. 


6. Click OK. 


7. Repeat steps 3 - 6, and this time add LoadXMLData.dtsx, which is found in C:\Program Files\Microsoft 
SQL Server\100\Samples\Integration Services\Tutorial\Deploying Packages\Completed Packages. 


To add ancillary files to the Deployment Tutorial project 


1. In Solution Explorer, right-click Deployment Tutorial, click Add, and then click Existing Item. 


2. In the Add Existing Item - Deployment Tutorial dialog box, navigate to C:\Program Files\Microsoft 
SQL Server\100\Samples\Integration Services\Tutorial\Deployment Packages\Sample Data, select 
orders.xml, orders.xsd, and NewCustomers.txt, and then click Add. 


3. In the Add Existing Item - Deployment Tutorial dialog box, navigate to C:\Program Files\Microsoft 
SQL Server\100\Samples\Integration Services\Tutorial\Deployment Packages\, select Readme.txt and 
click Add. 


4. On the File menu, click Save All. 


Next Task in Lesson 


Step 4: Adding Package Configurations 


Lesson 1-4 - Adding Package Configurations 


11/23/2021 * 5 minutes to read « Edit Online 





Applies to: Q sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


In this task, you will add a configuration to each package. Configurations update the values of package 
properties and package objects at run time. 


Integration Services provides a variety of configuration types. You can store configurations in environment 
variables, registry entries, user-defined variables, SQL Server tables, and XML files. To provide additional 
flexibility, Integration Services supports the use of indirect configurations. This means that you use an 
environment variable to specify the location of the configuration, which in turn specifies the actual values. The 
packages in the Deployment Tutorial project use a combination of XML configuration files and indirect 
configurations. An XML configuration file can include configurations for multiple properties, and when 
appropriate, can be referenced by multiple packages. In this tutorial, you will use a separate configuration file for 
each package. 


Configuration files frequently contain sensitive information such as connection strings. Therefore, you should 
use an access control list (ACL) to restrict access to the location or folder where you store the files, and give 
access only to users or accounts that are permitted to run packages. For more information, see Access to Files 
Used by Packages. 


The packages (DataTransfer and LoadXMLData) that you added to the Deployment Tutorial project in the 
previous task need configurations to run successfully after they are deployed to the target server. To implement 
configurations, you will first create the indirect configurations for the XML configuration files, and then you will 
create the XML configuration files. 


You will create two configuration files, DataTransferConfig.dtsConfig and LoadXMLData.dtsConfig. These files 
contain name-value pairs that update the properties in packages that specify the location of the data and log 
files used by the package. Later, as a step in the deployment process, you will update the values in the 
configuration files to reflect the new location of the files on the destination computer. 


Integration Services recognizes that the DataTransferConfig.dtsConfig and LoadXMLData.dtsConfig are 
dependencies of the DataTransfer and LoadXMLData packages, and automatically includes the configuration files 
when you create the deployment bundle in the next lesson. 


To create indirect configuration for the DataTransfer package 


Check the project's current Deployment Model, and set it to Package Deployment Model, if needed. On the 
Project menu, click Convert to Package Deployment Model 


1. In Solution Explorer, double-click DataTransfer.dtsx. 
2. In SSIS Designer, click anywhere in the background of the control flow design surface. 
3. On the SSIS menu, click Package Configurations. 


4. In the Package Configuration Organizer dialog box, select Enable package configurations if it is 
not already selected, and then click Add. 


5. On the welcome page of the Package Configuration Wizard, click Next. 


6. On the Select Configuration Type page, select XML configuration file in the Configuration type list, 
select the Configuration location is stored in an environment variable option, and type 
DataTransfer, or select the DataTransfer environment variable in the list. 


To 


13. 


To 
1. 


2. 


3: 


4. 





NOTE 


To make the environment variable available in the list, you may have to restart your computer after adding the 


variable. If you do not want to restart the computer, you can type the name of the environment variable. 








. Click Next. 


. On the Completing the Wizard page, type DataTransfer EV Configuration in the Configuration 


name box, review the configuration contents in the Preview pane, and then click Finish. 


. Close the Package Configuration Organizer dialog box. 


create the XML configuration for the DataTransfer package 


. In Solution Explorer, double-click DataTransfer.dtsx. 
. In SSIS Designer, click anywhere in the background of the control flow design surface. 
. On the SSIS menu, click Package Configurations. 


. In the Package Configuration Organizer dialog box, select the Enable Package Configurations check- 


box, and then click Add. 


. On the welcome page of the Package Configuration Wizard, click Next. 


. On the Select Configuration Type page, select XML configuration file in the Configuration type list 


and then click Browse. 


. InSelect Configuration File Location dialog box, navigate to C\DeploymenttTutorial and type 


DataTransferConfig in the File name box, and then click Save. 


. On the Select Configuration Type page, click Next. 


. On the Select Properties to Export page, expand DataTransfer, Connection Managers, Deployment Tutorial 


Log, and Properties, and then select the Connection String check-box. 


. Within Connection Managers, expand NewCustomers, and then select the Connection String check-box. 
. Click Next. 


. On the Completing the Wizard page, type DataTransfer Configuration in the Configuration name 


box, review the content of the configuration, and then click Finish. 


In the Package Configuration Organizer dialog box, verify that DataTransfer EV Configuration is listed 
first, and DataTransfer Configuration is listed second, and then click Close. 


create indirect configuration for the LoadXMLData package 


In Solution Explorer, double-click LoadXMLData.dtsx. 
In SSIS Designer, click anywhere in the background of the control flow design surface. 
On the SSIS menu, click Package Configurations. 


In the Package Configuration Organizer dialog box, Click Add. 


. On the welcome page of the Package Configuration Wizard, click Next. 


. On the Select Configuration Type page, select XML configuration file in the Configuration type list, 


select the Configuration location is stored in an environment variable option, type 
LoadXMLData or select the LoadXMLData environment variable in the list. 





NOTE 


To make the environment variable available in the list, you may have to restart your computer after adding the 


variable. 








. Click Next. 


. On the Completing the Wizard page, type LoadXMLData EV Configuration in the Configuration 


name box, review the content of the configuration, and then click Finish. 


To create the XML configuration for the LoadXMLData package 


1. 


2. 


10. 


11. 


12. 


In Solution Explorer, double-click LoadXMLData.dtsx. 


In SSIS Designer, click anywhere in the background of the control flow design surface. 


. On the SSIS menu, click Package Configurations. 


. In the Package Configuration Organizer dialog box, select the Enable Package Configurations check- 


box, and click Add. 


. On the welcome page of the Package Configuration Wizard, click Next. 


. On the Select Configuration Type page, select XML configuration file in the Configuration type list 


and click Browse. 


. InSelect Configuration File Location dialog box, navigate to C\Deploymenttutorial and type 


LoadXMLDataConfig in the File name box, and then click Save. 


. On the Select Configuration Type page, click Next. 


. On the Select Properties to Export page, expand LoadXMLData, Executables, Load XML Data, and 


Properties, and then select the [XMLSource].[XMLData] and [XMLSource].[XMLSchemaDefinition] 
check boxes. 


Click Next. 


On the Completing the Wizard page, type LoadXMLData Configuration in the Configuration name 
box, review the content of the configuration, and then click Finish. 


In the Package Configuration Organizer dialog box, verify that the LoadXMLData EV Configuration is 
listed first, and the LoadXMLData Configuration is listed second, and then click Close. 


Next Task in Lesson 


Step 5: Testing the Updated Packages 
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Package Configurations 


Create Package Configurations 


Access to Files Used by Packages 
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Before you go on to the next lesson, in which you will create the deployment bundle to use to install the tutorial 
packages on the destination computer, you should test the packages. In this task, you will run the packages, 
DataTransfer.dtsx and LoadXMLData, that you added to the Deployment Tutorial project and then extended with 
configurations. 


When the packages run, each executable in the package becomes a green color as it completes successfully. 
When all executables are green, the package has completed successfully. You can also view the package 
execution progress on the Progress tab. 


If the packages do not run successfully, you must fix them before you go on to the next lesson. 


To run the DataTransfer package 


1. In Solution Explorer, click DataTransfer.dtsx. 
2. On Debug menu, click Start Debugging. 
3. After the package has completed running, on the Debug menu, click Stop Debugging. 


To run the LoadXML Data package 
1. In Solution Explorer, click LoadXMLData.dtsx. 


2. On Debug menu, click Start Debugging. 


3. After the package has completed running, on the Debug menu, click Stop Debugging. 


Next Lesson 


Lesson 2: Create the Deployment Bundle in SSIS 
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In Lesson 1: Preparing to Create the Deployment Bundle, you created the Integration Services project named 
Deployment Tutorial, added the packages and supporting files to the project, and implemented configurations in 
packages. 


In this lesson, you will create the deployment bundle, which is a folder that contains the items that you need to 
install packages on another computer. The deployment bundle will include a deployment manifest, copies of the 
packages, and copies of the supporting files from the Deployment Tutorial project. The deployment manifest 
lists the packages, miscellaneous files, and configurations in the deployment bundle. 


You will also verify the file list in the deployment bundle and examine the contents of the manifest. 


Estimated time to complete this lesson: 30 minutes 


Lesson Tasks 
This lesson contains the following tasks: 
e Step 1: Building the Deployment Utility 


® Step 2: Verifying the Deployment Bundle 


Start the Lesson 


Step 1: Building the Deployment Utility 
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In this task, you will configure and build a deployment utility for the Deployment Tutorial project. 


Before you can build the deployment utility, you must modify the properties of the Deployment Tutorial project. 
You will use the Deployment Tutorial Property Pages dialog box to configure these properties. In this dialog 
box, you must enable the ability to update configurations during deployment and specify that the build process 

generates a deployment utility. After you set the properties, you will build the project. 


SQL Server Data Tools (SSDT) provides a set of windows that you can use to debug packages. You can view error, 
warning, and information messages, track about the status of packages at run time, or view the progress and 
results of build processes. For this lesson, you will use the Output window to view the progress and results of 
building the deployment utility. 


To set the deployment utility properties 


1. If SQL Server Data Tools (SSDT) is not already open, click Start, point to All Programs, point to 
Microsoft SQL Server, and then click Business Intelligence Development Studio. 


2. On the File menu, click Open, click Project/Solution, click the Deployment Tutorial folder and click 
Open, and then double-click Deployment Tutorial.sin. 


3. In Solution Explorer, right-click Deployment Tutorial and click Properties. 


4. Inthe Deployment Tutorial Property Pages dialog box, expand Configuration Properties, and click 
Deployment Utility. 


5. In the right pane of the Deployment Tutorial Property Pages dialog box, verify that 
AllowConfigurationChanges is set to true, set CreateDeploymentUtility to true, and optionally 
update the default value of DeploymentOutputPath. 


6. Click OK. 


To build the deployment utility 


1. In Solution Explorer, click Deployment Tutorial. 


2. On the View menu, click Output. By default, the Output window is located in the bottom left corner of 
SQL Server Data Tools (SSDT). 


3. On the Build menu, click Build Deployment Tutorial. 

4. In the Output window, verify the following information: 
Build started: SQL Integration Services project: Incremental ... 
Creating deployment utility... 
Deployment Utility created. 


Build complete -- 0 errors, 0 warnings 


5. On the File menu, click Exit. If prompted to save changes to Deployment Tutorial items, click Yes. 


Next Task in Lesson 


Step 2: Verifying the Deployment Bundle 


See Also 


Create a Deployment Utility 
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In lesson 1, you created the Deployment Tutorial project and added packages and ancillary files to the project; in 
the previous task you built a deployment utility for the project. 


In this task, you will verify the contents of the deployment bundle. The deployment bundle is the folder that you 
will copy to the destination computer and use to install packages. If you used the default value-bin\Deployment- 
as the location of the deployment utility, the deployment bundle is the Bin\Deployment folder within the 
Deployment Tutorial folder in the Integration Services project. 


To verify the content of deployment bundle 


1. Locate the bin\Deployment folder on your computer. 
2. Verify that the following files are present: 

e DataTransfer.dtsx 

e datatransferconfig.dtsconfig 

e Deployment Tutorial.SSISDeploymentManifest 

e@ LoadXMLData.dtsx 

e loadxmldataconfig.dtsconfig 

e@ NewCustomers.txt 

e orders.xml 

e orders.xsd 

e Readme.txt 


3. Right-click Deployment Tutorial.SSISDeploymentManifest, point to Open With, and then click Internet 
Explorer. You can also open the file in a text editor such as Notepad. The XML code of the file should be 
the following: 

<?xml version="1.0"?><DTSDeploymentManifest GeneratedBy="Domain\UserName" 
GeneratedFromProjectName="Deployment Tutorial" GeneratedDate="2006-02-24T13:29:02.6537669-08:00" 
AllowConfigurationChanges="true"><Package>DataTransfer.dtsx</Package> 

<Package>LoadXMLData. dtsx</Package><ConfigurationFile>datatransferconfig.dtsconfig</ConfigurationFile> 
<ConfigurationFile>loadxmldataconfig.dtsconfig</ConfigurationFile> 
<MiscellaneousFile>Readme.txt</MiscellaneousFile><MiscellaneousFile>orders.xml</MiscellaneousFile> 


<MiscellaneousFile>NewCustomers.txt</MiscellaneousFile> 
<MiscellaneousFile>orders.xsd</MiscellaneousFile></DTSDeploymentManifest> 


4. Verify that the value of the AllowConfigurationChanges attribute is true and the XML includes a 
Package element for each of the two packages, a MiscellaneousFile element for each of the four non- 
package files, and a ConfigurationFile element for each of the two XML configuration files. 


5. Exit Internet Explorer or the text editor. 


Next Lesson 


Lesson 3: Install SSIS Packages 
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In Lesson 2: Create the Deployment Bundle in SSIS, you built a deployment utility and created the deployment 
bundle that contains the items that you must install packages on another computer. You also verified the file list 
in the deployment bundle and examined the contents of the manifest file that was created when you built the 
deployment utility. 


In this lesson, you will copy the deployment bundle to the destination computer and then run the Package 
Installation Wizard to install the packages, package dependencies, and ancillary files on that computer. The 
packages will be installed in the msdbSQL Server database and the other items will be installed in the file 


system. After you complete the package installation, you will test the deployment by running the packages from 
SQL Server Management Studio using the Execute Package Utility. 


Estimated time to complete this lesson: 30 minutes 


Lesson Tasks 

This lesson contains the following tasks: 

e Step 1: Copying the Deployment Bundle 

e@ Step 2: Running the Package Installation Wizard 


e Step 3: Testing the Deployed Packages 


Start the Lesson 


Step 1: Copying the Deployment Bundle 
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In this task, you will copy the deployment bundle to the destination computer. 


The easiest way to copy the deployment bundle to the destination computer is to first create a public share on 
the destination computer, map a drive to the public share, and then copy the deployment bundle to the share. If 
you do not know how to create and configure public folders or map drives, see the Windows documentation. 


To copy the deployment bundle 


1. Locate the deployment bundle on your computer. 


If you used the default location, the deployment bundle is the Bin\Deployment folder within the 
Deployment Tutorial folder. 


2. Right-click the Deployment folder and click Copy. 


3. Locate the public share to which you want to copy the folder on the target computer and click Paste. 


Next Task in Lesson 


Step 2: Running the Package Installation Wizard 


Lesson 3-2 - Running the Package Installation 
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Applies to: Q sal Server (all supported versions) @ ssis Integration Runtime in Azure Data Factory 


In this task, you will run the Package Installation Wizard to deploy the packages from the Deployment Tutorial 
project to an instance of SQL Server. Only packages can be installed in the sysssispackages table in the msdb 
SQL Server database, the supporting files that the deployment bundle includes will be deployed to the file 
system. 


The Package Installation Wizard will guide you through the steps to install and configure the packages. You will 
install the packages to an instance of SQL Server on the destination computer (the computer to which you 
copied the deployment bundle. You will also create a folder, C\DeploymenttTutoriallnstall, in which the wizard 
will install the non-package files. 


In an earlier lesson, you modified the packages in the tutorial to use configurations. Using the Package 
Installation Wizard, you will edit these configurations to enable packages to run successfully in the installed-to 
environment. 


To install the packages 


1. On the destination computer, locate the deployment bundle. 


If you used the default value-bin\Deployment-as the location of the deployment utility, the deployment 
bundle is the Deployment folder in the Deployment Tutorial project. 


2. In the Deployment folder, double-click the manifest file, Deployment Tutorial.SSISDeploymentManifest. 
3. On the Welcome page of the Package Installation Wizard, click Next. 


4. On the Deploy SSIS Packages page, select the SQL Server deployment option, select the Validate 
packages after installation check box, and then click Next. 


5. On the Specify Target SQL Server page, specify (local), in the Server name box. 


6. If the instance of SQL Server supports Windows Authentication, select Use Windows Authentication; 
otherwise, select Use SQL Server Authentication and provide a user name and a password. 


7. Verify that the Rely on server storage for encryption check box is cleared. 
8. Click Next. 
9. On the Select Installation Folder page, click Browse. 
10. In the Browse For Folder dialog box, expand My Computer and then click Local Disk (C:). 


11. Click Make New Folder and replace the default name of the new folder, New Folder, with 
Deploymenttutoriallnstall. 





IMPORTANT 


This name is referenced in the value of the environment variables that configurations use. The name of the folder 
and the reference must match or the package cannot run. 








12. Click OK. 


13. On the Select Installation Folder page, verify that the Folder box contains C:\DeploymenttTutoriallnstall 
and then click Next. 


14. On the Confirm Installation page, click Next. 


The wizard installs the packages. After installation is completed, the Configure Packages page opens. 


15. On the Configure Packages page, verify that the Configuration file box lists 


datatransferconfig.dtsconfig and loadxmldataconfig.dtsconfig. 


16. In the Configuration file list, click datatransferconfig.dtsconfig, expand Property in the Path column 


of the Configurations box, and update the Value column with the following values: 


PROPERTY 


\Package.Connections[Deployment 
Tutorial 
Log].Properties[ConnectionString] 


\Package.Connections[NewCustome 
rs].Properties[ConnectionString] 


VALUE 


C:\Program Files\Microsoft SQL 
Server\100\Samples\Integration 
Services\Tutorial\Deploying 
Packages\Completed 
Packages\Deployment Tutorial Log 


C:\Program Files\Microsoft SQL 
Server\100\Samples\Integration 
Services\Tutorial\Deploying 
Packages\Sample 
Data\NewCustomers.txt 


UPDATED VALUE 


C:\DeploymentTutoriallnstall\Deploy 
ment Tutorial Log 


C:\DeploymentTutoriallnstall\NewCu 
stomers.txt 


17. In the Configuration file list, click loadxmldataconfig.dtsconfig, expand Property in the Path column of 


the Configurations box, and update the Value column with the following values: 


PROPERTY 


\Package.LoadXMLData.Properties|[ 
XML Source].[XMLData]] 


\Package.LoadXMLData.Properties|[ 
XML Source]. 
[XMLSchemaDefinition]] 


VALUE 


C:\Program Files\Microsoft SQL 
Server\100\Samples\Integration 
Services\Tutorial\Deploying 
Packages\Sample Data\orders.xml 


C:\Program Files\Microsoft SQL 
Server\100\Samples\Integration 
Services\Tutorial\Deploying 
Packages\Sample Data\orders.xsd 


UPDATED VALUE 


C:\DeploymentTutoriallnstall\orders. 
xml 


C:\DeploymentTutoriallnstall\orders. 
xsd 


18. On the Package Validation page, view the validation results of each package installed and then click Next. 


Because the values of the environment variables on the destination computer differ from the values of 


the environment variables on the development computer, several warnings appear on the Package 


Validation page. You should expect four warnings: 


The configuration file: "C\DeploymenttTutorial\DataTransferConfig.dtsConfig" is not valid. Check 


the configuration file name. 


Failed to load at least one of the configuration entries in the package. Check configuration entries 


and previous warnings to see description of which configuration failed. 


The configuration file: "C\\DeploymentTutorial\LoadXMLDataConfig.dtsConfig is not valid. Check 


the configuration file name. 


Failed to load at least one of the configuration entries in the package. Check configuration entries 


and previous warnings to see description of which configuration failed. 
These warnings do not affect package installation. 


If you did not select the Validate packages after installation option on the Deploy SSIS Packages 
page, the Package Validation pages does not open and the wizard does not display post-installation 
information about validation. 


19. On the Finish the Package Installation Wizard page, read the installation summary and then click Finish. 





NOTE 


A temporary log file is created to use in the package validation. This file is not used when the package runs. 





Next Task in Lesson 


Step 3: Testing the Deployed Packages 


See Also 


Integration Services Service (SSIS Service) 
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In this task, you will test the packages that you deployed to an instance of SQL Server. 


In other Integration Services tutorials, you ran packages in SQL Server Data Tools (SSDT), the development 
environment for Integration Services, using the Start Debugging option on the Debug menu. This time you 
will run the packages differently. 


Integration Services provides several tools that you can use to run packages in the test and production 
environment: the command prompt utility dtexec and the Execute Package Utility. The Execute Package Utility is 
a graphical tool that is built on dtexec. Both of these tools execute the package immediately. In addition, SQL 
Server provides a subsystem of SQL Server Agent that is especially designed for scheduling package execution 
as a step in a SQL Server Agent job. 


You will use the Execute Package Utility to run the deployed packages. The packages will be used as is; therefore, 
you do not have to update information on any pages in the dialog box. You will run the packages from the 
General page, which is the first page in the Execute Package Utility. If you like, you can click the other pages too 
see the information that they contain for each package. 





NOTE 


To ensure that the packages run successfully in the context of this tutorial, you should not modify any options. 





Before you run packages in SQL Server Management Studio by using the Execute Package Utility, ensure that the 


Integration Services service is running. The Integration Services service provides support for package storage 
and execution. If the service is stopped, you cannot connect to Integration Services and SQL Server 
Management Studio does not list the packages to run. You also must have permissions to run the package on 
the instance where the package has been deployed. For more information, see Integration Services Roles (SSIS 
Service). 


The top-level folders within the Stored Packages folder are the user-defined folders that Integration Services 
service monitors. You can specify as many or few folders in the MsDtsSrvr.ini.xml file as you want. This tutorial 
assumes that you are using the default MsDtsSrvrini.xml file, and that the names of the top-level folders within 
Stored Packages are File System and MSDB. 


To connect to Integration Services in SQL Server Management Studio 


1. Click Start, point to All Programs, point to Microsoft SQL Server, and then click SQL Server 
Management Studio. 


2. Inthe Connect to Server dialog box, select Integration Services in the Server type list, provide a 
server name in the Server name box, and click Connect. 





IMPORTANT 


If you cannot connect to Integration Services, the Integration Services service is likely not running. To learn the 
status of the service, click Start, point to All Programs, point to Microsoft SQL Server, point to 
Configuration Tools, and then click SQL Server Configuration Manager. In the left pane, click SQL Server 
Services. In the right pane, find the Integration Services service. Start the service if it is not already running. 








SQL Server Management Studio opens. By default the Object Explorer window is open and placed in the 
upper right corner of the studio. If Object Explorer is not open, click Object Explorer on the View menu. 


To run the packages using the Execute Package Utility 
1. In Object Explorer, expand the Stored Packages folder. 


2. Expand the MSDB folder. Because you deployed the packages to SQL Server, all the deployed packages 
are stored in the msdb SQL Server database, and all deployed packages appear in the MSDB folder. The 
File System folder is empty, unless you have deployed packages to the file system outside of the 
Deployment Tutorial. 


3. Starting at the top of the package list, right-click DataTransfer, and click Run Package. 
4. In the Execute Package Utility dialog box, click Execute. 


5. In the Execute Package Utility dialog box, view the progress and execution results of the package. 
When the Stop button becomes unavailable, which indicates that the package has completed, click Close. 





IMPORTANT 


If you click Stop while the package is running, the package will not finish. 





6. In the Execute Package Utility dialog box, click Close. 
7. Repeat steps 3 - 6 for the LoadXML package. 
8. On the File menu, click Exit. 


To verify the results of the DataTransfer package 


1. On the toolbar in SQL Server Management Studio, click New Query. 


2. Inthe Connect to Server dialog box, select Database Engine in the Server type list, provide the 
name of the server name on which you installed the tutorial packages or type (local) in the Server name 
box, and select an authentication mode. If using SQL Server Authentication, provide a user name and 
password. 


3. Click Connect. 

4. In the query window, type or paste the following SQL statement: 
USE AdventureWorks 
SELECT * FROM HighIncomeCustomers 

5. Press F5 or click the Execute icon on the toolbar. 


The query returns 31 rows of data. The return result contains any rows from the text file, Customers.txt, 
that have values larger than 100000 in the Yearlylncome column. 


6. Locate the Deploymenttutorial folder, right-click the log XML file, Deployment Tutorial Log, and then click 
Open. You can open the file by using Notepad or the text/XML editor of choice. 


To verify the results of the LoadXMLData package 


1. On the toolbar in SQL Server Management Studio, click New Query. 


2. If prompted to connect again, in the Connect to Server dialog box, select Database Engine in the 
Server type list, provide the name of the server on which you installed the tutorial packages or enter 
(local) in the Server name box, and select an authentication mode. If using SQL Server Authentication, 
provide a user name and password. 


3. Click Connect. 

4. In the query window, type or paste the following SQL statement: 
USE AdventureWorks 
SELECT * FROM OrderDatesByCountryRegion 

5. Press F5 or click the Execute icon on the toolbar. 


The query returns 21 rows of data. The return result consists of the rows from the XML data file, 
orders.xml. Each row is a summary by country/region; the row lists the name of a country/region, the 
number of orders for each country/region and the dates of the newest and oldest orders. 


See Also 


dtexec Utility 


